read10xCounts {DropletUtils} | R Documentation

## Load in data from 10x experiment

### Description

Creates a SingleCellExperiment from the CellRanger output directories for 10X Genomics data.

### Usage

    read10xCounts(samples, col.names=FALSE, type=c("auto", "sparse", "HDF5"),
        version=c("auto", "2", "3"), genome=NULL)

### Arguments

`samples` | A character vector containing one or more directory names, each corresponding to a 10X sample. Each directory should contain a matrix file, a gene/feature annotation file, and a barcode annotation file. Alternatively, strings may contain a path to a HDF5 file in the sparse matrix format generated by 10X. These can be mixed with directory names when `type="auto"`.
`col.names` | A logical scalar indicating whether the columns of the output object should be named with the cell barcodes.
`type` | String specifying the type of 10X format to read data from.
`version` | String specifying the version of the 10X format to read data from.
`genome` | String specifying the genome if `type="HDF5"` and `version='2'`.

### Details

This function was originally developed from the `Read10X` function from the Seurat package. It was then taken from the `read10xResults` implementation in the scater package.

If `type="auto"`, the format of the input file is automatically detected for each `samples` based on whether it ends with `".h5"`. If so, `type` is set to `"HDF5"`; otherwise it is set to `"sparse"`.

- If `type="sparse"`, count data are loaded as a dgCMatrix object. This is a conventional column-sparse compressed matrix format produced by the CellRanger pipeline.

- If `type="HDF5"`, count data are assumed to follow the 10X sparse HDF5 format for large data sets. It is loaded as a TENxMatrix object, which is a stub object that refers back to the file in `samples`. Users may need to set `genome` if it cannot be automatically determined when `version="2"`.

CellRanger 3.0 introduced a major change in the format of the output files for both `type`s. If `version="auto"`, the version of the format is automatically detected from the supplied paths. For `type="sparse"`, this is based on whether there is a `"features.tsv.gz"` file in the directory. For `type="HDF5"`, this is based on whether there is a top-level `"matrix"` group with a `"matrix/features"` subgroup in the file.

Matrices are combined by column if multiple `samples` were specified. This will throw an error if the gene information is not consistent across `samples`.

If `col.names=TRUE` and `length(sample)==1`, each column is named by the cell barcode. For multiple samples, the columns are unnamed to avoid problems with non-unique barcodes across samples.

Note that user-level manipulation of sparse matrices requires loading of the Matrix package. Otherwise, calculation of `rowSums`, `colSums`, etc. will result in errors.

### Value

A SingleCellExperiment object containing count data for each gene (row) and cell (column) across all `samples`.

- Row metadata will contain the fields `"ID"` and `"Symbol"`. The former is the gene identifier (usually Ensembl), while the latter is the gene name. If `version="3"`, it will also contain the `"Type"` field specifying the type of feature (e.g., gene or antibody).

- Column metadata will contain the fields `"Sample"` and `"Barcode"`. The former contains the value of `samples` from which each column was obtained. The latter refers to the cell barcode sequence and GEM group for each cell library.

- Rows are named with the gene identifier. Columns are named with the cell barcode in certain settings, see Details.

- The assays will contain a single `"counts"` matrix, containing UMI counts for each gene in each cell. Note that the matrix representation will depend on the format of the `samples`, see Details.

### Author(s)

Davis McCarthy, with modifications from Aaron Lun

### References

Zheng GX, Terry JM, Belgrader P, and others (2017). Massively parallel digital transcriptional profiling of single cells. Nat Commun 8:14049.

10X Genomics (2017). Gene-Barcode Matrices. https://support.10xgenomics.com/single-cell-gene-expression/software/pipelines/2.2/output/matrices

10X Genomics (2018). Feature-Barcode Matrices. https://support.10xgenomics.com/single-cell-gene-expression/software/pipelines/latest/output/matrices

10X Genomics (2018). HDF5 Gene-Barcode Matrix Format. https://support.10xgenomics.com/single-cell-gene-expression/software/pipelines/2.2/advanced/h5_matrices

10X Genomics (2018). HDF5 Feature Barcode Matrix Format. https://support.10xgenomics.com/single-cell-gene-expression/software/pipelines/latest/advanced/h5_matrices

### See Also

`write10xCounts`

### Examples

    # Mocking up some 10X genomics output.
    example(write10xCounts)

    # Reading it in.
    sce10x <- read10xCounts(tmpdir)

    # Column names are dropped with multiple 'samples'.
    sce10x2 <- read10xCounts(c(tmpdir, tmpdir))

[Package DropletUtils version 1.4.3 Index]