Skip to content

Feature Reference CSV Filling Guide for Antibody Capture, CRISPR Guide Capture, and Cell Multiplexing ​

Author: SeekGene
Time: 18 min
Words: 3.5k words
Updated: 2026-10-13
Reads: 0 times
3' scRNA-seq 5' + Immune Profiling Analysis Guide

This document helps you fill in Feature Barcode information (Antibody, CRISPR, Hashing, etc.) for Cell Ranger analysis. Please select the appropriate content based on the product type and library construction method (3' / 5').

Table of Contents ​


General Notes for Filling the Reference Table ​

Product Overview ​

ProductDescriptionTarget
Antibody Capture (Cell Surface Protein / CITE-seq)Simultaneously quantify surface proteins in single-cell transcriptome sequencing using antibody-oligonucleotide tagsSurface proteins (e.g., CD3, CD4)
CRISPR Guide Capture (CRISPR screening / Perturb-seq)Capture sgRNAs in individual cells to link genetic perturbations with transcriptomic phenotypes (see "CRISPR Guide Capture" section)sgRNA sequences
Cell Multiplexing (Hashing / CellPlex CMO)Pool multiple samples for sequencing and computationally demultiplex them into individual samples using barcode tagsSample origin information

Basic Concepts (Common to All Products) ​

Whether for Antibody Capture, CRISPR Guide Capture, or Cell Multiplexing, Cell Ranger requires a Feature Reference CSV file that tells the software:

  1. The name and ID of each feature (antibody / sgRNA / Hashtag).
  2. The barcode sequence of each feature.
  3. The exact position and extraction pattern of the barcode sequence within the sequencing read.
  4. The type of analysis each feature belongs to (antibody, CRISPR, or multiplexing).

All product types share 6 common required columns with fixed column names and order. CRISPR products require 2 additional columns (see "CRISPR Guide Capture" section):

ColumnDescriptionRequired
idUnique feature ID (e.g., CD3, sgTP53-1, Hashtag1). Must not contain spaces, slashes, quotes, commas, or other special characters. Must not conflict with transcriptome gene names.✅ Required
nameFeature display name. Can be the same as id. Uniqueness not required. Displayed in matrix/features.tsv.gz. Same special character restrictions apply.✅ Required
readSequencing read containing the feature barcode. Typically R2 (rarely R1).✅ Required
patternFixed sequence indicating the barcode position within the read (see details below).✅ Required
sequenceBarcode sequence. For example, the antibody oligonucleotide sequence or the sgRNA protospacer sequence.✅ Required
feature_typeFeature type: Antibody Capture / CRISPR Guide Capture / Multiplexing Capture.✅ Required

Pattern Syntax ​

SymbolMeaning
5P or ^Indicates that the pattern starts matching from the beginning of the read. Can only appear at the start of the pattern. Use one or the other, not both.
3P or $Indicates that the pattern is at the end of the read. Can only appear at the end. Same as above.
NAny nucleotide (placeholder, not validated).
A / C / G / TFixed nucleotide that must match the sequence column exactly.
(BC)Marks the position of the actual Feature Barcode sequence. Must appear exactly once per pattern. Corresponds to the sequence column.

Pattern Examples:

  • 5PNNNNNNNNNN(BC): The pattern starts at the beginning of the read, and the sequence immediately after it is the sequence.

  • ^(BC): The sequence starts directly at the beginning of the read.

  • (BC)GTTTAAGAGCTAAGCTGGAA: The pattern sequence is GTTTAAGAGCTAAGCTGGAA, and the sequence is located before it.

  • TTCCAGCTTAGCTCTTAAAC(BC): The pattern sequence is TTCCAGCTTAGCTCTTAAAC, and the sequence is located after it.

  • The pattern length should be moderate: too long may be affected by sequencing errors, too short may not uniquely identify the sequence. For non-N fixed bases, a length of 12-20 bp is recommended.

  • Cell Ranger identifies and extracts the sequence based on the pattern, then matches it against the reference table. Up to one base mismatch is allowed, and a barcode correction algorithm is applied.

General Filling Guidelines (Must Check) ​

  • The file must be in pure ASCII / UTF-8 CSV format. Do not use Excel-saved files with full-width Chinese punctuation, BOM headers, or special characters.
  • Each row corresponds to a unique Feature Barcode. The id column must be unique across the entire file (including both antibodies and multiplexing tags in the same experiment) and must not conflict with gene names or probe IDs.
  • The id column should only contain letters, numbers, underscores _, and hyphens -. Do not use pipes |, commas, or spaces. Pipes have special meaning in multi config CSV.
  • If an experiment includes both antibody detection and sample multiplexing (Hashing), both feature sets must be written in the same Feature Reference CSV file (with different feature_type values). Do not split them into two files.
  • The sequence column must be verified as correct. For sequences sourced from vendors, cross-check against the latest sequence table provided by the antibody / sgRNA / Hashtag supplier. For CRISPR products, ensure the provided sequence is the sgRNA strand that is actually transcribed and sequenced. Incorrect sequences will result in the feature not being detected (zero counts).

Antibody Capture ​

Antibody Capture assays typically use BioLegend TotalSeq™ series. The position of the barcode sequence within the R2 read varies by antibody type.

5' sample Antibody Capture libraries use the _Pro suffix in sample names, while 3' sample libraries use the _ADT suffix. The feature_type is always Antibody Capture.

TotalSeq-A (Compatible with 3' v2 / v3 kits) ​

  • Compatible data type: 3' gene expression (Single Cell 3' v2 / v3).
  • The barcode sequence starts at the very beginning of the R2 read (no preceding spacer sequence).
  • read = R2, pattern = 5P(BC).

Example (only modify id / name / sequence according to your actual experiment):

csv
id,name,read,pattern,sequence,feature_type
CD3,CD3_TotalSeqA,R2,5P(BC),ATTGGCACTCAGATG,Antibody Capture
CD4,CD4_TotalSeqA,R2,5P(BC),TACCCGTAATAGCGT,Antibody Capture

Download template

TotalSeq-B (Compatible with 3') ​

  • Compatible data type: 3' gene expression.
  • The barcode sequence starts at the 10th base of the R2 read (preceded by a 10 bp random sequence).
  • read = R2, pattern = 5PNNNNNNNNNN(BC).

Example (only modify id / name / sequence according to your actual experiment):

csv
id,name,read,pattern,sequence,feature_type
CD3,CD3_TotalSeqB,R2,5PNNNNNNNNNN(BC),AACAAGACCCTTGAG,Antibody Capture
CD4,CD4_TotalSeqB,R2,5PNNNNNNNNNN(BC),TACCCGTAATAGCGT,Antibody Capture

Download template

TotalSeq-C (Compatible with 5' / V(D)J) ​

  • Compatible data type: 5' gene expression / V(D)J immune profiling.
  • The barcode sequence also starts at the 10th base of the R2 read.
  • read = R2, pattern = 5PNNNNNNNNNN(BC).

Example (only modify id / name / sequence according to your actual experiment):

csv
id,name,read,pattern,sequence,feature_type
CD3,CD3_TotalSeqC,R2,5PNNNNNNNNNN(BC),CTCATTGTAACTCCT,Antibody Capture
CD19,CD19_TotalSeqC,R2,5PNNNNNNNNNN(BC),CTGGGCAATTACTCG,Antibody Capture

Download template


Cell Multiplexing ​

Cell multiplexing pools multiple samples for sequencing and computationally demultiplexes them using barcode tags (Hashtag / CMO). 10x Genomics supports the following multiplexing methods. Please confirm which one you are using:

Multiplexing MethodPlatformTag SourceFeature Reference Required?
Antibody Capture Hashing (TotalSeq Hashtag)3' or 5' gene expressionHashtag sequences from antibody vendors✅ Required
3' CellPlex (CMO)3' gene expression10x official CMO tags (built-in, usually no custom reference needed)Not required when using official CMOs; required when using third-party / custom tags (e.g., TotalSeq for Hashing)

Currently, 3' multiplexing data filenames usually end with _HTO. 5' multiplexing libraries use the _Pro suffix.

Antibody Capture Hashing (Most Common, Surface Protein-Based Multiplexing) ​

When using TotalSeq-A / B / C Hashtag antibodies for sample multiplexing:

  • Provide a custom Feature Reference. The format is identical to that of the corresponding TotalSeq antibody type.
  • Inform us in advance that this is a surface protein-based multiplexing experiment, and which tags are multiplexing hashtags. This is important for downstream bioinformatics processing.
  • Set feature_type to Antibody Capture.
  • Multiplexing analysis requires Gene Expression data to be provided simultaneously. Multiplexing data alone cannot be analyzed.

Multiplexing with Surface Protein Hashtags Only ​

Example with TotalSeq-A Hashtag (for 3' data; only modify id / name / sequence according to your actual experiment):

csv
id,name,read,pattern,sequence,feature_type
TotalSeqA_Hashtag_1,TotalSeqA_Hashtag_1,R2,5P(BC),ATCACATCGTTGCCA,Antibody Capture
TotalSeqA_Hashtag_2,TotalSeqA_Hashtag_2,R2,5P(BC),CTCTAGGTTCCCACC,Antibody Capture
TotalSeqA_Hashtag_3,TotalSeqA_Hashtag_3,R2,5P(BC),AGCTCACTTGTCCTG,Antibody Capture
TotalSeqA_Hashtag_4,TotalSeqA_Hashtag_4,R2,5P(BC),GTATGTTCTGCAATT,Antibody Capture

Download template

Example with TotalSeq-B Hashtag (for 3' data; only modify id / name / sequence according to your actual experiment):

csv
id,name,read,pattern,sequence,feature_type
TotalSeqB_Hashtag_1,TotalSeqB_Hashtag_1,R2,5PNNNNNNNNNN(BC),GTCAACTCTTTAGCG,Antibody Capture
TotalSeqB_Hashtag_2,TotalSeqB_Hashtag_2,R2,5PNNNNNNNNNN(BC),TGATGGCCTATTGGG,Antibody Capture

Download template

Example with TotalSeq-C Hashtag (for 5' data; only modify id / name / sequence according to your actual experiment):

csv
id,name,read,pattern,sequence,feature_type
TotalSeqC_Hashtag_1,TotalSeqC_Hashtag_1,R2,5PNNNNNNNNNN(BC),GTCAACTCTTTAGCG,Antibody Capture
TotalSeqC_Hashtag_2,TotalSeqC_Hashtag_2,R2,5PNNNNNNNNNN(BC),TGATGGCCTATTGGG,Antibody Capture
TotalSeqC_Hashtag_3,TotalSeqC_Hashtag_3,R2,5PNNNNNNNNNN(BC),TTCCGCCTCTCTTTG,Antibody Capture
TotalSeqC_Hashtag_4,TotalSeqC_Hashtag_4,R2,5PNNNNNNNNNN(BC),AGTAAGTTCAGCGTA,Antibody Capture

Download template

Both Antibody Capture and Hashtag Multiplexing ​

When both Antibody Capture and Hashtag multiplexing are present, distinguish which are multiplexing hashtags by whether the id column contains "Hashtag".

For example, using TotalSeq-B as tags, TotalSeqB_Hashtag_1 and TotalSeqB_Hashtag_2 are multiplexing hashtags, while CD3_TotalSeqB, CD4_TotalSeqB, and CD8a_TotalSeqB are antibody tags.

Reference table example (modify id / name / sequence according to your actual experiment):

csv
id,name,read,pattern,sequence,feature_type
TotalSeqB_Hashtag_1,TotalSeqB_Hashtag_1,R2,5PNNNNNNNNNN(BC),GTCAACTCTTTAGCG,Antibody Capture
TotalSeqB_Hashtag_2,TotalSeqB_Hashtag_2,R2,5PNNNNNNNNNN(BC),TGATGGCCTATTGGG,Antibody Capture
CD3_TotalSeqB,CD3,R2,5PNNNNNNNNNN(BC),AACAAGACCCTTGAG,Antibody Capture
CD4_TotalSeqB,CD4,R2,5PNNNNNNNNNN(BC),TACCCGTAATAGCGT,Antibody Capture
CD8a_TotalSeqB,CD8a,R2,5PNNNNNNNNNN(BC),ATTGGCACTCAGATG,Antibody Capture

Download template

Bioinformatics Notes ​

During analysis, the bioinformatician will add sample_id and hashtag_ids entries in the [samples] section of the configuration file for sample demultiplexing (handled by bioinformatics, no additional information required).

The demultiplexed sample name, sample_id, and hashtag_ids must all match the id values.

csv
[samples]
sample_id,hashtag_ids
TotalSeqB_Hashtag_1,TotalSeqB_Hashtag_1
TotalSeqB_Hashtag_2,TotalSeqB_Hashtag_2

If the same sample uses multiple Hashtag antibodies (technical replicates), separate the IDs with a pipe |, e.g., ABHT-1|ABHT-2. Example (handled by bioinformatics, no additional information required):

WARNING

Please inform us in advance about such cases!

csv
[samples]
sample_id,hashtag_ids
Sample1,TotalSeqB_Hashtag_1|TotalSeqB_Hashtag_2
Sample2,TotalSeqB_Hashtag_3

3' CellPlex with CMO ​

CMO (Cell Multiplexing Oligo) uses lipid-anchored oligonucleotides for multiplexing.

  • Multiplexing analysis requires Gene Expression data to be provided simultaneously. Multiplexing data alone cannot be analyzed.
  • Set feature_type to Multiplexing Capture.
  • Confirm whether the CMO tags are the default Cell Ranger ones or custom.

Using 10x Official CMO Tags ​

10x provides 12 default CMO tags (CMO301-CMO312) built into Cell Ranger. If using official 10x tags, the Feature Reference CSV does not need to list the sequence column; only the CMO tag id values used are needed.

csv
id,name,read,pattern,sequence,feature_type
CMO301,CMO301,R2,5P(BC),ATGAGGAATTCCTGC,Multiplexing Capture
CMO302,CMO302,R2,5P(BC),CATGCCAATAGAGCG,Multiplexing Capture
CMO303,CMO303,R2,5P(BC),CCGTCGTCCAAGCAT,Multiplexing Capture
CMO304,CMO304,R2,5P(BC),AACGTTAATCACTCA,Multiplexing Capture
CMO305,CMO305,R2,5P(BC),CGCGATATGGTCGGA,Multiplexing Capture
CMO306,CMO306,R2,5P(BC),AAGATGAGGTCTGTG,Multiplexing Capture
CMO307,CMO307,R2,5P(BC),AAGCTCGTTGGAAGA,Multiplexing Capture
CMO308,CMO308,R2,5P(BC),CGGATTCCACATCAT,Multiplexing Capture
CMO309,CMO309,R2,5P(BC),GTTGATCTATAACAG,Multiplexing Capture
CMO310,CMO310,R2,5P(BC),GCAGGAGGTATCAAT,Multiplexing Capture
CMO311,CMO311,R2,5P(BC),GAATCGTGATTCTTC,Multiplexing Capture
CMO312,CMO312,R2,5P(BC),ACATGGTCAACGCTG,Multiplexing Capture

Download template

At runtime, the cmo_ids used are listed in the [samples] section of the configuration file for demultiplexing (handled by bioinformatics, no additional information required):

csv
[samples]
sample_id,cmo_ids
sample1,CMO301
sample2,CMO303

Using Custom CMO Tags ​

When using custom CMO tags, provide a complete Feature Reference CSV including id, name, read, pattern, and the actual sequence. Set feature_type to Multiplexing Capture.

Example (modify id / name / pattern / sequence according to your actual experiment):

csv
id,name,read,pattern,sequence,feature_type
HTO1,HTO1,R2,5PNNNNNNNNNN(BC),CTCATTGTAACTCCT,Multiplexing Capture
HTO2,HTO2,R2,5PNNNNNNNNNN(BC),CTGGGCAATTACTCG,Multiplexing Capture

Download template

At runtime, the configuration file specifies the custom cmo-set reference file location and the cmo_ids (handled by bioinformatics, no additional information required):

csv
[gene-expression]
reference,/path/to/transcriptome
cmo-set,/path/to/custom_cmo_ref.csv
create-bam,true
[samples]
sample_id,cmo_ids
sample1,HTO1
sample2,HTO2

If the same sample uses multiple CMO tags (technical replicates), separate the IDs with a pipe |, e.g., CMO301|CMO302. Example:

WARNING

Please inform us in advance about such cases!

csv
[samples]
sample_id,cmo_ids
sample1,CMO301|CMO302
sample2,CMO303|CMO304

CRISPR Guide Capture ​

CRISPR Guide Capture detects sgRNAs (protospacers) introduced into individual cells. The Feature Barcode is the sgRNA protospacer sequence itself.

CRISPR products have 8 information columns (2 additional columns beyond the common 6):

ColumnDescriptionRequired
idUnique feature ID. Must not contain spaces, slashes, quotes, commas, or other special characters. Must not conflict with transcriptome gene names.✅ Required
nameFeature display name. Can be the same as id. Uniqueness not required. Displayed in matrix/features.tsv.gz. Same special character restrictions apply.✅ Required
readR2✅ Required
patternFixed sequence indicating the barcode position within the read. Typically 12-20 bp.✅ Required
sequenceThe sgRNA protospacer sequence. Must be unique across all features.✅ Required
feature_typeCRISPR Guide Capture✅ Required
target_gene_idTarget gene ID, e.g., ENSG00000113812✅ Required (required for perturbation effect analysis; can be left empty when only sgRNA counting is needed)
target_gene_nameTarget gene name, e.g., ACTR8✅ Required

Filling Guidelines ​

  • The sequence column should contain the protospacer sequence of each sgRNA, excluding the scaffold sequence. The length must match the actual design.
  • target_gene_id filling guidance:
    • Required: When perturbation effect analysis is needed, both target_gene_id and target_gene_name must be filled, and must match the gene_id and gene_name in the genome GTF file.
    • Can be left empty: When only sgRNA counting is needed (e.g., QC, sgRNA detection rate statistics) and perturbation effect analysis is not required, target_gene_id can be left empty (but target_gene_name must still be filled).
    • Validation is performed during analysis; entries not found in the genome will cause analysis failure.
  • 5' CRISPR requires special attention to sgRNA sequence orientation: The sequencing read direction is 5' to 3'. However, in 5' CRISPR Guide Capture libraries, the sgRNA is captured in the reverse orientation. Therefore, the pattern in the Feature Reference CSV must be the reverse complement of the original design sequence, not the forward sequence. For 5' CRISPR Guide Capture experiments, please confirm whether you are providing the "original sequence" or the "converted sequence". If in doubt, communicate in advance to avoid rework due to orientation errors.
  • sgRNA sequences must not be duplicated. If different genes share identical sgRNA sequences by accident, please check and communicate with us in advance to avoid analysis failure or ambiguous counting.
  • Confirm whether Non-Targeting controls are included. If so, list them separately and clearly label them as Non-Targeting in the id / name fields for downstream analysis to distinguish negative controls.

3' CRISPR Example (fill in according to your actual experiment):

csv
id,name,read,pattern,sequence,feature_type,target_gene_id,target_gene_name
ACTR8-1,ACTR8-1,R2,(BC)GTTTAAGAGCTAAGCTGGAA,GAAGGGCGGCGAGAAGGAGA,CRISPR Guide Capture,ENSG00000113812,ACTR8
ACTR8-2,ACTR8-2,R2,(BC)GTTTAAGAGCTAAGCTGGAA,GAGAACGGAAAGGAGAAGGG,CRISPR Guide Capture,ENSG00000113812,ACTR8
NEG_CTRL-1,NEG_CTRL-1,R2,(BC)GTTTAAGAGCTAAGCTGGAA,GACCGGGGGGGTGCGATGTA,CRISPR Guide Capture,Non-Targeting,Non-Targeting
NEG_CTRL-2,NEG_CTRL-2,R2,(BC)GTTTAAGAGCTAAGCTGGAA,GTGTACTAGTGACGACTATA,CRISPR Guide Capture,Non-Targeting,Non-Targeting

Download template

5' CRISPR Example (fill in according to your actual experiment):

csv
id,name,read,pattern,sequence,feature_type,target_gene_id,target_gene_name
ACTR8-1,ACTR8-1,R2,TTCCAGCTTAGCTCTTAAAC(BC),TCTCCTTCTCGCCGCCCTTC,CRISPR Guide Capture,ENSG00000113812,ACTR8
ACTR8-2,ACTR8-2,R2,TTCCAGCTTAGCTCTTAAAC(BC),CCCTTCTCCTTTCCGTTCTC,CRISPR Guide Capture,ENSG00000113812,ACTR8
NEG_CTRL-1,NEG_CTRL-1,R2,TTCCAGCTTAGCTCTTAAAC(BC),TACATCGCACCCCCCCGGTC,CRISPR Guide Capture,Non-Targeting,Non-Targeting
NEG_CTRL-2,NEG_CTRL-2,R2,TTCCAGCTTAGCTCTTAAAC(BC),TATAGTCGTCACTAGTACAC,CRISPR Guide Capture,Non-Targeting,Non-Targeting

Download template

Special Pattern Handling: 3' vs 5' Comparison ​

Comparison Item3' CRISPR5' CRISPR
Capture orientationForward captureReverse capture
pattern fillingUse the scaffold upstream sequence from the original designUse the reverse complement of the original design sequence
pattern example(BC)GTTTAAGAGCTAAGCTGGAATTCCAGCTTAGCTCTTAAAC(BC)
sequence orientationOriginal protospacer sequenceOriginal protospacer sequence (unchanged)

IMPORTANT

The most common error in 5' CRISPR is the pattern sequence orientation. Please confirm: the pattern is the reverse complement of the scaffold upstream sequence, not the forward sequence. If in doubt, communicate in advance to avoid rework due to orientation errors.

Pattern Sequence Confirmation Example ​

This example uses a 5' + CRISPR product based on Addgene: lentiCRISPR v2. The pattern sequence can be confirmed on the Addgene website.

Navigate to the sequence page and locate the sgRNA scaffold sequence:

The basic structure of the gRNA transcript from 5' to 3' is:

5' -- guide sequence (spacer) + sgRNA scaffold -- 3'

  • guide sequence: The variable region designed to target a specific gene. This is the only variable part in the experiment.
  • sgRNA scaffold: The constant backbone sequence within the same vector system, responsible for Cas9 protein binding.

Therefore, the pattern sequence is located at the 5' end of the scaffold. Considering that the length should be moderate (too long may be affected by sequencing errors, too short may not uniquely identify the sequence), we selected the 20 bp GTTTTAGAGCTAGAAATAGC immediately upstream of the scaffold as the pattern. For 5' + CRISPR experiments (reverse capture), the reverse complement is taken, resulting in the final pattern GCTATTTCTAGCTCTAAAAC(BC).


Pre-Submission Checklist ​

The following items are arranged in actual filling order. Please check each item:

  • [ ] Step 1: Confirm the specific product combination (3' / 5', V(D)J or not, CRISPR or not, multiplexing or not) and the sample-to-tag mapping table.
  • [ ] Step 2: Create the file as UTF-8 / ASCII plain text CSV, ensuring no full-width Chinese commas and no BOM header.
  • [ ] Step 3: Fill in header columns strictly as id,name,read,pattern,sequence,feature_type (CRISPR additionally requires target_gene_id,target_gene_name), order must not be changed.
  • [ ] Step 4: Ensure id is unique across the entire file, with no spaces, commas, or pipes.
  • [ ] Step 5: Confirm read and pattern match the selected library chemistry (3' TotalSeq-A → 5P(BC); 3' TotalSeq-B/C → 5PNNNNNNNNNN(BC); CRISPR 3' → (BC)...; CRISPR 5' → ...reverse complement(BC)).
  • [ ] Step 6: Verify sequence is correct, and the length matches the expected length of (BC) in the pattern.
  • [ ] Step 7: Confirm feature_type is correct: Antibody Capture → Antibody Capture; CRISPR → CRISPR Guide Capture; Multiplexing (Hashtag) → Antibody Capture; Multiplexing (CMO) → Multiplexing Capture.
  • [ ] Step 8: If both antibody detection and sample multiplexing are included, both must be in the same Feature Reference CSV file.

If you are unsure about any of the above, please contact us before submitting to avoid rework due to file format or field errors.


References ​

0 comments·0 replies