Read a local ENCODE file — encode

Read one or more files that are already on disk. Small tabular and JSON files are loaded directly. Genomic interval and sequence formats use optional Bioconductor readers when they are installed. Large or unsupported formats return a path object by default.

Usage

encode_read(
  path,
  format = NULL,
  max_size = "100MB",
  region = NULL,
  allow_large = FALSE,
  unsupported = c("return_path", "error"),
  as = c("auto", "data.frame", "GRanges", "path", "SummarizedExperiment"),
  row_names = c("gene_symbol", "gene_id", "ensembl_id", "entrez_id", "none"),
  values = "raw_counts",
  simplify_quant = TRUE,
  ...
)

Arguments

path: Local file path, downloaded-file table, or file table with a local_path column.
format: Optional file format override.
max_size: Maximum uncompressed size to read into memory, as bytes or a string. Compressed text inputs are scanned before import.
region: Optional genomic range object passed to rtracklayer::import() as which for indexed genomic formats.
allow_large: Whether to allow full import of indexed formats such as bigWig or bigBed without region.
unsupported: What to do for unsupported formats. Use "return_path" to return an encode_local_file path object, or "error" to fail.
as: Return type. "auto" uses Bioconductor classes for genomic formats, including GRanges for BED-like intervals. Use "data.frame" to force tabular BED-like output, "GRanges" to require genomic ranges for BED-like formats, or "path" to return an encode_local_file path object. For a downloaded-file table, use "SummarizedExperiment" to return aligned expression matrices with feature and file metadata in a SummarizedExperiment.
row_names: Identifier column to prefer for expression-table row names. If that column is unavailable, the complete feature identifier used to assemble the matrix is retained. Use "none" to omit row names.
values: Expression values to combine across files. Defaults to "raw_counts". Use values such as "tpm", "fpkm", or "rpkm" when those matrices are needed, or "all" to build every supported matrix.
simplify_quant: Whether ENCODE gene-quantification tables should be normalized to common identifier and expression columns already present in the file. Automatic featureCounts simplification requires exactly one sample-count column; use FALSE to preserve every column in a multi-sample featureCounts table. This does not query or use external annotation databases.
...: Additional arguments passed to table readers where applicable.

Value

The return type depends on input shape and file format. A local path returns the native object for that file: text tables return data frames, JSON returns a list, FASTA returns a DNAStringSet when Biostrings is installed, BED-like intervals return GRanges, and GFF/GTF, BigWig, and BigBed return rtracklayer imports when available and readable. Native-reader failures follow the unsupported policy. ENCODE peak files with extra nonstandard columns may fall back to a data frame in automatic mode; as = "GRanges" fails if conversion is not possible. FASTQ and alignment formats return encode_local_file path objects by default. Downloaded-file tables return an encode_loaded_files object with metadata, data, row_data, and matrices components. With as = "SummarizedExperiment", a downloaded-file table returns a SummarizedExperiment when compatible matrices were assembled. Its metadata(se)$encodeUtils entry retains the source query, request history, filters, and file-selection criteria.

Details

When downloaded gene-quantification TSV tables are read together, the returned object includes complete file metadata, individual file tables, aligned feature metadata, and numeric expression matrices. A local path returns the native object for that file. A downloaded-file table always returns an encode_loaded_files collection, including for a one-row table. Combined matrices are created only when every table has one complete, unique feature identifier, the same feature set, and compatible ENCODE organism, assembly, output-type, and genome-annotation metadata when those fields are available. Otherwise the original tables are retained without an inferred alignment.

Examples

path <- tempfile(fileext = ".tsv")
writeLines(c("gene_id\texpected_count", "Gata4\t10", "Tbx5\t4"), path)

encode_read(path)
#>       gene_id gene_symbol ensembl_id entrez_id raw_counts
#> Gata4   Gata4       Gata4       <NA>      <NA>         10
#> Tbx5     Tbx5        Tbx5       <NA>      <NA>          4