HOME  ›   pipelines
If your question is not answered here, please email us at:  ${email.software}

10x Genomics
Chromium Single Cell Gene Expression

Cell Ranger2.1, printed on 04/20/2024

Single-Library Analysis with cellranger count

Cell Ranger's pipelines analyze sequencing data produced from Chromium Single Cell 3’ RNA-seq libraries. This involves the following steps:

  1. Run cellranger mkfastq on the Illumina BCL output folder to generate FASTQ files.

  2. Run cellranger count on each library that was demultiplexed by cellranger mkfastq.

  3. Optionally, run cellranger aggr to aggregate multiple libraries from a single experiment that were analyzed by cellranger count.

  4. Optionally run cellranger reanalyze to re-run the secondary analysis on a library or aggregated set of libraries (i.e., PCA, t-SNE, and clustering).

For the following example, assume that the Illumina BCL output is in a folder named /sequencing/140101_D00123_0111_AHAWT7ADXX.

Run cellranger mkfastq

First, follow the instructions on running cellranger mkfastq to generate FASTQ files. For example, if the flowcell serial number was HAWT7ADXX, then cellranger mkfastq will output FASTQ files in HAWT7ADXX/outs/fastq_path.

Run cellranger count

To generate single-cell gene counts for a single library, run cellranger count with the following arguments. For a complete list of command-line arguments, run cellranger count --help.

ArgumentDescription
--idA unique run ID string: e.g. sample345
--fastqsEither:
Path of the fastq_path folder generated by cellranger mkfastq
e.g. /home/jdoe/runs/HAWT7ADXX/outs/fastq_path. This contains a directory hierarchy that cellranger count will automatically traverse.
- OR -
Any folder containing fastq files, for example if the fastq files were generated by a service provider and delivered outside the context of the mkfastq output directory structure.
Can take multiple comma-separated paths, which is helpful if the same library was sequenced on multiple flowcells.
Doing this will treat all reads from the library, across flowcells, as one sample.
If you have multiple libraries for the sample, you will need to run cellranger count on them individually, and then combine them with cellranger aggr.
--sampleSample name as specified in the sample sheet supplied to cellranger mkfastq.
Can take multiple comma-separated values, which is helpful if the same library was sequenced on multiple flowcells and the sample name used (and therefore fastq file prefix) is not identical between them.
Doing this will treat all reads from the library, across flowcells, as one sample.
If you have multiple libraries for the sample, you will need to run cellranger count on them individually, and then combine them with cellranger aggr.
Allowable characters in sample names are letters, numbers, hyphens, and underscores.
--transcriptomePath to the Cell Ranger compatible transcriptome reference e.g.
  • For a human-only sample, use /opt/refdata-cellranger-GRCh38-1.2.0
  • For a human and mouse mixture sample, use /opt/refdata-cellranger-hg19-and-mm10-1.2.0
--expect-cells(optional) Expected number of recovered cells. Default: 3,000 cells.
--force-cells(optional) Force pipeline to use this number of cells, bypassing the cell detection algorithm. Use this if the number of cells estimated by Cell Ranger is not consistent with the barcode rank plot.
--nosecondary(optional) Add this flag to skip secondary analysis of the gene-barcode matrix (dimensionality reduction, clustering and visualization). Set this if you plan to use cellranger reanalyze or your own custom analysis.
--chemistry(optional) Assay configuration. One of:
  • auto for autodetection (default),
  • threeprime for Single Cell 3′,
  • fiveprime for Single Cell 5′,
  • SC3Pv1 for Single Cell 3′ v1,
  • SC3Pv2 for Single Cell 3′ v2,
  • SC5P-PE for Single Cell 5′ paired-end (both R1 and R2 are used for alignment),
  • SC5P-R2 for Single Cell 5′ R2-only (where only R2 is used for alignment).
--r1-length(optional) Hard-trim the input R1 sequence to this length. Note that the length includes the Barcode and UMI sequences so do not set this below 26 for Single Cell 3′ v2 or Single Cell 5′. This and --r2-length are useful for determining the optimal read length for sequencing.
--r2-length(optional) Hard-trim the input R2 sequence to this length.
--lanes(optional) Lanes associated with this sample
--localcoresRestricts cellranger to use specified number of cores to execute pipeline stages. By default, cellranger will use all of the cores available on your system.
--localmemRestricts cellranger to use specified amount of memory (in GB) to execute pipeline stages. By default, cellranger will use 90% of the memory available on your system. Please note that cellranger requires at least 16 GB of memory to run all pipeline stages.
--indices(Deprecated. Optional. Only used for output from cellranger demux) Sample indices associated with this sample. Comma-separated list of:
  1. index set plate well: SI-3A-A1
  2. index sequences: TCGCCATA,GTATACAC

After determining these input arguments, run cellranger:

$ cd /home/jdoe/runs
$ cellranger count --id=sample345 \
                   --transcriptome=/opt/refdata-cellranger-GRCh38-1.2.0 \
                   --fastqs=/home/jdoe/runs/HAWT7ADXX/outs/fastq_path \
                   --sample=mysample \
                   --expect-cells=1000

Following a set of preflight checks to validate input arguments, cellranger count pipeline stages will begin to run:

Martian Runtime - 2.3.2
 
Running preflight checks (please wait)...
2016-11-10 14:23:52 [runtime] (ready)           ID.sample345.SC_RNA_COUNTER_CS.SC_RNA_COUNTER.SETUP_CHUNKS
2016-11-10 14:23:55 [runtime] (split_complete)  ID.sample345.SC_RNA_COUNTER_CS.SC_RNA_COUNTER.SETUP_CHUNKS
2016-11-10 14:23:55 [runtime] (run:local)       ID.sample345.SC_RNA_COUNTER_CS.SC_RNA_COUNTER.SETUP_CHUNKS.fork0.chnk0.main
...

By default, cellranger will use all of the cores available on your system to execute pipeline stages. You can specify a different number of cores to use with the --localcores option; for example, --localcores=16 will limit cellranger to using up to sixteen cores at once. Similarly, --localmem will restrict the amount of memory (in GB) used by cellranger.

The pipeline will create a new folder named with the sample ID you specified (e.g. /home/jdoe/runs/sample345) for its output. If this folder already exists, cellranger will assume it is an existing pipestance and attempt to resume running it.

Output Files

A successful cellranger count run should conclude with a message similar to this:

2016-11-10 16:10:09 [runtime] (join_complete)   ID.sample345.SC_RNA_COUNTER_CS.SC_RNA_COUNTER.SUMMARIZE_REPORTS
 
Outputs:
- Run summary HTML:                      /opt/sample345/outs/web_summary.html
- Run summary CSV:                       /opt/sample345/outs/metrics_summary.csv
- BAM:                                   /opt/sample345/outs/possorted_genome_bam.bam
- BAM index:                             /opt/sample345/outs/possorted_genome_bam.bam.bai
- Filtered gene-barcode matrices MEX:    /opt/sample345/outs/filtered_gene_bc_matrices
- Filtered gene-barcode matrices HDF5:   /opt/sample345/outs/filtered_gene_bc_matrices_h5.h5
- Unfiltered gene-barcode matrices MEX:  /opt/sample345/outs/raw_gene_bc_matrices
- Unfiltered gene-barcode matrices HDF5: /opt/sample345/outs/raw_gene_bc_matrices_h5.h5
- Secondary analysis output CSV:         /opt/sample345/outs/analysis
- Per-molecule read information:         /opt/sample345/outs/molecule_info.h5
- Loupe Cell Browser file:               /opt/sample345/outs/cloupe.cloupe
 
Pipestance completed successfully!

The output of the pipeline will be contained in a folder named with the sample ID you specified (e.g. sample345). The subfolder named outs will contain the main pipeline output files:

File NameDescription
web_summary.htmlRun summary metrics and charts in HTML format
metrics_summary.csvRun summary metrics in CSV format
possorted_genome_bam.bamReads aligned to the genome and transcriptome annotated with barcode information
possorted_genome_bam.bam.baiIndex for possorted_genome_bam.bam
filtered_gene_bc_matricesFiltered gene-barcode matrices containing only cellular barcodes in MEX format
filtered_gene_bc_matrices_h5.h5Filtered gene-barcode matrices containing only cellular barcodes in HDF5 format
raw_gene_bc_matricesUnfiltered gene-barcode matrices containing all barcodes in MEX format
raw_gene_bc_matrices_h5.h5Unfiltered gene-barcode matrices containing all barcodes in HDF5 format
analysisSecondary analysis data including dimensionality reduction, cell clustering, and differential expression
molecule_info.h5Molecule-level information used by cellranger aggr to aggregate samples into larger datasets.
cloupe.cloupeLoupe Cell Browser visualization and analysis file

Once cellranger count has successfully completed, you can browse the resulting summary HTML file in any supported web browser, open the .cloupe file in Loupe Cell Browser, or refer to the Understanding Output section to explore the data by hand.