Cell Ranger6.1, printed on 11/05/2024
The cellranger pipeline outputs unfiltered (raw) and filtered feature-barcode matrices in two file formats: the Market Exchange Format (MEX), which is described on this page, and Hierarchical Data Format (HDF5), which is described in detail here.
Each element of the feature-barcode matrix is the number of UMIs associated with a feature (row) and a barcode (column):
| Type | Description |
|---|---|
| Unfiltered feature-barcode matrix | Contains every barcode from the fixed list of known-good barcode sequences that has at least one read. This includes background and cell associated barcodes. |
| Filtered feature-barcode matrix | Contains only detected cell-associated barcodes. For Targeted Gene Expression samples, non-targeted genes are removed from the filtered matrix. |
For sparse matrices, the matrix is stored in the Market Exchange Format (MEX). It contains gzipped TSV files with feature and barcode sequences corresponding to row and column indices respectively. For example, the matrices output may look like:
$ cd /home/jdoe/runs/sample345/outs $ tree filtered_feature_bc_matrix filtered_feature_bc_matrix ├── barcodes.tsv.gz ├── features.tsv.gz └── matrix.mtx.gz 0 directories, 3 files
Prior to Cell Ranger 3.0, the output matrix file format was different. In particular, the file genes.csv has been replaced by features.csv.gz to account for Feature Barcode technology, and the matrix and barcode files are now gzipped.
Note that the cellranger multi pipeline produces a filtered feature-barcode matrix called sample_feature_bc_matrix/. |
Features correspond to row indices. For each feature, its feature ID and name are stored in the first and second column of the (unzipped) features.tsv.gz file, respectively. The third column identifies the type of feature, which will be one of Gene Expression, Antibody Capture, CRISPR, or CUSTOM, depending on the feature type. Below is a minimal example features.tsv.gz file showing data collected for 3 genes and 2 antibodies.
$ gzip -cd filtered_feature_bc_matrix/features.tsv.gz ENSG00000141510 TP53 Gene Expression ENSG00000012048 BRCA1 Gene Expression ENSG00000139687 RB1 Gene Expression CD3_GCCTGACTAGATCCA CD3 Antibody Capture CD19_CGTGCAACACTCGTA CD19 Antibody Capture
For Gene Expression data, the ID corresponds to gene_id in the annotation field of the reference GTF. Similarly, the name corresponds to gene_name in the annotation field of the reference GTF. If no gene_name field is present in the reference GTF, gene name is equivalent to gene ID. Similarly, for Antibody Capture and CRISPR data, the id and name are taken from the first two columns of the Feature Reference CSV file.
For multi-species experiments, gene IDs and names are prefixed with the genome name to avoid name collisions between genes of different species e.g. GAPDH becomes hg19_GAPDH and Gm15816 becomes mm10_Gm15816.
Barcode sequences correspond to column indices:
$ gzip -cd filtered_feature_bc_matrices/barcodes.tsv.gz AAACCCAAGGAGAGTA-1 AAACGCTTCAGCCCAG-1 AAAGAACAGACGACTG-1 AAAGAACCAATGGCAG-1 AAAGAACGTCTGCAAT-1 AAAGGATAGTAGACAT-1 AAAGGATCACCGGCTA-1 AAAGGATTCAGCTTGA-1 AAAGGATTCCGTTTCG-1 AAAGGGCTCATGCCCT-1
Each barcode sequence includes a suffix with a dash separator followed by a number:
AAACCCAAGGAGAGTA-1
More details on the barcode sequence format are available in the barcoded BAM section.
R and Python support the MEX format, and sparse matrices can be used for more efficient manipulation, as described below:
The R package Matrix supports loading MEX format data, and can be easily used to load the sparse feature-barcode matrix, as shown in the example code below (edit file path to your matrix directory).
library(Matrix) matrix_dir = "/opt/sample345/outs/filtered_feature_bc_matrix/" barcode.path <- paste0(matrix_dir, "barcodes.tsv.gz") features.path <- paste0(matrix_dir, "features.tsv.gz") matrix.path <- paste0(matrix_dir, "matrix.mtx.gz") mat <- readMM(file = matrix.path) feature.names = read.delim(features.path, header = FALSE, stringsAsFactors = FALSE) barcode.names = read.delim(barcode.path, header = FALSE, stringsAsFactors = FALSE) colnames(mat) = barcode.names$V1 rownames(mat) = feature.names$V1
Cell Ranger represents the feature-barcode matrix using sparse formats (only the nonzero entries are stored) in order to minimize file size. All of our programs, and many other programs for gene expression analysis, support sparse formats.
However, certain programs (e.g. Excel) only support dense formats (where every row-column entry is explicitly stored, even if it's a zero). Here are a few methods for converting feature-barcode matrices to CSV:
The csv, os, gzip and scipy.io modules can be used to load a feature-barcode matrix into Python as shown below (edit file path to your matrix directory).
import csv import gzip import os import scipy.io # define MEX directory matrix_dir = "/opt/sample345/outs/filtered_feature_bc_matrix" # read in MEX format matrix as table mat = scipy.io.mmread(os.path.join(matrix_dir, "matrix.mtx.gz")) # list of transcript ids, e.g. 'ENSG00000243485' features_path = os.path.join(matrix_dir, "features.tsv.gz") feature_ids = [row[0] for row in csv.reader(gzip.open(features_path, mode="rt"), delimiter="\t")] # list of gene names, e.g. 'MIR1302-2HG' gene_names = [row[1] for row in csv.reader(gzip.open(features_path, mode="rt"), delimiter="\t")] # list of feature_types, e.g. 'Gene Expression' feature_types = [row[2] for row in csv.reader(gzip.open(features_path, mode="rt"), delimiter="\t")] barcodes_path = os.path.join(matrix_dir, "barcodes.tsv.gz") barcodes = [row[0] for row in csv.reader(gzip.open(barcodes_path, mode="rt"), delimiter="\t")]
To view the matrix as a data table and save as a CSV file with Python, we can convert it into a pandas dataframe with the following code:
import pandas as pd # transform table to pandas dataframe and label rows and columns matrix = pd.DataFrame.sparse.from_spmatrix(mat) matrix.columns = barcodes matrix.insert(loc=0, column="feature_id", value=feature_ids) matrix.insert(loc=0, column="gene", value=gene_names) matrix.insert(loc=0, column="feature_type", value=feature_types) # display matrix print(matrix) # save the table as a CSV (note the CSV will be a very large file) matrix.to_csv("mex_matrix.csv", index=False)
The output should look similar to:
feature_type gene feature_id AAACCCAAGGAGAGTA-1 AAACGCTTCAGCCCAG-1 ... Gene Expression MIR1302-2HG ENSG00000243485 0 0 Gene Expression FAM138A ENSG00000237613 0 0 Gene Expression OR4F5 ENSG00000186092 0 0 Gene Expression AL627309.1 ENSG00000238009 0 0 Gene Expression AL627309.3 ENSG00000239945 0 0 ...
You can convert a feature-barcode matrix to dense CSV format using the cellranger mat2csv command.
| WARNING: Dense files can be very large and may cause Excel to crash, or even fail in mat2csv if your computer doesn't have enough memory. For example, a feature-barcode matrix from a human reference (~33k genes) with ~3k barcodes uses at least 200MB of disk space. Our 1.3 million mouse neuron dataset, if converted to this format, would use more than 60GB of disk space. Thus, while you can use mat2csv for small datasets, we strongly recommend using R or Python (as shown in the sections above) to examine these matrix files. |
This command takes two arguments - an input matrix generated by Cell Ranger (either an HDF5 file or a MEX directory), and an output path for the dense CSV. For example, to convert a matrix from a pipestance named sample123 in the current directory, either of the following commands would work:
# convert from MEX $ cellranger mat2csv sample123/outs/filtered_feature_bc_matrix sample123.csv # or, convert from HDF5 $ cellranger mat2csv sample123/outs/filtered_feature_bc_matrix.h5 sample123.csv
You can then load sample123.csv into Excel.
Please see this Q&A article for shell commands to convert MEX files to CSV. This method creates a single file that is sparse (zeroes are ignored).