The Libraries CSV file declares the input FASTQ data for the libraries that make up a Feature Barcode experiment. It is a required input file when analyzing Feature Barcode libraries with cellranger count.
For a complete list of input files required to run specific Cell Ranger pipelines, please refer to the List of inputs page.
Libraries CSV is passed to cellranger count with the --libraries flag, and declares the FASTQ files and library type for each input dataset.
A typical Feature Barcode analysis will have a Single Cell Gene Expression library, and one or more Feature Barcode libraries (Antibody Capture and CRISPR Guide Capture).
For experiments that include Feature Barcode libraries, the --libraries option replaces the --fastqs option, providing a structured way to input multiple libraries into the analysis pipeline.
The Libraries CSV is not required when running cellranger multi because library information is directly input into the [libraries] section of the multi config CSV.
This table describes the columns that should be included the Libraries CSV file:
| Column Name | Description |
|---|---|
fastqs | The absolute path to the directory containing the demultiplexed FASTQ files for a sample and is used in place of the --fastqs argument when analyzing two or more libraries. Comma-delimited paths are not accepted. If you have multiple sets of FASTQs for this library, add a separate row for each set and use the same library_type value. |
sample | Same as the --sample option of cellranger count. Sample name assigned in the bcl2fastq sample sheet. Details are provided in the Cell Ranger Commands page. |
library_type | Must match a valid library type as described in the Library/Feature Types section. FASTQ data is interpreted from rows in the Feature Reference file. The algorithm matches feature_type from the Feature Reference CSV with library_type. This field is case-sensitive. Must be Gene Expression for the Single Cell Gene Expression libraries (same for Targeted Gene Expression). For Feature Barcode libraries, must be one of Custom, Antibody Capture (for Cell Surface Protein), or CRISPR Guide Capture. Use Antibody Capture (for TotalSeq™-C). |
When inputting Feature Barcode data to Cell Ranger via the Libraries CSV file, you must declare the library_type of each library. Specifying the library_type enables additional downstream processing, particularly for libraries involving CRISPR Guide Capture and Antibody Capture.
This table outlines the types of libraries that can be specified and their implications for downstream processing:
| library_type | Description |
|---|---|
Antibody Capture | For use with experiments measuring cell surface protein expression levels via an antibody and/or antigen-multimer staining assay. Enables a t-SNE projection of the cells using only the Antibody Capture / Cell Surface Protein feature counts. This projection is available in an output file and in Loupe Browser. See the Antibody Capture Algorithm page for more details. |
CRISPR Guide Capture | Enables analysis of gene expression changes caused by the presence of CRISPR perturbations, in a Perturb-Seq style assay. See the CRISPR Guide Capture Algorithm page for more details. This mode also creates a t-SNE projection using only the CRISPR guide counts. This projection is available in an output file and in Loupe Browser. |
Custom | Provides processing of the Feature Barcode reads and a basic summary of the sequencing quality and library quality, but performs no special processing of the Feature Barcode counts. |
This section has a few example Libraries CSVs. Copy+Paste the most relevant example into a file, customize it for your experiment, and save it as a CSV. Alternatively, you may download this Libraries CSV template and customize it. Be sure to use the absolute path to your FASTQ files.
In this example, we have demultiplexed sequencing data from two libraries named GEX_sample1 and CRISPR_sample1 on the bcl2fastq/bcl-convert/mkfastq sample sheet. This generated two FASTQ files named GEX_sample1_S0_L001_R1_001.fastq.gz and CRISPR_sample1_S0_L001_R1_001.fastq.gz in the path /opt/foo (be sure to use the correct full path to your FASTQ files). We pass the FASTQ sample names and paths to Cell Ranger with the appropriate library types:
fastqs,sample,library_type,
/opt/foo/,GEX_sample1,Gene Expression,
/opt/foo/,CRISPR_sample1,CRISPR Guide Capture,
In this example, we have demultiplexed sequencing data from three libraries named GEX_sample3, Ab_sample3, and CRISPR_sample3 on the bcl2fastq / bcl-convert/ mkfastq sample sheet. The result is three FASTQ files named GEX_sample3_S0_L001_R1_001.fastq.gz, Ab_sample3_S0_L001_R1_001.fastq.gz, and CRISPR_sample3_S0_L001_R1_001.fastq.gz in the path /opt/foo (be sure to use the correct full path to your FASTQ files). We pass the FASTQ sample names to Cell Ranger with the appropriate library types:
fastqs,sample,library_type,
/opt/foo/,GEX_sample3,Gene Expression,
/opt/foo/,Ab_sample3,Antibody Capture,
/opt/foo/,CRISPR_sample3,CRISPR Guide Capture,
In this example, we have demultiplexed sequencing data from three libraries named GEX_sample4, Ab_sample4, and Ag_sample4 on the bcl2fastq / bcl-convert / mkfastq sample sheet. The result is three FASTQ files named GEX_sample4_S0_L001_R1_001.fastq.gz, Ab_sample4_S0_L001_R1_001.fastq.gz, and Ag_sample4_S0_L001_R1_001.fastq.gz in the path /opt/foo (be sure to use the correct full path to your FASTQ files). We pass the FASTQ sample names to Cell Ranger with the appropriate library types:
fastqs,sample,library_type,
/opt/foo/,GEX_sample4,Gene Expression,
/opt/foo/,Ab_sample4,Antibody Capture,
/opt/foo/,Ag_sample4,Antibody Capture,
Any antigen libraries produced via antigen-multimer staining should be designated as Antibody Capture in the libraries.csv and feature_reference.csv files, as illustrated in the example above."
The Antigen Capture feature type is only applicable to Barcode Enabled Antigen Mapping (BEAM) assays. Antigen Capture libraries generated using the BEAM workflow cannot be analyzed using cellranger count. Please use cellranger multi.