Question: I am analyzing V(D)J data on 10x Cloud and encounter the error 'V(D)J Chain detection failed'. How do I solve this error?
Answer: Explicitly set V(D)J chain type on 10x Cloud. The way to do this differs depending on whether the analysis is
cellranger vdj or
When running cellranger vdj on Cloud
For V(D)J-only analyses, run
cellranger vdj. Select chain type under the Advanced settings. Click on the View advanced settings button to expand the options.
Then, in the Chain section, use the dropdown menu to select either T cell receptors or B cell receptors.
When running cellranger multi on Cloud
For V(D)J data with gene expression data, preprocess the data jointly with
cellranger multi. Here, the FASTQ library type label enables the explicit chain type selection. Under Library or Feature Type, select one of the three explicit V(D)J chain types from the dropdown menu--T (Alpha Beta), T (Gamma Delta) or B. Do not select Single Cell V(D)J, which calls the automatic detection protocol.
By default, Cell Ranger will try to automatically determine the chain type from the data. When this fails, the complete error message will look something like the following. In order for Cell Ranger to automatically determine chain type, the sample library must meet the listed conditions.
V(D)J Chain detection failed for Sample foo in "/mnt/scratch/inputs/x/y".
Total Reads = 1000000
Reads mapped to TR = 49211
Reads mapped to IG = 3
In order to distinguish between the TR and the IG chain the following conditions need to be satisfied:
- A minimum of 10000 total reads
- A minimum of 5.0% of the total reads needs to map to TR or IG
- The number of reads mapped to TR should be at least 3.0x compared to the number of reads mapped to IG or vice versa
Please check the input data and/or specify the chain via the --chain argument.
To overcome this error on the command line, for
cellranger vdj explicitly set the
--chain parameter to either IG for BCRs or TR for TCRs. Documentation is at https://support.10xgenomics.com/single-cell-vdj/software/pipelines/latest/using/vdj#opt-arg-exp. For
cellranger multi, specify the chain type under the
feature_types column in the multi config CSV's libraries section. Choices are VDJ-B for BCRs, VDJ-T for alpha-beta TCRs or VDJ-T-GD for delta-gamma TCRs. Documentation is at https://support.10xgenomics.com/single-cell-vdj/software/pipelines/latest/using/multi#config.
- Delta-gamma analysis is only available with
cellranger multiand is officially unsupported although enabled. See Can I detect T cells with gamma-delta chains in my V(D)J data? for details.
If the immune cells are a small proportion of the sample cell population then this error may be expected. If this is not expected, or if immune cells were enriched by sorting, then please contact firstname.lastname@example.org for a sample prep consult and attach the Cell Ranger web summary report and cDNA and library traces.