Search ENCODE metadata — encode_search • encodeUtils

Find ENCODE experiments, files, or other records. The search returns matching metadata rows and the total number of matches. It does not download data files.

Usage

encode_search(
  type = "Experiment",
  filters = list(),
  search = NULL,
  organism = NULL,
  assay = NULL,
  assay_type = NULL,
  biosample = NULL,
  biosample_type = NULL,
  organ = NULL,
  cell = NULL,
  system = NULL,
  life_stage = NULL,
  sex = NULL,
  disease = NULL,
  treatment = NULL,
  cellular_component = NULL,
  development = FALSE,
  exclude_controls = FALSE,
  target = NULL,
  target_category = NULL,
  file_format = NULL,
  output_type = NULL,
  assembly = NULL,
  status = "released",
  limit = 25,
  metadata = c("full", "basic"),
  include_facets = TRUE,
  quiet = FALSE
)

Arguments

type: ENCODE object type to search, such as "Experiment" or "File". Use "Experiment" to find datasets and "File" to find individual files. Use NULL only for mixed free-text searches.
filters: Named list of ENCODE search filters. ENCODE field names, dot notation, and negated filters such as "control_type!=" are accepted.
search: Optional free-text search term.
organism: Optional organism filter. Common values such as "mouse", "human", "Mus musculus", and "Homo sapiens" are accepted.
assay: Optional assay filter. Common values such as "rna-seq", "atac-seq", "chip-seq", "histone chip-seq", and "tf chip-seq" are expanded to ENCODE assay names.
assay_type: Optional broad assay category, such as "Transcription", "DNA accessibility", or "DNA binding".
biosample: Optional biosample or tissue term. This is added to the free-text query so broader terms such as "brain" can find forebrain, midbrain, hindbrain, cortex, and related ENCODE biosample terms.
biosample_type: Optional biosample class, such as "tissue", "cell line", "primary cell", or "organoid".
organ: Optional organ facet, such as "brain", "heart", or "liver".
cell: Optional cell facet, such as "T cell", "neural cell", or "stem cell".
system: Optional anatomical system facet, such as "immune system" or "central nervous system".
life_stage: Optional life-stage filter, such as "embryonic", "postnatal", "adult", or "fetal". "fetal" is treated as "embryonic" for ENCODE mouse development searches.
sex: Optional sex filter, such as "female", "male", or "mixed".
disease: Optional disease term.
treatment: Optional biosample-treatment term.
cellular_component: Optional subcellular fraction term, such as "nucleus" or "cytosol".
development: If TRUE, restrict experiments to organism-development series records.
exclude_controls: If TRUE, remove ENCODE control experiments from the search result.
target: Optional ChIP-seq target label, such as "TBX5" or "H3K27ac".
target_category: Optional target category, such as "histone" or "transcription factor".
file_format: Optional file-format filter used when type = "File", such as "fastq", "bed", "bigWig", or "tsv".
output_type: Optional file-output filter used when type = "File", such as "reads", "gene quantifications", or "IDR ranked peaks".
assembly: Optional genome-assembly filter used when type = "File", such as "GRCh38" or "mm10".
status: Optional ENCODE status filter. The default keeps released records only. Use NULL to omit the status filter.
limit: Number of records to return, or the explicit string "all". For biological File searches, "all" also explicitly permits expansion across more than 25 matching parent experiments.
metadata: Amount of linked metadata to request. "full" gives richer lab, organism, biosample, and target columns. "basic" requests fewer fields.
include_facets: Whether to keep ENCODE facet counts in the result object for verbose printing.
quiet: If FALSE, print a concise query status message.

Value

An encode_search_result object. The object contains results, the flattened result table; raw, the parsed ENCODE response including @graph; total, the total number of matching records reported by ENCODE; filters, the active filter table; facets, ENCODE facet counts when requested; columns, response column metadata; query_url; metadata; frame; the primary request metadata; and request_history, which records every ENCODE request used to construct the result. Use encode_results() to extract results.

Details

The result prints as a compact table. Use encode_results() to extract the table. Use print(x, verbose = TRUE) to show the query URL, active filters, and ENCODE facets.

File searches with biological filters such as organism, biosample, organ, target, or assay first search matching ENCODE Experiment records and then query files attached to those experiments. File-format filters are applied to the attached File records. Limited File searches refuse to expand more than 25 parent experiments. Narrow the biological filters or use limit = "all" only when a complete File search is intended.

Examples

experiments <- encode_search(
    organism = "mouse",
    assay = "rna-seq",
    organ = "heart",
    limit = 1,
    quiet = TRUE
)

encode_results(experiments)
#> ENCODE experiments
#> - experiments: 1
#> Experiments:
#>   experiment         assay     organism biosample biosample_type
#>  ENCSR389GJZ total RNA-seq Mus musculus     heart         tissue
#>                age  sex                                     sample
#>  adult 8-10 months male male adult (8-10 months) strain B6CASTF...
#>                    lab project files date_released   status
#>  Barbara Wold, Caltech  ENCODE    20    2022-11-09 released