Package 'TENxIO'

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

Help Index


TENxIO: A Bioconductor package for importing 10X Genomics files

Description

The package provides file classes based on BiocIO for common file extensions found in the 10X Genomics website.

Supported file types

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

Author(s)

Maintainer: Marcel Ramos [email protected] (ORCID)

Authors:

Other contributors:

  • NCI (GrantNo.: U24CA289073) [funder]

See Also

Useful links:


TENxFile constructor function

Description

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

Usage

TENxFile(resource, extension, ...)

Arguments

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 ExperimentHub resources where the file extension is removed.

...

Additional inputs to the low level class generator functions

Details

Note that the example below includes the use of a large ~ 4 GB ExperimentHub resource obtained from the 10X website.

Value

A subclass of TENxFile according to the input file extension

Examples

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()

}

TENxFileList: Represent groups of files from 10X Genomic

Description

This constructor function is meant to handle .tar.gz tarball files from 10X Genomics.

Usage

TENxFileList(..., version, compressed = FALSE)

Arguments

...

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 tar.gz (default FALSE)

Details

These tarballs usually contain three files:

  1. matrix.mtx.gz - the counts matrix

  2. features.tsv.gz - row metadata usually represented as rowData

  3. 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.

Value

Either a SingleCellExperiment or a list of imported data

See Also

import in TENxFileList

Examples

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

Description

TENxFragments: Import fragments files from 10X

Usage

TENxFragments(resource, yieldSize = 200, which = GRanges(), ...)

Arguments

resource

character(1) The file path to the fragments resource, usually a compressed tabix file with extension .tsv.gz.

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 RSamtools as the param input.

...

Further arguments to the class generator function (currently not used)

Value

A RaggedExperiment object class

See Also

import in TENxFragments

Examples

fr <- system.file(
    "extdata", "pbmc_3k_atac_ex_fragments.tsv.gz",
    package = "TENxIO", mustWork = TRUE
)

tfr <- TENxFragments(fr)

fra <- import(tfr)

TENxH5: Represent H5 files from 10X

Description

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.

Usage

TENxH5(resource, version, group, ranges, rowidx, colidx, ...)

Arguments

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 NA_character_ if range information is not present.

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 [ method of the TENxMatrix representation.

...

Additional inputs to the low level class generator functions

Details

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.

Value

Usually, a SingleCellExperiment instance

See Also

import in TENxH5

Examples

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)

TENxMTX: Represent Matrix Market Format Files from 10X

Description

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.

Usage

TENxMTX(resource, compressed = FALSE, ...)

Arguments

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

Value

A SummarizedExperiment instance with a dgCMatrix in the assay

See Also

import in TENxMTX

Examples

mtxf <- system.file(
    "extdata", "pbmc_3k_ff_bc_ex.mtx",
    package = "TENxIO", mustWork = TRUE
)

con <- TENxMTX(mtxf)

import(con)

TENxPeaks: Represent peak annotation files from 10x

Description

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.

Usage

TENxPeaks(resource, extension, ...)

Arguments

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 ExperimentHub resources where the file extension is removed.

...

Additional inputs to the low level class generator functions

Details

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.

Value

A GRanges class object of peak locations

See Also

import in TENxPeaks

Examples

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)

TENxTSV: Represent Tab Separated Value files from 10x

Description

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.

Usage

TENxTSV(resource, compressed = FALSE, ...)

Arguments

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

Details

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.*⁠.

See Also

import in TENxTSV