Cell Ranger Feature Reference CSV

A Feature Reference CSV file is essential file for detailing the unique Feature Barcode sequence, and its location in the sequencing read. This CSV should contain columns for the feature name, identifier, the corresponding Feature Barcode sequence, and a pattern to extract this sequence from the read sequence.

This CSV file is a required input for the cellranger count and cellranger multi pipelines when processing Feature Barcode data. For a complete list of input files required to run specific Cell Ranger pipelines, please refer to the List of inputs page.

For cellranger count, the CSV file should be specified using the --feature-ref option. An example cellranger count command with this flag is provided on the count page.
For cellranger multi, a path to the CSV should be included in the [feature] section of the multi config CSV.

Each line in the CSV corresponds to one unique Feature Barcode. The CSV can contain only ASCII characters to ensure compatibility.

This table describes the columns in the Feature Reference CSV file. Several example files are provided below.

Column Name	Description
`id`	Unique ID used to track feature counts. May only include ASCII characters and exclude whitespaces, slashes, quotes, or commas. Each ID must be unique and must not overlap with any gene identifier from the transcriptome.
`name`	Human-readable name for this feature. May only include ASCII characters and exclude whitespaces, slashes, quotes, or commas. This name will be displayed in the Loupe Browser Active Feature list.
`read`	Specifies which RNA sequencing read contains the Feature Barcode sequence. Must be `R1` or `R2`. Note: in most cases, `R2` is the appropriate choice.
`pattern`	Specifies how to extract the Feature Barcode sequence from the read. See the Feature Barcode extraction pattern section below for details.
`sequence`	Nucleotide barcode sequence associated with this feature. E.g., antibody barcode or sgRNA protospacer sequence.
`feature_type`	Specifies the type of feature being analyzed. Ensure that each `feature_type` in the Feature Reference matches a corresponding `library_type` in the Libraries CSV (for `cellranger count`) or `feature_types` in `[libraries]` section of the multi config CSV (for `cellranger multi`). FASTQ data noted in the Libraries CSV file under a `library_type` that aligns with the `feature_type` will be analyzed for occurrences of this feature, linking library setup and feature detection accurately. See available options for count and multi pipelines. This field is case-sensitive.
`mhc_allele`	Only relevant for BEAM-T (TCR Antigen Capture). Defines the MHC allele associated with each antigen included in the experiment. See the Feature Reference section on the Antigen Capture page for more details.

Important

Cell Ranger v4.0 and later offers support for an 'un-tethered' Feature Barcode pattern, (BC), in the Feature Reference CSV. This feature allows users to specify the sequence of the Feature Barcode without the need to specify its specific location (tether) on the read. However, it is important to note that utilizing the un-tethered pattern, particularly in experiments with a large number of guide RNAs, may potentially slow down your Cell Ranger run. To ensure optimal performance, it is recommended to use a tether whenever feasible.

The pattern field of the feature reference defines how to locate the Feature Barcode within a read. The Feature Barcode may appear at a known offset with respect to the start or end of the read or may appear at a fixed position relative to a known anchor sequence. The pattern column can be made up of a combination of these elements:

5P: denotes the beginning of the read sequence. May appear zero or one time, and must be at the beginning of the pattern. Only 5P or 3P may appear, not both (^ may be used instead of 5P).
3P: denotes the end of the read sequence. May appear zero or one time, and must be at the end of the pattern ($ may be used instead of 3P).
N: denotes an arbitrary base.
A, C, G, T: denotes a fixed base that must match the read sequence exactly.
(BC): denotes the Feature Barcode sequence as specified in the sequence column of the feature reference. Must appear exactly once in the pattern.

Any constant sequences made up of A, C, G, and T in the pattern must match exactly in the read sequence. Any N in the pattern is allowed to match a single arbitrary base. A modest number of fixed bases should be used to minimize the chance of a sequencing error disrupting the match. The fixed sequence should also be long enough to uniquely identify the position of the Feature Barcode. For feature types that require a non-N anchor, we recommend 12bp-20bp of constant sequence.

The extracted Feature Barcode sequence is aligned to the feature reference and up to one base mismatch is allowed. The extracted Feature Barcode sequences are corrected up to a Hamming distance of one base with the 10x Genomics barcode correction algorithm.

TotalSeq™-B is a line of antibody-oligonucleotide conjugates supplied by BioLegend that are compatible with the Single Cell 3' assay. The Feature Barcode sequence appears at a fixed position (10th base) in the R2 read.

read	pattern
R2	5PNNNNNNNNNN(BC)

Example dataset
Example TotalSeq™-B Feature Reference CSV (Please refer to BioLegend for the latest conjugated Feature Barcode information.)

TotalSeq™-C is a line of antibody-oligonucleotide conjugates supplied by BioLegend that are compatible with the Single Cell 5' assay. The Feature Barcode sequence appears at a fixed position (10th base) in the R2 read.

read	pattern
R2	5PNNNNNNNNNN(BC)

Example dataset
Example TotalSeq™-C Feature Reference CSV (Please refer to BioLegend for the latest conjugated Feature Barcode information.)

The feature reference for Immudex's dMHC Dextramer® libraries with dCODE Dextramers has the same feature barcode pattern as TotalSeq™-C. Use "Antibody Capture" in the feature_type column for dextramer or multimer reagents. Therefore, the same feature reference example for TotalSeq™-C can also be used for MHC Dextramer® libraries.

To analyze Barcode Enabled Antigen Mapping (BEAM) libraries, visit the corresponding 5' Immune Profiling page.

TotalSeq™-A is a line of antibody-oligonucleotide conjugates supplied by BioLegend that are compatible with the Single Cell 3' v2 and Single Cell 3' v3 kits. The Feature Barcode sequence appears at the start of the R2 read.

Although TotalSeq™-A can be used with the CITE-Seq assay, CITE-Seq is not a 10x Genomics-supported assay. Please contact New York Genome Center or BioLegend for assistance with the assay or software.

read	pattern
R2	5P(BC)

Example TotalSeq™-A Feature Reference CSV (Please refer to BioLegend for the latest conjugated Feature Barcode information.).

Proteintech Genomics (PTG) provides a line of antibody cocktails targeting intracellular and cell surface proteins, fully compatible with the 10x Genomics Single Cell Gene Expression Flex platform.

For PTG-derived Antibody Capture libraries, the Feature Barcode sequence appears at the start of the R2 read.

read	pattern
R2	5P(BC)

The sequencing configuration for PTG-derived Antibody Capture libraries is detailed in this Knowledge Base article.

Cell Ranger can also analyze mixed Antibody Capture libraries containing both BioLegend and PTG antibody-labeled cells, provided that the library is sequenced using the Read 1 sequencing configuration (Read 1: 48 cycles; i7 index: 10 cycles; i5 index: 10 cycles; Read 2: 50 cycles).

Example PTG Feature Reference CSV


id,name,read,pattern,sequence,feature_type
POU2AF1,POU2AF1_PTG,R2,^(BC),GGTATCCGCAAGCGT,Antibody Capture
VIM,IM_PTG,R2,^(BC),ACATGCCTAGCTCCG,Antibody Capture
AHNAK,AHNAK_PTG,R2,^(BC),CTGCGTACAGGTGGA,Antibody Capture
BACH1,BACH1_PTG,R2,^(BC),GCCATCACGGCACGT,Antibody Capture
SYK,SYK_PTG,R2,^(BC),CGTGATGCGCTGACG,Antibody Capture

In CRISPR Guide Capture assays, the Feature Barcode sequence is the CRISPR protospacer sequence. The protospacer is followed by a downstream constant sequence in the guide RNA which is used as an anchor to identify the location of the protospacer. We recommend using a 12bp-20bp constant sequence that can be uniquely identified but is short enough that it is unlikely to be disrupted by a sequencing error.

The example Feature Reference CSV files list six guide RNA features, each with six distinct barcode/protospacer sequences (sequence column). The pattern column has the same pattern for all six features. We use the target_gene_id and target_gene_name columns to declare the target gene of each guide RNA, for use in downstream CRISPR perturbation analysis. Two guides are declared with target_gene_id as Non-Targeting. Cells containing Non-Targeting guides will be used as controls for CRISPR perturbation analysis. The four remaining guides target two genes.

Read	Pattern	Assay	Example
R2	(BC)GTTTAAGAGCTAAGCTGGAA	3’ Gene Expression with Feature Barcode	Download 3' CSV
R2	TTCCAGCATAGCTCTTAAAC(BC)	5’ Gene Expression with Feature Barcode and Fixed RNA Profiling	Download CSV

Columns in a Feature Reference CSV

Feature Barcode extraction pattern

Example Feature Reference CSVs

Antibody Capture with TotalSeq™-B

Antibody Capture with TotalSeq™-C

Antibody Capture with TotalSeq™-A

Antibody Capture with PTG

CRISPR Guide Capture