Support homeCell RangerAnalysis
Running Cell Ranger count

Running Cell Ranger count

Important
You can run 10x Genomics single cell pipelines with 10x Genomics Cloud Analysis, our recommended method to easily process FASTQ files into Cell Ranger output files for most new customers. Click here to sign up for a free account.
Important
Libraries generated using the GEM-X Universal 3’ and 5' 4-plex On-chip Multiplexing assays cannot be analyzed using cellranger count.

Cell Ranger pipelines analyze sequencing data from Chromium Single Cell Gene Expression and Feature Barcode libraries. The cellranger count takes FASTQ files and performs alignment, filtering, barcode counting, and UMI counting. It uses the 10x Barcodes to generate feature-barcode matrices, determine clusters, and perform gene expression analysis. The count pipeline can take input from multiple sequencing runs on the same GEM well.

When one of more Feature Barcode libraries are included in the analysis, all Feature Barcode data are processed through a counting pipeline that quantifies each feature in each cell. The pipeline outputs a unified feature-barcode matrix that contains gene expression counts alongside Feature Barcode counts for each cell barcode. The feature-barcode matrix replaces the gene-barcode matrix emitted by older versions of Cell Ranger.

The pipeline first extracts and corrects the cell barcode and UMI from the feature library using the same methods as gene expression read processing. It then matches the Feature Barcode read against the list of features declared in the Feature Barcode Reference. The counts for each feature are available in the feature-barcode matrix output files and in the Loupe Browser output file.

Pipeline limitations and alternatives

The cellranger count pipeline does not support:

For recommendations on choosing the appropriate pipeline for various library combinations, visit the Choosing a pipeline page.

Note: Cell Ranger is not suitable for Single Cell Multiome Analysis. For Single Cell Multiome ATAC + Gene Expression libraries, please use Cell Ranger ARC.

The analysis involves the following steps:

Step 1: Generate FASTQ Files

(skip this step if you are starting with FASTQ files)

Run bcl-convert or bcl2fastq on the Illumina BCL output folder to demultiplex and generate FASTQ files.

For this example, assume the Illumina BCL output is stored in the folder /sequencing/140101_D00123_0111_AHAWT7ADXX. Given the flow cell ID is HAWT7ADXX, the output FASTQ files will be located in the directory HAWT7ADXX/outs/fastq_path.

Step 2: Run cellranger count

Run cellranger count on each GEM well that was demultiplexed.

If a Feature Barcode library was created alongside the Gene Expression library, both can be analyzed simultaneously using cellranger count. Details on Feature Barcode Analysis.

Step 3: Aggregate Libraries (Optional)

Optionally, run cellranger aggr to aggregate multiple GEM wells from the same experiment that were previously analyzed with cellranger count.

Step 4: Reanalyze Data (Optional)

Optionally, run cellranger reanalyze to rerun the secondary analysis (i.e., PCA, t-SNE, and clustering) on a library or aggregated set of libraries. This step allows for fine-tuning of analysis parameters.

Important
Starting with Cell Ranger v7.0, the expected cell count can be auto-estimated or set manually using --expect-cells (e.g., for replicating previous analyses). Use --force-cells to override automated cell calling. For details, see Gene Expression algorithm overview

To generate single cell feature counts for a single library, run cellranger count with the arguments shown in the code snippet below:

cd /home/jdoe/runs
cellranger count --id=sample345 \
           --transcriptome=/opt/refdata-gex-GRCh38-2020-A \
           --fastqs=/home/jdoe/runs/HAWT7ADXX/outs/fastq_path \
           --sample=mysample \
           --create-bam=true \
           --localcores=8 \
           --localmem=64

If your experiment includes a Feature Barcode library (e.g., Cell Surface Protein/ Antibody Capture) two additional arguments need to be added to the cellranger count command:

  • --feature-ref argument: points to a Feature Reference CSV file. This file details the structure and sequence of each Feature Barcode used in your experiment.
  • --libraries argument is required to specify the Libraries CSV file, which lists all the input libraries and their corresponding details.

Example command:

cd /home/jdoe/runs
cellranger count --id=sample345 \
           --libraries=library.csv \
           --transcriptome=/opt/refdata-gex-GRCh38-2020-A \
           --feature-ref=feature_ref.csv \
           --create-bam=true

This configuration ensures accurate processing and analysis of Feature Barcode libraries alongside Gene Expression data.

To reduce costs associated with sequencing and library preparation, Antibody Capture libraries (without Gene Expression libraries) can be analyzed in "Feature Barcode Only" mode using cellranger count. This capability has been available since Cell Ranger v3.1. Starting with Cell Ranger v9.0, a transcriptome reference is no longer required for Antibody Capture-only analysis.

Important

In the "Feature Barcode Only" mode, if fewer than ten antibodies are used, Cell Ranger skips secondary analysis and does not generate a .cloupe file. This restriction does not apply to runs that include Gene Expression libraries.

To use cellranger count in Feature Barcode Only mode, follow the instructions for Feature Barcode Analysis. Be sure to omit Gene Expression entries from the Libraries CSV file.

Results from a Feature Barcode Only analysis can be aggregated using cellranger aggr, provided all the runs being combined share a common feature reference.

Cell Ranger performs the normal Feature Barcode quantification analysis in Feature Barcode Only mode, but uses a simplified version of the cell calling algorithm. The EmptyDrops step that refines cell calls is not performed. See the Cell Calling algorithm documentation for details.

Important

Libraries with peptide-MHC multimers must be analyzed along with cell surface proteins targeting T-cell surface markers. The analysis of peptide-MHC multimers libraries on their own is unsupported. Similarly, CRISPR Guide Capture libraries must not be analyzed in the absence of the corresponding Gene Expression library.

When you enable cell type annotation, your data is securely transmitted to 10x Genomics Cloud Analysis. Since your data is leaving your local environment and entering the 10x Genomics domain, it becomes subject to the terms outlined in the 10x Genomics End User License Agreement (EULA). Please review the EULA carefully to understand how your data will be handled and the associated usage terms.

Starting with v9.0, you can enable cell annotations during a count run by including two additional command line arguments --tenx-cloud-token-path and --cell-annotation-model:

Example command:

cellranger count --id=sample345 \
     --libraries=libraries.csv \ 
     --transcriptome=/opt/refdata-gex-GRCh38-2020-A \ 
     --feature_ref=feature_ref.csv \
     --create-bam=true \ 
     --tenx-cloud-token-path=/path/to/10xcloud_token.json \
     --cell-annotation-model=auto \

To learn how to generate and access your 10x Cloud Analysis token, visit the cellranger annotate page.

Please note that the cell type annotation model is currently a beta feature.

By default, Cell Ranger uses all available system cores. To specify a different number of cores, use the --localcores option (e.g., --localcores=16 limits usage to sixteen cores). Control the memory allocation with --localmem, specifying the limit in gigabytes (GB).

For a complete listing of the arguments accepted, visit the Command Line Argument Reference page, or run cellranger count --help.

For help on which arguments to use to target a particular set of FASTQs, consult Specifying Input FASTQ Files for 10x Genomics pipelines.

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

Martian Runtime - v4.0.8
Running preflight checks (please wait)...
Checking sample info...
Checking FASTQ folder...
Checking reference...
Checking optional arguments...
...

A successful cellranger count run will conclude with a completion message that confirms the successful execution of the process. Typically, this message might look something like:

Waiting 6 seconds for UI to do final refresh.
Pipestance completed successfully!
yyyy-mm-dd hh:mm:ss Shutting down.
Saving pipestance info to "tiny/tiny.mri.tgz"

Cell Ranger outputs to a new folder named after the specified sample ID (e.g., /home/jdoe/runs/sample345). If this folder exists, Cell Ranger will treat it as an existing pipestance and try to resume the process.

Upon successful completion of the process, you can view the output web summary HTML file in any supported web browser and open the .cloupe file in Loupe Browser.

For detailed descriptions of all output files, please refer to the 3' Gene Expression Outputs page.