importCellRanger {singleCellTK} | R Documentation

## Construct SCE object from Cell Ranger output

### Description

Read the filtered barcodes, features, and matrices for all samples from (preferably a single run of) Cell Ranger output. Import and combine them as one big SingleCellExperiment object.

### Usage

    importCellRanger(
      cellRangerDirs = NULL,
      sampleDirs = NULL,
      sampleNames = NULL,
      cellRangerOuts = NULL,
      dataType = c("filtered", "raw"),
      matrixFileNames = "matrix.mtx.gz",
      featuresFileNames = "features.tsv.gz",
      barcodesFileNames = "barcodes.tsv.gz",
      gzipped = "auto",
      class = c("Matrix", "matrix"),
      delayedArray = TRUE
    )

    importCellRangerV2(
      cellRangerDirs = NULL,
      sampleDirs = NULL,
      sampleNames = NULL,
      dataTypeV2 = c("filtered", "raw"),
      class = c("Matrix", "matrix"),
      delayedArray = TRUE,
      reference = NULL,
      cellRangerOutsV2 = NULL
    )

    importCellRangerV3(
      cellRangerDirs = NULL,
      sampleDirs = NULL,
      sampleNames = NULL,
      dataType = c("filtered", "raw"),
      class = c("Matrix", "matrix"),
      delayedArray = TRUE
    )

### Arguments

`cellRangerDirs` | The root directories where Cell Ranger was run. These folders should contain sample specific folders. Default `NULL`, meaning the paths for each sample will be specified in samples argument.
`sampleDirs` | Default `NULL`. Can be one of `NULL`. All samples within `cellRangerDirs` will be imported. The order of samples will be first determined by the order of `cellRangerDirs` and then by list.dirs. This is only for the case where `cellRangerDirs` is specified. A list of vectors containing the folder names for samples to import. Each vector in the list corresponds to samples from one of `cellRangerDirs`. These names are the same as the folder names under `cellRangerDirs`. This is only for the case where `cellRangerDirs` is specified. A vector of folder paths for the samples to import. This is only for the case where `cellRangerDirs` is `NULL`. The cells in the final SCE object will be ordered in the same order of `sampleDirs`.
`sampleNames` | A vector of user-defined sample names for the samples to be imported. Must have the same length as `length(unlist(sampleDirs))` if `sampleDirs` is not `NULL`. Otherwise, make sure the length and order match the output of `unlist(lapply(cellRangerDirs, list.dirs, recursive = FALSE))`. Default `NULL`, in which case the folder names will be used as sample names.
`cellRangerOuts` | Character vector. The intermediate paths to filtered or raw cell barcode, feature, and matrix files for each sample. Supercedes `dayaType`. If `NULL`, `dataType` will be used to determine Cell Ranger output directory. If not `NULL`, `dataType` will be ingored and `cellRangerOuts` specifies the paths. Must have length 1 or the same length as `length(unlist(sampleDirs))` if `sampleDirs` is not `NULL`. Otherwise, make sure the length and order match the output of `unlist(lapply(cellRangerDirs, list.dirs, recursive = FALSE))`. Reference genome names might need to be appended for CellRanger version below 3.0.0 if reads were mapped to multiple genomes when running Cell Ranger pipeline. Probable options include "outs/filtered_feature_bc_matrix/", "outs/raw_feature_bc_matrix/", "outs/filtered_gene_bc_matrix/", "outs/raw_gene_bc_matrix/".
`dataType` | Character. The type of data to import. Can be one of "filtered" (which is equivalent to `cellRangerOuts = "outs/filtered_feature_bc_matrix/"` or `cellRangerOuts = "outs/filtered_gene_bc_matrix/"`) or "raw" (which is equivalent to `cellRangerOuts = "outs/raw_feature_bc_matrix/"` or `cellRangerOuts = "outs/raw_gene_bc_matrix/"`). Default "filtered" which imports the counts for filtered cell barcodes only.
`matrixFileNames` | Character vector. Filenames for the Market Exchange Format (MEX) sparse matrix files (matrix.mtx or matrix.mtx.gz files). Must have length 1 or the same length as `length(unlist(sampleDirs))` if `sampleDirs` is not `NULL`. Otherwise, make sure the length and order match the output of `unlist(lapply(cellRangerDirs, list.dirs, recursive = FALSE))`.
`featuresFileNames` | Character vector. Filenames for the feature annotation files. They are usually named features.tsv.gz or genes.tsv. Must have length 1 or the same length as `length(unlist(sampleDirs))` if `sampleDirs` is not `NULL`. Otherwise, make sure the length and order match the output of `unlist(lapply(cellRangerDirs, list.dirs, recursive = FALSE))`.
`barcodesFileNames` | Character vector. Filename for the cell barcode list files. They are usually named barcodes.tsv.gz or barcodes.tsv. Must have length 1 or the same length as `length(unlist(sampleDirs))` if `sampleDirs` is not `NULL`. Otherwise, make sure the length and order match the output of `unlist(lapply(cellRangerDirs, list.dirs, recursive = FALSE))`.
`gzipped` | `TRUE` if the Cell Ranger output files (barcodes.tsv, features.tsv, and matrix.mtx) were gzip compressed. `FALSE` otherwise. This is true after Cell Ranger 3.0.0 update. Default `"auto"` which automatically detects if the files are gzip compressed. If not `"auto"`, `gzipped` must have length 1 or the same length as `length(unlist(sampleDirs))` if `sampleDirs` is not `NULL`. Otherwise, make sure the length and order match the output of `unlist(lapply(cellRangerDirs, list.dirs, recursive = FALSE))`.
`class` | Character. The class of the expression matrix stored in the SCE object. Can be one of "Matrix" (as returned by readMM function), or "matrix" (as returned by matrix function). Default `"Matrix"`.
`delayedArray` | Boolean. Whether to read the expression matrix as DelayedArray object or not. Default `TRUE`.
`dataTypeV2` | Character. The type of output to import for Cellranger version below 3.0.0. Whether to import the filtered or the raw data. Can be one of 'filtered' or 'raw'. Default 'filtered'. When `cellRangerOuts` is specified, `dataTypeV2` and `reference` will be ignored.
`reference` | Character vector. The reference genome names. Default `NULL`. If not `NULL`, it must gave the length and order as `length(unlist(sampleDirs))` if `sampleDirs` is not `NULL`. Otherwise, make sure the length and order match the output of `unlist(lapply(cellRangerDirs, list.dirs, recursive = FALSE))`. Only needed for Cellranger version below 3.0.0.
`cellRangerOutsV2` | Character vector. The intermediate paths to filtered or raw cell barcode, feature, and matrix files for each sample for Cellranger version below 3.0.0. If `NULL`, `reference` and `dataTypeV2` will be used to determine Cell Ranger output directory. If it has length 1, it assumes that all samples use the same genome reference and the function will load only filtered or raw data.

### Details

`importCellRangerV2` imports output from Cell Ranger V2. `importCellRangerV2Sample` imports output from one sample from Cell Ranger V2. `importCellRangerV3` imports output from Cell Ranger V3. `importCellRangerV3` imports output from one sample from Cell Ranger V3. Some implicit assumptions which match the output structure of Cell Ranger V2 & V3 are made in these 4 functions including `cellRangerOuts`, `matrixFileName`, `featuresFileName`, `barcodesFileName`, and `gzipped`. Alternatively, user can call `importCellRanger` to explicitly specify these arguments.

### Value

A `SingleCellExperiment` object containing the combined count matrix, the feature annotations, and the cell annotation.

### Examples

    # Example #1
    # The following filtered feature, cell, and matrix files were downloaded from
    # https://support.10xgenomics.com/single-cell-gene-expression/datasets/
    # 3.0.0/hgmm_1k_v3
    # The top 10 hg19 & mm10 genes are included in this example.
    # Only the first 20 cells are included.
    sce <- importCellRanger(
        cellRangerDirs = system.file("extdata/", package = "singleCellTK"),
        sampleDirs = "hgmm_1k_v3_20x20",
        sampleNames = "hgmm1kv3",
        dataType = "filtered")
    # The following filtered feature, cell, and matrix files were downloaded from
    # https://support.10xgenomics.com/single-cell-gene-expression/datasets/
    # 2.1.0/pbmc4k
    # Top 20 genes are kept. 20 cell barcodes are extracted.
    sce <- importCellRangerV2(
        cellRangerDirs = system.file("extdata/", package = "singleCellTK"),
        sampleDirs = "pbmc_4k_v2_20x20",
        sampleNames = "pbmc4k_20",
        reference = 'GRCh38',
        dataTypeV2 = "filtered")
    sce <- importCellRangerV3(
        cellRangerDirs = system.file("extdata/", package = "singleCellTK"),
        sampleDirs = "hgmm_1k_v3_20x20",
        sampleNames = "hgmm1kv3",
        dataType = "filtered")

[Package singleCellTK version 2.0.0 Index]