| Title: | Import methods for 10X Genomics files |
|---|---|
| Description: | Provides a structured S4 approach to importing data files from the 10X pipelines. It mainly supports Single Cell Multiome ATAC + Gene Expression data among other data types. The main Bioconductor data representations used are SingleCellExperiment and RaggedExperiment. |
| Authors: | Marcel Ramos [aut, cre] (ORCID: <https://orcid.org/0000-0002-3242-0582>), NCI [fnd] (GrantNo.: U24CA289073) |
| Maintainer: | Marcel Ramos <[email protected]> |
| License: | Artistic-2.0 |
| Version: | 1.15.2 |
| Built: | 2026-11-05 19:06:35 UTC |
| Source: | https://github.com/waldronlab/TENxIO |
The package provides file classes based on BiocIO for common file
extensions found in the 10X Genomics website.
Here is a table of supported file and file extensions and their imported classes:
| Extension | Class | Imported as |
| .h5 | TENxH5 | SingleCellExperiment w/ TENxMatrix |
| .mtx / .mtx.gz | TENxMTX | SummarizedExperiment w/ dgCMatrix |
| .tar.gz | TENxFileList | SingleCellExperiment w/ dgCMatrix |
| peak_annotation.tsv | TENxPeaks | GRanges |
| fragments.tsv.gz | TENxFragments | RaggedExperiment |
| .tsv / .tsv.gz | TENxTSV | tibble |
Maintainer: Marcel Ramos [email protected] (ORCID)
Authors:
Marcel Ramos [email protected] (ORCID)
Other contributors:
NCI (GrantNo.: U24CA289073) [funder]
Useful links:
The TENxFile constructor function serves as the
auto-recognizer function for 10X files. It can import several different
file extensions, namely:
* H5 - on-disk HDF5
* MTX - matrix market
* .tar.gz - compressed tarball
TENxFile(resource, extension, ...)TENxFile(resource, extension, ...)
resource |
character(1) The path to the file |
extension |
character(1) The file extension for the given resource. It
can usually be obtained from the file path. An override can be provided
especially for |
... |
Additional inputs to the low level class generator functions |
Note that the example below includes the use of a large ~ 4 GB
ExperimentHub resource obtained from the 10X website.
A subclass of TENxFile according to the input file extension
if (interactive()) { ## from ExperimentHub hub <- ExperimentHub::ExperimentHub() fname <- hub[["EH1039"]] TENxFile(fname, extension = "h5", group = "mm10", version = "2") TENxFile(fname, extension = "h5", group = "mm10", version = "2") |> metadata() }if (interactive()) { ## from ExperimentHub hub <- ExperimentHub::ExperimentHub() fname <- hub[["EH1039"]] TENxFile(fname, extension = "h5", group = "mm10", version = "2") TENxFile(fname, extension = "h5", group = "mm10", version = "2") |> metadata() }
This constructor function is meant to handle .tar.gz tarball
files from 10X Genomics.
TENxFileList(..., version, compressed = FALSE)TENxFileList(..., version, compressed = FALSE)
... |
Typically, a file path to a tarball archive. Can be named arguments corresponding to file paths, or a named list of file paths. |
version |
character(1) The version in the tarball. See details. |
compressed |
logical(1) Whether or not the file provided is compressed,
usually as |
These tarballs usually contain three files:
matrix.mtx.gz - the counts matrix
features.tsv.gz - row metadata usually represented as rowData
barcodes.tsv.gz - column names corresponding to cell barcode
identifiers
If all above files are in the tarball, the import method will provide a
SingleCellExperiment. Otherwise, a simple list of imported data is given.
Note that version "3" uses 'features.tsv.gz' and version "2" uses
'genes.tsv.gz'. If known, indicate the version argument in the
TENxFileList constructor function.
Either a SingleCellExperiment or a list of imported data
import in TENxFileList
fl <- system.file( "extdata", "pbmc_granulocyte_sorted_3k_ff_bc_ex_matrix.tar.gz", package = "TENxIO", mustWork = TRUE ) ## Method 1 (tarball) TENxFileList(fl) ## metadata before import metadata(TENxFileList(fl)) ## import() method import(TENxFileList(fl)) ## metadata after import import(TENxFileList(fl)) |> metadata() ## untar to simulate folder output dir.create(tdir <- tempfile()) untar(fl, exdir = tdir) ## Method 2 (folder) TENxFileList(tdir) import(TENxFileList(tdir)) ## Method 3 (list of TENxFile objects) files <- list.files(tdir, recursive = TRUE, full.names = TRUE) names(files) <- basename(files) filelist <- lapply(files, TENxFile) TENxFileList(filelist, compressed = FALSE) ## Method 4 (SimpleList) TENxFileList(as(filelist, "SimpleList"), compressed = FALSE) ## Method 5 (named arguments) TENxFileList( barcodes.tsv.gz = TENxFile(files[1]), features.tsv.gz = TENxFile(files[2]), matrix.mtx.gz = TENxFile(files[3]) ) unlink(tdir, recursive = TRUE)fl <- system.file( "extdata", "pbmc_granulocyte_sorted_3k_ff_bc_ex_matrix.tar.gz", package = "TENxIO", mustWork = TRUE ) ## Method 1 (tarball) TENxFileList(fl) ## metadata before import metadata(TENxFileList(fl)) ## import() method import(TENxFileList(fl)) ## metadata after import import(TENxFileList(fl)) |> metadata() ## untar to simulate folder output dir.create(tdir <- tempfile()) untar(fl, exdir = tdir) ## Method 2 (folder) TENxFileList(tdir) import(TENxFileList(tdir)) ## Method 3 (list of TENxFile objects) files <- list.files(tdir, recursive = TRUE, full.names = TRUE) names(files) <- basename(files) filelist <- lapply(files, TENxFile) TENxFileList(filelist, compressed = FALSE) ## Method 4 (SimpleList) TENxFileList(as(filelist, "SimpleList"), compressed = FALSE) ## Method 5 (named arguments) TENxFileList( barcodes.tsv.gz = TENxFile(files[1]), features.tsv.gz = TENxFile(files[2]), matrix.mtx.gz = TENxFile(files[3]) ) unlink(tdir, recursive = TRUE)
TENxFragments: Import fragments files from 10X
TENxFragments(resource, yieldSize = 200, which = GRanges(), ...)TENxFragments(resource, yieldSize = 200, which = GRanges(), ...)
resource |
character(1) The file path to the fragments resource, usually
a compressed tabix file with extension |
yieldSize |
numeric() The number of records to read by default, 200 records will be imported. A warning will be emitted if not modified. |
which |
GRanges() A GRanges indicating the regions of interest. This
get sent to |
... |
Further arguments to the class generator function (currently not used) |
A RaggedExperiment object class
import in TENxFragments
fr <- system.file( "extdata", "pbmc_3k_atac_ex_fragments.tsv.gz", package = "TENxIO", mustWork = TRUE ) tfr <- TENxFragments(fr) fra <- import(tfr)fr <- system.file( "extdata", "pbmc_3k_atac_ex_fragments.tsv.gz", package = "TENxIO", mustWork = TRUE ) tfr <- TENxFragments(fr) fra <- import(tfr)
This constructor function was developed using the PBMC 3K dataset from 10X
Genomics (version 3). Other versions are supported and input arguments
version and group can be overridden.
TENxH5(resource, version, group, ranges, rowidx, colidx, ...)TENxH5(resource, version, group, ranges, rowidx, colidx, ...)
resource |
character(1) The path to the file |
version |
character(1) There are currently two recognized versions associated with 10X data, either version "2" or "3". See details for more information. |
group |
character(1) The HDF5 group embedded within the file structure, this is usually either the "matrix" or "outs" group but other groups are supported as well (e.g., "mm10"). |
ranges |
character(1) The HDF5 internal folder location embedded within
the file that points to the ranged data information, e.g.,
"/features/interval". Set to |
rowidx, colidx
|
numeric() A vector of indices corresponding to either
rows or columns that will dictate the data imported from the file. The
indices will be passed on to the |
... |
Additional inputs to the low level class generator functions |
The various TENxH5 methods including rowData and rowRanges,
provide a snapshot of the data using a length 12 head and tail subset for
efficiency. In contrast, methods such as dimnames and dim give
a full view of the dimensions of the data. The show method provides
relevant information regarding the dimensions of the data including
metadata such as rowData and "Type" column, if available. The data files
are imported as SingleCellExperiment class objects.
An additional ref argument can be provided when the file contains
multiple feature_type in the file or "Type" in the rowData. By default,
the first type reported in table() is set as the mainExpName in the
SingleCellExperiment object.
For data that do not contain genomic coordinate information, the TENxH5
will fail to read "/features/interval" and will set the ranges
argument to NA_character_.
The data version "3" mainly includes a "matrix" group and "interval"
information within the file. Version "2" data does not include
ranged-based information and has a different directory structure compared
to version "3". See the internal data.frame: TENxIO:::h5.version.map
for a map of fields and their corresponding file locations within the H5
file. This map is used to create the rowData structure from the file.
Usually, a SingleCellExperiment instance
import in TENxH5
h5f <- system.file( "extdata", "pbmc_granulocyte_ff_bc_ex.h5", package = "TENxIO", mustWork = TRUE ) TENxH5(h5f) import(TENxH5(h5f)) h5f <- system.file( "extdata", "10k_pbmc_ATACv2_f_bc_ex.h5", package = "TENxIO", mustWork = TRUE ) ## Optional ref input, most frequent Type used by default th5 <- TENxH5(h5f, ranges = "/features/id", ref = "Peaks") th5 TENxH5(h5f, ranges = "/features/id") import(th5)h5f <- system.file( "extdata", "pbmc_granulocyte_ff_bc_ex.h5", package = "TENxIO", mustWork = TRUE ) TENxH5(h5f) import(TENxH5(h5f)) h5f <- system.file( "extdata", "10k_pbmc_ATACv2_f_bc_ex.h5", package = "TENxIO", mustWork = TRUE ) ## Optional ref input, most frequent Type used by default th5 <- TENxH5(h5f, ranges = "/features/id", ref = "Peaks") th5 TENxH5(h5f, ranges = "/features/id") import(th5)
This constructor function accepts .mtx and .mtx.gz compressed formats
for eventual importing. It is mainly used with tarball files from 10X
Genomics, where more annotation data is included. Importing solely the
.mtx format will provide users with a SummarizedExperiment with an assay
of class dgCMatrix from the Matrix package. Currently, other formats are
not supported but if you'd like to request support for a format, please open
an issue on GitHub.
TENxMTX(resource, compressed = FALSE, ...)TENxMTX(resource, compressed = FALSE, ...)
resource |
character(1) The path to the file |
compressed |
logical(1) Whether the resource file is compressed (default FALSE) |
... |
Additional inputs to the low level class generator functions |
A SummarizedExperiment instance with a dgCMatrix in the assay
import in TENxMTX
mtxf <- system.file( "extdata", "pbmc_3k_ff_bc_ex.mtx", package = "TENxIO", mustWork = TRUE ) con <- TENxMTX(mtxf) import(con)mtxf <- system.file( "extdata", "pbmc_3k_ff_bc_ex.mtx", package = "TENxIO", mustWork = TRUE ) con <- TENxMTX(mtxf) import(con)
This constructor function is designed to work with the files denoted with
"peak_annotation" in the file name. These are usually produced as tab
separated value files, i.e., .tsv.
TENxPeaks(resource, extension, ...)TENxPeaks(resource, extension, ...)
resource |
character(1) The path to the file |
extension |
character(1) The file extension for the given resource. It
can usually be obtained from the file path. An override can be provided
especially for |
... |
Additional inputs to the low level class generator functions |
The output class allows handling of peak data. It can be used in
conjunction with the annotation method on a SingleCellExperiment to add
peak information to the experiment. The ranged data is represented as a
GRanges class object.
A GRanges class object of peak locations
import in TENxPeaks
fi <- system.file( "extdata", "pbmc_granulocyte_sorted_3k_ex_atac_peak_annotation.tsv", package = "TENxIO", mustWork = TRUE ) peak_file <- TENxPeaks(fi) peak_anno <- import(peak_file) peak_anno example(TENxH5) ## Add peaks to an existing SCE ## First, import the SCE from an example H5 file h5f <- system.file( "extdata", "pbmc_granulocyte_ff_bc_ex.h5", package = "TENxIO", mustWork = TRUE ) con <- TENxH5(h5f) sce <- import(con) ## auto-import peaks when using annotation<- annotation(sce, name = "peak_annotation") <- peak_file annotation(sce)fi <- system.file( "extdata", "pbmc_granulocyte_sorted_3k_ex_atac_peak_annotation.tsv", package = "TENxIO", mustWork = TRUE ) peak_file <- TENxPeaks(fi) peak_anno <- import(peak_file) peak_anno example(TENxH5) ## Add peaks to an existing SCE ## First, import the SCE from an example H5 file h5f <- system.file( "extdata", "pbmc_granulocyte_ff_bc_ex.h5", package = "TENxIO", mustWork = TRUE ) con <- TENxH5(h5f) sce <- import(con) ## auto-import peaks when using annotation<- annotation(sce, name = "peak_annotation") <- peak_file annotation(sce)
The constructor function creates an instance of class TENxTSV whose data
can be imported with the import method. The import method works with
tabular data from the 10x Genomics website with the .tsv and the compressed
.tsv.gz file extensions. Typically, .tsv and .tsv.gz files are
automatically imported by wrapper functions that import bundled files.
TENxTSV(resource, compressed = FALSE, ...)TENxTSV(resource, compressed = FALSE, ...)
resource |
character(1) The path to the file |
compressed |
logical(1) Whether the resource file is compressed (default FALSE) |
... |
Additional inputs to the low level class generator functions |
Typical .tsv and .tsv.gz files obtained from the 10X website are
compressed and contain information relevant to 'barcodes' and 'features'.
Currently, the code only supports files such as features.tsv.* and
barcodes.tsv.*.
import in TENxTSV