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

10x Genomics
Chromium Single Cell Gene Expression

Running cellranger aggr

In this tutorial, you will learn how to:

The cellranger aggr pipeline is optional. It is used to aggregate, or combine two cellranger count runs together. With experiments involving multiple samples, and multiple 10X Chromium GEM wells, libraries must each be processed in separate runs of cellranger count.

To compare samples to each other for differential expression analysis, cellranger aggr is used to combine output files from each run of cellranger count to produce one single feature-barcode matrix and a .cloupe file for visualizing with Loupe Browser.

Overview of cellranger aggr

First run the cellranger aggr pipeline with the ----help command to print the usage statement and view the input requirements.

cellranger aggr --help

The output is similar to the following:

cellranger aggr (3.1.0)
Copyright (c) 2019 10x Genomics, Inc.  All rights reserved.
The commands below should be preceded by 'cellranger':
    aggr   [options]
    aggr -h | --help | --version

This pipeline has two inputs:

CSV stands for comma separated value. For specific instructions for creating this CSV, see the cellranger aggr page.

The CSV file is a two column file. The first column is for the library id. This id can be anything you want. Choose descriptive ids since they are used later in analysis. The second column contains the paths to the molecule_info.h5 output files from the cellranger count pipelines.

Get Data

Use the following publicly available molecule_info.h5 files:

Start by making a directory to run the aggr pipeline in.

mkdir ~/yard/run_cellranger_aggr
cd ~/yard/run_cellranger_aggr

Next, download the data files.

wget https://cf.10xgenomics.com/samples/cell-exp/3.0.0/pbmc_1k_v3/pbmc_1k_v3_molecule_info.h5
wget https://cf.10xgenomics.com/samples/cell-exp/3.0.0/pbmc_10k_v3/pbmc_10k_v3_molecule_info.h5

These are small files, less than1GB each and usually take less than one minute to download.

The next step is to build the CSV file. The path to the hdf5 f just downloaded is needed. From the same directory where the files were downloaded , use the pwd command to find the path.


The output is similar to the following:


Copy the path to make the CSV file. Use the text editor of your choice to make this file. This example uses nano.

nano pbmc_aggr.csv

This opens the nano text editor. This is a Linux program. To access the command prompt again, exit from this program.


Paste the text above into the editor. Edit the path to each molecule_info.h5file so it matches the path copied above, pointing to the path of the file on your system.

Exit out of the nano text edtior by pressing Ctrl-x and answering Y to save the file.

Save modified buffer (ANSWERING "No" WILL DESTROY CHANGES) ?                                                                                                    
 Y Yes
 N No           ^C Cancel

It asks you:

File Name to Write: pbmc_aggr.csv 

Press Enter to confirm keeping this filename and saving the file. Now you are back to the command prompt.

Save the file and out of the nano text editor, which is a Linux-formatted CSV file.

Setup the Command for cellranger aggr

Next, build the command line and run it.

cellranger aggr --id=1k_10K_pbmc_aggr --csv=pbmc_aggr.csv

Run cellranger aggr

The output is similar to the following:

cellranger aggr (3.1.0)
Copyright (c) 2019 10x Genomics, Inc.  All rights reserved.


Waiting 6 seconds for UI to do final refresh.
Pipestance completed successfully!

2019-09-13 18:22:07 Shutting down.
Saving pipestance info to 1k_10K_pbmc_aggr/1k_10K_pbmc_aggr.mri.tgz

Explore the Output of cellranger aggr

Just like the other pipelines, when you see “Pipestance completed successfully!” the job is done, and the pipeline outputs are in the pipestance directory in the outs folder. List the contents of this directory:

ls -1 1k_10K_pbmc_aggr/outs/

The output is similar to the following:


The outputs are similar to those from the cellranger count pipeline, with the exception of the BAM files and molecule_info.h5 files.

Other Tutorials in this Series