Mastering the MiXCR 10x-sc-xcr-vdj Preset: A Comprehensive Guide for Immune Repertoire Analysis

Lily Turner Feb 02, 2026 332

This article provides a detailed guide for researchers and drug development professionals on leveraging the MiXCR `analyze` command's `10x-sc-xcr-vdj` preset for single-cell V(D)J and paired Transcriptome analysis of 10x Genomics...

Mastering the MiXCR 10x-sc-xcr-vdj Preset: A Comprehensive Guide for Immune Repertoire Analysis

Abstract

This article provides a detailed guide for researchers and drug development professionals on leveraging the MiXCR `analyze` command's `10x-sc-xcr-vdj` preset for single-cell V(D)J and paired Transcriptome analysis of 10x Genomics data. It covers foundational concepts, step-by-step workflows, troubleshooting strategies, and comparative validation to ensure robust and reproducible analysis of adaptive immune receptor repertoires in single-cell resolution studies.

Demystifying the 10x-sc-xcr-vdj Preset: What It Is and Why It's Essential for Single-Cell Immune Profiling

Understanding the 10x-sc-xcr-vdj Preset's Role in the MiXCR Ecosystem

The mixcr analyze command, a cornerstone of the MiXCR platform for adaptive immune receptor repertoire (AIRR) analysis, offers specialized presets to standardize pipelines for diverse data modalities. The 10x-sc-xcr-vdj preset is explicitly engineered for processing single-cell V(D)J sequencing data generated by the 10x Genomics Chromium platform. This preset encapsulates a curated sequence of algorithmic steps and parameters optimized for the unique characteristics of linked-read, barcoded single-cell data, enabling the accurate assembly of full-length paired T-cell receptor (TCR) or B-cell receptor (BCR) sequences and their confident assignment to individual cells. Within the broader thesis of MiXCR's analytical ecosystem, this preset represents a critical bridge between raw single-cell sequencing output and biologically interpretable clonotype-by-cell matrices, forming the essential preprocessing foundation for downstream immune repertoire analysis at single-cell resolution.

Core Functions & Algorithmic Workflow

The mixcr analyze 10x-sc-xcr-vdj preset automates a multi-stage pipeline. The table below summarizes the key stages and their quantitative outputs.

Table 1: Core Pipeline Stages of the 10x-sc-xcr-vdj Preset

Stage Primary Function Key Quantitative Outputs
align Aligns reads to V, D, J, and C reference gene segments. Number of successfully aligned reads; alignment score distributions.
assemble Assembles aligned reads into contigs, corrects errors, and collapses UMIs. Number of assembled clonotypes per sample; consensus sequence quality scores.
exportClones Exports final clonotype tables with sequences and annotations. Clonal count, frequency, and proportion; CDR3 amino acid sequences.

The logical and data flow relationship between these stages, the input data, and final deliverables is depicted in the following workflow.

Diagram Title: 10x-sc-xcr-vdj Preset Data Workflow

Application Notes & Comparative Performance

The preset is optimized for key metrics critical in single-cell analysis: sensitivity (cell recovery), specificity (correct chain pairing), and accuracy (error-corrected sequences). The table below compares generalized performance expectations when using the preset versus a generic, non-optimized MiXCR pipeline on 10x data.

Table 2: Performance Comparison of Optimized vs. Generic Pipeline

Performance Metric 10x-sc-xcr-vdj Preset Generic Non-Optimized Pipeline Notes
Cell Recovery Rate High (>90% of cell barcodes) Variable, often lower Preset uses informed barcode filtering.
Chain Pairing Confidence High Low to Moderate Leverages 10x barcode/UMI linking.
Background Noise Low High Aggressive UMI-based error correction.
Runtime Efficiency Optimized Less Efficient Pre-set parameters reduce compute time.

Detailed Experimental Protocol

The following protocol details the steps for utilizing the 10x-sc-xcr-vdj preset in a standard single-cell TCR sequencing experiment from 10x Genomics libraries.

Protocol: Processing 10x Single-Cell V(D)J Data with MiXCR

I. Sample & Data Preparation

  • Library Preparation: Generate 5' gene expression and V(D)J libraries from PBMCs or tissue samples using the 10x Genomics Chromium Single Cell Immune Profiling Solution (e.g., kits v2 or v3) following the manufacturer's instructions.
  • Sequencing: Pool and sequence libraries on an Illumina platform. Target a minimum of 5,000 reads per cell for the V(D)J library.
  • Data Export: Use Cell Ranger (cellranger mkfastq) to demultiplex raw BCL files and generate paired-end FASTQ files (R1: cell/UMI barcode; R2: transcript insert).

II. MiXCR Analysis Execution

  • Command Execution: Run the following command in a terminal with MiXCR installed:

    Note: Specify 10x-chemistry-v2 or -v3 based on your kit version.
  • Output Files: The pipeline generates:
    • sample_output.vdjca: Binary alignment archive.
    • sample_output.clns: Binary clonotype archive.
    • sample_output.clonotypes.\[txt|tsv\]: Primary clonotype table.

III. Downstream Analysis Integration

  • Clonotype Table Parsing: Import the .clonotypes.tsv file into R/Python for analysis. Key columns include clonotypeId, aaSeqCDR3, nSeqCDR3, readCount, umiCount, and cellIds.
  • Integration with Gene Expression: Use the cellIds barcode list to merge clonotype data with 5' GEX data (e.g., from Seurat or Scanpy objects) using cellular barcodes as the key.

The Scientist's Toolkit: Essential Research Reagents & Materials

Table 3: Key Reagent Solutions for 10x SC V(D)J Experiments with MiXCR

Item / Reagent Function / Purpose Example Product
Single Cell Immune Profiling Kit Encapsulates cells, barcodes mRNA, and specifically enriches V(D)J transcripts. 10x Genomics Chromium Single Cell 5' v3 (Cat# 1000269)
Dual Index Kit TT Set A Provides unique sample indexes for multiplexing libraries during sequencing. 10x Genomics Single Index Kit (Cat# 1000215)
Cell Ranger Software Demultiplexes raw sequencing data and performs initial barcode processing. 10x Genomics Cell Ranger (v8.0+)
MiXCR Software Suite Executes the specialized analyze pipeline for immune repertoire reconstruction. MiXCR (v4.6+)
High-Quality Reference Genome Provides species-specific V, D, J, C gene segments for accurate alignment. 10x Genomics refdata-cellranger-vdj-GRCh38-alts-ensembl-[version]
Next-Generation Sequencer Generates high-throughput paired-end sequencing reads. Illumina NovaSeq 6000, NextSeq 2000

This Application Note details the functionality and implementation of the 10x-sc-xcr-vdj command preset within the MiXCR software ecosystem. The preset is engineered for the integrated analysis of single-cell multimodal 10x Genomics data, concurrently processing T- or B-Cell Receptor (VDJ) sequences, surface protein expression (C-Receptor via Feature Barcoding), and whole transcriptome (xCR) data from the same cellular barcodes. This integrated approach is critical for dissecting the complex relationships between clonality, cell phenotype, and functional state in immunology and oncology research.

Preset Workflow Architecture

The 10x-sc-xcr-vdj preset orchestrates a synchronized analysis pipeline. The core innovation lies in its ability to maintain cellular identity across disparate data modalities, allowing for a unified downstream interpretation.

Diagram Title: Integrated xCR Analysis Workflow

The preset generates comprehensive quantitative tables. Key integrated metrics are summarized below.

Table 1: Core Quantitative Outputs from the 10x-sc-xcr-vdj Pipeline

Metric Category Specific Output Description Typical Range/Example
Clonality Clonal Frequency Proportion of cells belonging to each unique clonotype. 0.001% - 50%
Clonotype Count Total number of distinct functional clonotypes detected. 100 - 100,000 per sample
Top 10 Clonotype Share Cumulative frequency of the ten most abundant clones. 5% - 80% (indicates clonal expansion)
Cell Identity Cells with VDJ + Transcriptome Number of cells with successfully assembled VDJ data and transcriptome. 1,000 - 50,000 cells
Cells with VDJ + C-Receptor Number of cells with VDJ and quantified surface protein data. 500 - 40,000 cells
Receptor Diversity Shannon Entropy Index Diversity index considering clonotype richness and evenness. 0 (monoclonal) - 10 (highly diverse)
Simpson Clonality Index Probability that two randomly selected cells are from the same clone. 0 (diverse) - 1 (monoclonal)
C-Receptor Integration Protein Expression per Clonotype Mean antibody-derived tag (ADT) counts for specific proteins (e.g., CD4, PD-1) aggregated by clone. Log2(ADT counts + 1)

Detailed Experimental Protocol

Protocol 1: Generating Integrated Data with 10x Chromium and MiXCR

Objective: To generate a unified dataset containing VDJ sequences, transcriptome, and surface protein expression from a single-cell suspension of human PBMCs or tumor infiltrating lymphocytes (TILs).

I. Sample Preparation & Library Generation (Wet-Lab)

  • Cell Preparation: Prepare a single-cell suspension with >90% viability. Target cell recovery should be 5,000-20,000 cells.
  • 10x Genomics Chip Loading: Use the Chromium Next GEM Single Cell 5' Kit v3 with Feature Barcoding technology for Cell Surface Protein and the Chromium Single Cell V(D)J Enrichment Kit. Load cells, Gel Beads, and partitioning oil onto a Chip G.
  • GEM Generation & Barcoding: Cells are co-partitioned with Gel Beads in the Chromium Controller. Within each GEM, reverse transcription occurs, adding a unique cell barcode and UMI to cDNA from poly-adenylated mRNA (transcriptome) and to oligonucleotide tags bound to antibody-derived feature barcodes (C-Receptor).
  • VDJ Enrichment: A separate aliquot of the cDNA pool undergoes targeted PCR enrichment for T-cell or B-cell receptor loci.
  • Library Construction: Construct separate sequencing libraries for: a) Gene Expression, b) Feature Barcode (C-Receptor), and c) V(D)J-enriched cDNA.

II. Data Generation & Primary Analysis (Computational)

  • Sequencing: Pool libraries and sequence on an Illumina platform. Recommended sequencing depth:
    • Gene Expression: ≥ 20,000 reads/cell
    • Feature Barcode: ≥ 5,000 reads/cell
    • V(D)J: ≥ 5,000 reads/cell
  • CellRanger Analysis: Run cellranger multi (or cellranger count + cellranger vdj) with the appropriate reference genomes (e.g., GRCh38 for transcriptome/VDJ, and a Feature Barcode reference CSV). This demultiplexes data by cell barcode and generates:
    • filtered_feature_bc_matrix.h5 (Transcriptome + C-Receptor counts)
    • vdj_contig_info.pb (Annotated VDJ contigs)

III. Integrated Analysis with MiXCR Preset (Computational)

  • Execute MiXCR Preset: Run the following command, which executes the multi-step preset in a single line:

  • Output Interpretation: Key output files include:
    • output_prefix.clonotypes.ALL.txt: Master table linking each cell barcode to its clonotype, CDR3 sequences, transcriptome cluster, and C-Receptor expression levels.
    • output_prefix.clones.tsv: Clonal-level summary statistics.

The Scientist's Toolkit: Essential Research Reagents & Materials

Table 2: Key Reagents and Solutions for Integrated xCR Experiments

Item Vendor/Example Function in Protocol
Chromium Next GEM Single Cell 5' Kit v3 10x Genomics (PN: 1000269) Provides reagents for GEM generation, barcoding, and cDNA synthesis for transcriptome and feature barcode libraries.
Chromium Single Cell V(D)J Enrichment Kit 10x Genomics (PN: 1000005/6) Contains primers for targeted amplification of human or mouse T-cell or B-cell receptor sequences.
TotalSeq-C Antibody Panels BioLegend Antibodies conjugated with oligonucleotide tags (Feature Barcodes) for detecting surface proteins (C-Receptors).
Dual Index Kit TT Set A 10x Genomics (PN: 1000215) Provides indexed primers for final library construction for all three libraries.
Cell Staining Buffer BioLegend (PN: 420201) Buffer for staining cells with TotalSeq antibodies prior to loading on the Chromium chip.
MiXCR Software Milaboratory Core analysis platform executing the 10x-sc-xcr-vdj preset for integrated data processing.
CellRanger Software Suite 10x Genomics Primary data processing software to generate input files (vdj_contig_info.pb, feature matrix) for MiXCR.
High-Viability Cell Suspension N/A Starting material. Critical for successful partitioning and library complexity.

Integrated Data Interpretation Pathway

The final integrated data allows for the interrogation of complex relationships, as visualized in the following logic pathway.

Diagram Title: Logic for Interpreting Integrated xCR Data

Within the context of a broader thesis on benchmarking and optimizing MiXCR analyze 10x-sc-xcr-vdj command presets for single-cell V(D)J repertoire analysis, a critical preliminary step is the accurate sourcing and preparation of input data. While Cell Ranger is the standard pipeline for processing 10x Genomics Chromium data, its primary output for V(D)J analysis is a filtered contig annotations file. For researchers utilizing third-party tools like MiXCR, which often require raw sequencing reads (FASTQ) as input, understanding the pathways from Cell Ranger outputs back to the original FASTQ files is essential. This protocol details the requirements and methodologies for data retrieval and preparation.

Data Input Pathways and Requirements

The following table summarizes the key file types and their roles in transitioning from Cell Ranger outputs to FASTQ re-analysis.

Table 1: Key File Types in the 10x V(D)J Data Processing Pipeline

File Type Typical Source Primary Use in Cell Ranger Required for MiXCR analyze 10x-sc-xcr-vdj? Notes
Raw BCL Files Illumina Sequencer Output Primary sequencing data. No (Indirectly) The fundamental output of the sequencing run.
FASTQ Files cellranger mkfastq Input for cellranger vdj. Yes Required as direct input for MiXCR's 10x preset.
Filtered Contig Annotations (CSV/JSON) cellranger vdj output (outs/) Primary output for clonotype analysis. No This is the result of Cell Ranger's assembly, not a valid input for MiXCR's 10x preset.
Web Summary File (web_summary.html) cellranger vdj output (outs/) QC and run metrics. No Critical for assessing sample quality prior to any analysis.
Libraries CSV File Experimental Design Specifies sample indexing for mkfastq. Possibly Needed if re-generating FASTQ from BCL files for multiplexed runs.

Protocol: Retrieving FASTQ Files for Re-analysis with MiXCR

Objective: To obtain the correct FASTQ file inputs for the MiXCR analyze 10x-sc-xcr-vdj command from a completed Cell Ranger V(D)J analysis.

Materials & Reagents

Research Reagent Solutions & Essential Materials:

  • Cell Ranger Suite (v7.0+): 10x Genomics proprietary software. Contains mkfastq, vdj, and bcl2fastq utilities.
  • Illumina BCL2FASTQ Conversion Software: Often integrated with Cell Ranger mkfastq. Converts base call (BCL) files to FASTQ format.
  • High-Performance Computing (HPC) Cluster or Cloud Instance: Recommended due to large file sizes and computational demands of FASTQ generation.
  • Sample Sheet (CSV Format): Metadata file defining sample index associations for demultiplexing.
  • Sufficient Storage Space: Raw BCL (hundreds of GBs) and FASTQ (tens of GBs per sample) files require substantial storage.

Methodology

Scenario A: FASTQ Files Are Archived If the original FASTQ files are accessible in lab storage or a genomic repository:

  • Locate Files: Identify the fastq_path directory from the original Cell Ranger vdj command. Typical structure: SampleID/outs/fastq_path/.
  • Verify Contents: Ensure the directory contains the three required FASTQ file pairs (R1, R2, I1) for each sample lane.
    • R1: Contains cDNA read (cell barcode + UMI + partial leader).
    • R2: Contains the actual V(D)J transcript sequence.
    • I1 (Index Read): Contains the sample index for demultiplexing (if multiple samples were pooled).
  • Link or Copy: Use these FASTQ files directly as the --fastq-files argument for MiXCR.

Scenario B: Only Raw BCL Files Are Available (Most Common) If only the sequencer's output (BCL files) is retained, regenerate FASTQs.

  • Prepare Inputs:
    • Navigate to the directory containing the Data/ folder from the Illumina run.
    • Ensure a valid libraries.csv sample sheet is available from the original experiment.
  • Execute cellranger mkfastq:

    • --id: Specifies the name of the new directory to create.
    • --run: Path to the folder containing the BCL files.
    • --samplesheet: CSV file linking sample names to index sequences.
  • Locate Output: The demultiplexed FASTQ files will be in OutputFastqName/outs/fastq_path/. Proceed to MiXCR analysis.

Experimental Workflow for Data Preparation

Title: Workflow from Sequencing to Analysis for 10x V(D)J Data

Signaling Pathway for Data Decision Logic

Title: Decision Logic for Sourcing FASTQ Inputs

Successful application of the MiXCR analyze 10x-sc-xcr-vdj preset is contingent upon correct input data preparation. Researchers must recognize that the standard Cell Ranger V(D)J output (filtered contigs) is not compatible. This protocol provides a clear decision framework and executable methods to secure the necessary FASTQ files, either from archives or by regenerating them from raw BCL data. Ensuring this foundational step is critical for the subsequent comparative analysis of clonotype calling accuracy and efficiency within the stated thesis context.

This Application Note details integrated protocols for the simultaneous analysis of adaptive immune receptor repertoires (AIRR) and whole-transcriptome data from single cells, specifically using the 10x Genomics Chromium Single Cell Immune Profiling solution. The methodologies are framed within the broader thesis of utilizing and validating the mixcr analyze 10x-sc-xcr-vdj command preset, a comprehensive pipeline within the MiXCR software suite. This pipeline is designed to process raw sequencing data from 10x V(D)J + Gene Expression libraries, aligning clonotype (VDJ sequence), isotype (constant region), and single-cell gene expression into a unified biological insight.

Key Research Reagent Solutions

Item Function
10x Genomics Chromium Next GEM Single Cell 5' Kit v2 Provides gel beads-in-emulsion (GEMs) for partitioning single cells, containing barcoded oligos for capturing 5' mRNA and V(D)J transcripts.
Chromium Single Cell V(D)J Enrichment Kit, Human B Cell Contains gene-specific primers to enrich for full-length V(D)J regions of B cell receptors (BCR), including constant region (C) genes for isotype calling.
Cell Ranger Multi (v8.0+) Primary software for demultiplexing, barcode processing, and initial V(D)J contig assembly. Outputs filtered contig annotations and expression matrices.
MiXCR (v4.6+) Advanced, calibratable pipeline for precise V(D)J alignment, clonotyping, and isotype assignment. Offers superior sensitivity and reproducibility for clonal analysis.
Seurat (v5.1+) / scRepertoire (v1.12+) R toolkits for integrating clonotype data with single-cell gene expression clusters, enabling phenotype-clonotype correlation analysis.

Core Experimental Protocol: From Sample to Integrated Data

Library Preparation and Sequencing

  • Cell Preparation: Generate a single-cell suspension from PBMCs or tissue (viability >90%, concentration 700-1200 cells/µL).
  • GEM Generation & Barcoding: Combine cells with Master Mix and Gel Beads containing barcoded oligos on a Chromium Chip. Incubate to form GEMs for reverse transcription. The 5' barcoded cDNA is generated.
  • V(D)J Enrichment: Amplify cDNA and perform two nested PCRs using the B cell V(D)J enrichment primers to specifically amplify full-length, rearranged V(D)J regions spanning the constant region.
  • Library Construction: Fragment and index the enriched V(D)J amplicons and the 5' gene expression cDNA to construct Illumina-ready libraries.
  • Sequencing: Pool libraries and sequence on an Illumina NovaSeq. Recommended sequencing depth: ≥5,000 read pairs per cell for Gene Expression, ≥5,000 read pairs per cell for V(D)J.

Computational Analysis viamixcr analyze 10x-sc-xcr-vdj

  • Input: Raw FASTQ files (sample_S1_L001_R1_001.fastq.gz, sample_S1_L001_R2_001.fastq.gz).
  • Command Execution:

  • Pipeline Stages (Automated):
    • Alignment: Aligns reads to V, D, J, and C gene reference sequences.
    • Assemble: Assembles aligned reads into full-length contigs for each cell barcode.
    • AssembleContigs: Further processes contigs.
    • ExportClones: Generates the final clonotype table.

Integration with Gene Expression

  • Process the 5' Gene Expression library with cellranger multi or cellranger count to generate a feature-barcode matrix and clusters.
  • Import the MiXCR clonotype table and the Cell Ranger output into R using the scRepertoire package.
  • Annotate the Seurat object with clonotype and isotype information.
  • Perform combined analysis: visualize clonal expansion across UMAP clusters, correlate isotype switching with differential gene expression.

Data Presentation: Key Metrics from a Representative B Cell Study

Table 1: Typical Output Metrics from a 10,000-cell Human PBMC B Cell Dataset processed with MiXCR

Metric Value Interpretation
Cells With Productive V-J Span 8,450 ~84.5% cell recovery rate for BCR data.
Median Reads Per Cell 5,120 Indicates sufficient sequencing depth for V(D)J.
Median UMIs Per Cell (GEX) 25,000 Indicates robust gene expression coverage.
Unique Clonotypes (CDR3aa) 6,210 Diversity of the B cell repertoire.
Clonal Expansion (Top 10 Clones) 15% of cells Proportion of cells belonging to the 10 largest clones.
Isotype Distribution (IgG1 dominant) 32% Most abundant switched isotype in this sample.

Table 2: Linkage Analysis Between Isotype and Differential Gene Expression (DEG)

Isotype Upregulated Genes (vs. Naïve B) Log2FC Adjusted p-value Associated Pathway
IgG1 TBX21, STAT4 +3.2, +2.1 <0.001 Th1-skewed B cell response
IgA CCR10, ALDH1A1 +4.1, +3.8 <0.001 Mucosal Homing
IgE IL4R, FCER2 +5.5, +2.7 <0.001 Type 2 Immunity

Visualization of Workflows and Biological Insights

Title: Single Cell BCR & GEX Analysis Workflow

Title: Isotype Switching & Differentiation Pathway

Step-by-Step Workflow: Running and Interpreting MiXCR analyze with the 10x-sc-xcr-vdj Preset

Application Notes

This document serves as an essential prerequisite guide for a broader thesis research project focusing on the systematic evaluation and optimization of MiXCR's analyze 10x-sc-xcr-vdj command preset. The ability to accurately and reproducibly process raw 10x Genomics Chromium single-cell V(D)J sequencing data is foundational for downstream analyses of adaptive immune receptor repertoires in contexts such as oncology, autoimmune disease research, and therapeutic antibody discovery. Proper installation and data preparation directly impact the quality of clonotype tables, repertoire metrics, and single-cell immune phenotype linking that form the basis of the thesis's comparative research.

Key considerations include ensuring version compatibility between MiXCR, Java runtime, and the structure of 10x Genomics Cell Ranger output directories. Failure to adhere to standardized input preparation can lead to errors in barcode whitelisting, chain pairing, or contig assembly, thereby compromising all subsequent analytical conclusions of the thesis.

Experimental Protocols

Protocol 1: Installation of MiXCR and Dependency Verification

This protocol details the installation of MiXCR and verification of its core dependencies.

  • Java Runtime Environment (JRE) Check:

    • Open a terminal/command line interface.
    • Execute java -version. Ensure version 8 or higher is installed. If not, install OpenJDK or Oracle JRE suitable for your operating system.

  • MiXCR Installation:

    • Download the latest standalone JAR file from the official MiXCR repository on GitHub (e.g., mixcr-<version>.jar).
    • For convenience, create an alias or add it to your system PATH. A common alias is: alias mixcr="java -jar /path/to/mixcr-<version>.jar".
    • Verify installation by running mixcr -v. This should print the version and citation information.

  • Test with Example Data:

    • Run mixcr test. This executes a built-in validation routine to ensure all components function correctly.

Protocol 2: Preparation of 10x Genomics V(D)J Sequencing Data

This protocol standardizes the input data structure from Cell Ranger for use with MiXCR's preset. The input must be the unfiltered contig annotations file.

  • Data Source:

    • Begin with the output directory of a 10x Genomics Cell Ranger (cellranger vdj) pipeline run. The required file is filtered_contig_annotations.csv (or for Cell Ranger 7+, the all_contig_annotations.json is also acceptable).

  • File Structure Validation:

    • Navigate to the Cell Ranger output directory. Confirm the existence of the file ./outs/filtered_contig_annotations.csv.

  • Input Path Declaration:

    • Define the absolute or relative path to this file as your PATH_TO_10X_FILTERED_CONTIG_ANNOTATIONS. This path will be used as the primary input argument for the MiXCR analyze command.

Data Presentation

Table 1: Essential Software Dependencies and Specifications

Component Minimum Version Recommended Version Verification Command Purpose
Java JRE 8 11 or 17 java -version Runtime environment for MiXCR.
MiXCR 4.0 Latest Stable (e.g., 4.5.x) mixcr -v Core software for V(D)J analysis.
10x Data Cell Ranger 3.x Cell Ranger 7.x N/A Compatibility with 10x-sc-xcr-vdj preset.
Operating System N/A Linux/macOS N/A Optimal for pipeline execution.

Table 2: Key Input Files for analyze 10x-sc-xcr-vdj Preset

File Name Typical Location Mandatory Description
filtered_contig_annotations.csv cellranger_vdj_out/outs/ Yes Contains assembled contigs, barcodes, chain info, and consensus sequences.
all_contig_annotations.json cellranger_vdj_out/outs/ No (Alternative) JSON format containing all contigs (filtered + unfiltered). Can be used in newer workflows.
Raw FASTQ Files User-defined No (for this step) Required only for analysis starting from raw sequencing reads, not for this preset.

Mandatory Visualization

Diagram: Workflow from 10x Data to Thesis Research

Diagram: Prerequisites Enabling Thesis Preset Research

The Scientist's Toolkit

Table 3: Research Reagent Solutions for Data Preparation

Item Function in Protocol
10x Genomics ChromiumSingle Cell V(D)J Reagent Kit Generates barcoded, library-ready material from input cells for 5' V(D)J + Gene Expression or 3' V(D)J profiling.
Cell Ranger VDJ Pipeline(v7.x or later) Proprietary 10x software suite that performs demultiplexing, barcode processing, contig assembly, and initial annotation to produce the required filtered_contig_annotations.csv file.
High-Performance Computing(HPC) Cluster or Server Essential for running both Cell Ranger and subsequent high-throughput MiXCR analyses, which are computationally intensive.
MiXCR Standalone JAR File The executable Java package containing all algorithms and presets for immune repertoire analysis, including the 10x-sc-xcr-vdj command.
Organized Project Directory A clear, versioned file structure to store raw data (FASTQ), intermediate files (Cell Ranger outs/), and MiXCR output folders, ensuring reproducibility.

Within the broader thesis investigating the optimization of the MiXCR analyze 10x-sc-xcr-vdj command preset for single-cell T- and B-cell receptor repertoire analysis, understanding the full command syntax and essential parameters is critical. This protocol provides detailed application notes for researchers, scientists, and drug development professionals to execute robust, reproducible immune repertoire sequencing data analysis pipelines.

The Fullmixcr analyzeSyntax

The mixcr analyze command is a high-level wrapper that integrates multiple MiXCR subcommands into a single workflow. For the 10x-sc-xcr-vdj preset, the full syntax is as follows:

Essential Parameters and Their Functions

Below is a summary of the essential parameters for the 10x-sc-xcr-vdj preset, based on current MiXCR documentation and community best practices.

Table 1: Essential Parameters for mixcr analyze 10x-sc-xcr-vdj

Parameter Default Value Description Impact on Thesis Research
--starting-material rna Specifies library prep source (rna or dna). Critical for quantifying transcriptome vs. genome-level receptor diversity.
--chain auto Specifies chain(s) to analyze (e.g., TRA, TRB, IGH, IGL). Defines scope of single-cell paired analysis for VDJ/VJ chains.
--only-productive true Filters for productive rearrangements. Essential for focusing on functional sequences in drug target discovery.
--contig-assembly true Assembles contigs from reads. Key step for accurate CDR3 reconstruction in single-cell data.
--threads 4 Number of processing threads. Optimizes compute resource use for high-throughput dataset analysis.
--verbose false Enables detailed log output. Aids in debugging and pipeline validation.
--force-overwrite false Overwrites existing results. Ensures reproducible execution in automated workflows.
--report auto Generates a summary report file. Provides quantitative overview for quality assessment.

Table 2: Quantitative Output Metrics Generated by the Preset

Output File Key Quantitative Metrics Relevance for Thesis
<prefix>.clns Clone count, read count, UMI count per cell. Primary data for clonal abundance and diversity calculations.
<prefix>.report Total reads processed, % aligned, % assembled. Quality control for experimental batches.
<prefix>.clonotypes.tsv CDR3 nucleotide/aa sequence, V/D/J genes, UMIs. Source for tracking specific clones across samples.

Detailed Experimental Protocol

Protocol: Executing themixcr analyze 10x-sc-xcr-vdjPipeline for Single-Cell 10x Genomics Data

1. Prerequisite Software and Data

  • Software: MiXCR v4.5+ installed via package manager (e.g., apt, brew) or downloaded from the official GitHub repository.
  • Input Data: FASTQ files (R1, R2, I1) from a 10x Genomics 5' V(D)J sequencing run. Files must be named in a standard pattern (e.g., Sample_S1_L001_R1_001.fastq.gz).
  • Reference Genome: Species-specific reference (e.g., hs for Homo sapiens, mmu for Mus musculus). Downloaded automatically by MiXCR on first use.

2. Command Execution Run the following command in a terminal or submit as a job to a computing cluster.

3. Post-Analysis Validation

  • Inspect the generated Sample01_analysis.report.txt file. Confirm that the "Final clonotype count" is reasonable for your cell count and that alignment percentages are high (>80%).
  • Load the Sample01_analysis.clonotypes.tsv file into statistical software (e.g., R, Python) for downstream analysis, such as calculating clonal diversity indices (Shannon, Simpson) or visualizing V-gene usage.

Visualization of the Analysis Workflow

Workflow of the 10x-sc-xcr-vdj Command Preset

The Scientist's Toolkit: Research Reagent Solutions

Table 3: Key Reagents and Materials for 10x scVDJ-seq Experiments

Item Function in Experimental Workflow Example Product/Catalog #
Chromium Next GEM Chip K Partitions single cells with gel beads for 10x library prep. 10x Genomics, 1000127
Chromium Next GEM Single Cell 5' Kit v3 Contains enzymes, buffers, and primers for 5' gene expression and V(D)J library construction. 10x Genomics, 1000269
Chromium Single Cell V(D)J Enrichment Kit Contains primers for target amplification of T-cell or B-cell receptor regions. 10x Genomics, 1000005 (Human T) / 1000016 (Human B)
Dual Index Kit TT Set A Provides unique dual indices for sample multiplexing. 10x Genomics, 1000215
SPRIselect Reagent Kit Magnetic beads for size selection and clean-up of cDNA and final libraries. Beckman Coulter, B23318
High Sensitivity DNA Kit Used with a Bioanalyzer or TapeStation for quality control of final libraries. Agilent, 5067-4626
PhiX Control v3 Spiked into runs on Illumina sequencers for quality monitoring. Illumina, FC-110-3001

Application Notes

This document serves as an essential guide for interpreting the output files generated by the MiXCR analyze 10x-sc-xcr-vdj command preset, a critical tool in single-cell adaptive immune receptor repertoire (AIRR) sequencing analysis. The preset is specifically designed to process 10x Genomics Chromium single-cell V(D)J sequencing data, producing a suite of files that detail clonal expansion, cell-based repertoire, and assembled contigs. The accurate decoding of these outputs is fundamental for research in immunology, oncology, and therapeutic antibody discovery.

Core Output File Structure and Interpretation

The mixcr analyze 10x-sc-xcr-vdj pipeline automates several steps: alignment, contig assembly, clustering, and export. The primary outputs fall into three conceptual categories: clone-centric, cell-centric, and contig-centric reports.

1. Clones Report (*clones.tsv): This file represents the core analytical product, listing all inferred clonotypes. A clonotype is defined as a set of cells sharing functionally identical immune receptor sequences (considering V, J genes, and CDR3 amino acid sequence). Key quantitative metrics are summarized below.

2. Cells Report (*cells.tsv): This file provides a cell-by-cell view of the repertoire. Each row corresponds to a single cell barcode, with columns indicating which clonotype(s) it belongs to and the associated receptor chains detected.

3. Contigs Report (*contigs.tsv): This is a more granular file containing information for every individual assembled contig (a continuous sequence assembled from reads), before cell and clone grouping.

Table 1: Key Metrics in Clones Report (*clones.tsv)

Column Name Description Typical Range/Value
cloneId Unique identifier for the clonotype. Integer sequence
cloneCount Total number of cells assigned to this clonotype. 1 to thousands
cloneFraction Proportion of all cells represented by this clonotype. 0.0 to 1.0
targetSequences Consensus nucleotide sequence(s) for the clone. V(D)J sequence
targetQualities Phred quality scores for consensus sequences. String of quality scores
vHit, jHit, cHit Assigned V, J, and C gene alleles. IMGT gene nomenclature
nSeqCDR3, aaSeqCDR3 Nucleotide and amino acid sequence of the CDR3 region. Variable length
minQualCDR3 Minimum quality score within the CDR3 region. 0-40+

Table 2: Key Metrics in Cells Report (*cells.tsv)

Column Name Description
cellId Single-cell barcode (e.g., from 10x).
cloneIds List of cloneIds the cell is assigned to (for dual receptors).
clonalSequenceA, clonalSequenceB Paired receptor sequences (e.g., TRA/TRB, IGH/IGL).

Table 3: Key Metrics in Contigs Report (*contigs.tsv)

Column Name Description
contigName Unique name for the assembled contig.
cellId Source cell barcode.
chain Chain type (e.g., TRA, TRB, IGH, IGL, IGK).
reads Number of reads supporting this contig.
vHit, jHit, cHit Assigned genes.
nSeqCDR3, aaSeqCDR3 CDR3 sequence.

Experimental Protocols

Protocol 1: Executing the MiXCR 10x-sc-xcr-vdj Analysis Pipeline

Objective: To process raw 10x Genomics single-cell V(D)J sequencing data (FASTQ files) into clonal, cellular, and contig reports.

Materials: See "The Scientist's Toolkit" below.

Methodology:

  • Data Preparation: Ensure paired-end FASTQ files are organized. You will need sample_S1_L001_R1_001.fastq.gz (cDNA reads) and sample_S1_L001_R2_001.fastq.gz (cell+UMI barcode reads).
  • Command Execution: Run the preset command in a terminal with adequate computational resources.

    Parameters: --species (e.g., hs for human, mm for mouse); --starting-material (rna or dna); --receptor-type (tcr or ig); --only-productive filters for in-frame sequences without stop codons.
  • Output Retrieval: The command generates a final sample.clones.tsv file, along with intermediate files. The sample.clones.tsv, sample.cells.tsv, and sample.contigs.tsv are the primary reports for downstream analysis.

Protocol 2: Validation and Quality Control of Clonal Assignments

Objective: To verify the accuracy of clonotype calling and cell assignment using independent methods.

Methodology:

  • Spike-in Control Analysis: Use synthetic TCR/BCR sequences (e.g., from spike-in cells with known receptors) processed alongside the sample. Map the output clones back to the known sequences to calculate the false-negative rate.
  • UMI Saturation Curve: From the contigs.tsv file, plot the number of unique clonotypes detected against the number of confidently mapped reads (or UMIs). The plateau indicates sequencing saturation.
  • Cross-Validation with Gene Expression: Integrate the cells.tsv file with 10x Gene Expression data (from Cell Ranger). Correlate clonal expansion metrics with transcriptional clusters (e.g., effector T cell markers) to biologically validate clonal assignments.

Diagrams

Workflow: From Raw FASTQ to MiXCR Reports

Relationship Between Contig, Cell, and Clone Files

The Scientist's Toolkit

Table 4: Essential Research Reagent Solutions for 10x scVDJ-seq with MiXCR

Item Function in Experiment
10x Genomics Chromium Single Cell V(D)J Reagent Kits Provides all necessary gel beads, buffers, and enzymes for partitioning cells, RT, and library construction for TCR or BCR.
MiXCR Software Suite (v4.0+) The core analytical engine that executes the analyze 10x-sc-xcr-vdj preset and generates reports.
High-Quality RNA/DNA from Lymphocytes Starting material. Integrity (RIN > 8) is critical for full-length V(D)J transcript capture.
Spike-in Control Cells with Known Receptors (e.g., cell lines with defined TCR). Used for validating sensitivity and specificity of the wet-lab and computational pipeline.
Cell Ranger V(D)J (Optional) 10x's proprietary software. Can be used for initial FASTQ generation and as a comparative benchmark for MiXCR results.
R/Bioconductor (e.g., immunarch, scRepertoire) Downstream analysis packages for advanced statistical testing, diversity estimation, and visualization of MiXCR output tables.
High-Performance Computing (HPC) Cluster Essential for processing multiple samples, as the MiXCR alignment and assembly steps are computationally intensive.

Application Notes Integrating clonotype data from MiXCR's analyze 10x-sc-xcr-vdj preset with single-cell RNA-seq (scRNA-seq) expression data is a critical step for holistic immune repertoire profiling within the broader thesis on MiXCR preset benchmarking. This integration enables the correlation of clonal expansion, diversity, and antigen specificity with cellular transcriptomes, phenotypes, and states. The primary tools for this are the Seurat package for single-cell analysis and specialized libraries like scRepertoire or immunarch for repertoire analysis. Key quantitative outputs from MiXCR that feed into these pipelines are summarized below.

Table 1: Core MiXCR Output Files for Downstream Integration

File Name Description Key Quantitative Fields
clonotypes.csv High-level clonotype summary. clonotypeId, count (clonotype frequency), fraction
clones.csv Detailed per-cell clone information. cloneId, clonotypeId, cellId (cell barcode), readCount, chain sequences (aaSeqCDR3, nSeqCDR3)
contigs.csv Processed contig sequences for each cell. cellId, chain (TRA, TRB, IGH, IGL, IGK), vGene, jGene, cGene, cdr3aa, cdr3nt, reads

The integration process typically involves merging the clonotype information from clones.csv or clonotypes.csv with the cell metadata in a Seurat object using the cell barcode (cellId) as the key. Subsequent analysis with scRepertoire allows for the calculation of repertoire metrics (clonality, diversity, overlap) and their visualization per cluster or sample.

Protocol: Importing MiXCR Results into Seurat and scRepertoire

Materials & Reagents Research Reagent Solutions:

  • MiXCR Processed Data: The clones.csv and clonotypes.csv files from the mixcr analyze 10x-sc-xcr-vdj pipeline.
  • Cell Ranger Output: The filtered_feature_bc_matrix directory containing scRNA-seq count matrices and barcodes.
  • R Environment (v4.0+): With the following packages installed: Seurat, scRepertoire, tidyverse/dplyr, ggplot2.
  • Python Environment (Optional, v3.8+): With scanpy, pandas, and anndata for alternative workflows.

Procedure Part A: Data Preparation and Seurat Object Creation

  • Load Expression Data: In R, create a Seurat object from the 10x Genomics Cell Ranger output.

  • Standard Preprocessing: Perform standard QC, normalization, and clustering.

Part B: Clonotype Data Import and Integration

  • Load and Format MiXCR Data: Read the MiXCR clones.csv file and create a clean cell barcode column to match the Seurat object barcodes.

  • Add Clonotype Data to Seurat Metadata: Merge the clonotype information into the Seurat object's metadata.

  • Integrate with scRepertoire: Use the combineExpression function to add the clonotype data in a format optimized for scRepertoire's analysis suite.

Part C: Combined Analysis and Visualization

  • Visualize Clonal Expansion: Overlay clonal frequency on UMAP clusters.

  • Calculate Repertoire Metrics: Generate diversity and clonality plots per cluster.

  • Investigate Clonal Overlap: Analyze shared clonotypes across conditions or clusters.

Visualization: Workflow Diagram

Solving Common Pitfalls: Troubleshooting and Optimizing Your 10x-sc-xcr-vdj Analysis

Within the broader thesis investigating MiXCR's analyze 10x-sc-xcr-vdj command preset for single-cell V(D)J repertoire analysis, a critical challenge is the occurrence of low cell or clonotype recovery. This directly impacts statistical power, clonal diversity assessment, and the reliability of downstream analyses. These Application Notes detail systematic quality control (QC) checkpoints to diagnose and remediate such issues, ensuring robust data for researchers and drug development professionals.

Key Quality Control Metrics & Benchmarks

The following tables summarize critical QC thresholds derived from current 10x Genomics Chromium Single Cell Immune Profiling best practices and recent literature.

Table 1: Pre-sequencing QC Checkpoints for Cell Viability and Input

Metric Target Range Low Recovery Risk Indicator Recommended Assay
Cell Viability >90% <80% Fluorescent viability dye (e.g., PI, 7-AAD)
Cell Concentration 700-1,200 cells/µL <500 cells/µL Automated cell counter
Input Cell Number 10,000-20,000 cells <5,000 cells Manual count with hemocytometer
cDNA Yield (from Gene Expression) >1.0 ng/µL <0.5 ng/µL Fluorometric assay (e.g., Qubit)
cDNA Fragment Size ~1,000 bp broad peak Smear <500 bp Capillary electrophoresis (e.g., Bioanalyzer)

Table 2: Post-sequencing & MiXCR Processing QC Metrics

Metric Healthy Profile Low Recovery Alert Calculation/Preset
Number of Cells with VDJ Data ~65-85% of GEX cells <50% of GEX cells MiXCR report cellsWithVdj
Median Reads per Cell >5,000 <1,000 MiXCR --report output
Clonotypes per Cell 1.0 - 1.3 (mostly 1) >1.5 (multiple chains) From clonotypes.csv
Productive Contig Fraction >70% <50% MiXCR: productive + non-productive
Cells with Productive V-J Spanning Pair >60% of loaded cells <30% of loaded cells MiXCR --chain-type pairing logic

Detailed Experimental Protocols

Protocol 1: Pre-Library Preparation Cell QC and Viability Staining

Objective: Accurately assess live cell concentration and viability prior to loading on the Chromium chip. Materials: See "Scientist's Toolkit" below. Procedure:

  • Cell Wash: Pellet the single-cell suspension (300 x g, 5 min). Aspirate supernatant and resuspend in 1x PBS + 0.04% BSA.
  • Staining: Add fluorescent viability dye (e.g., 1 µL of 1 mg/mL PI per 1 mL cells). Incubate for 5 minutes on ice, protected from light.
  • Analysis: Load onto an automated cell counter with fluorescence capability.
  • Calculation: Count only PI-negative (viable), morphologically intact cells. Adjust concentration to target 1,000 cells/µL using PBS + 0.04% BSA.
  • Threshold: Proceed only if viability >85% and total viable cells >15,000.

Protocol 2: Diagnosing Recovery Issues via MiXCR Report Analysis

Objective: Use MiXCR's built-in reporting to pinpoint the stage of recovery failure. Methodology:

  • Run MiXCR with --report flag: Execute the mixcr analyze command with the 10x-sc-xcr-vdj preset and the --report argument.

  • Extract Key Metrics: Parse the report.txt file for the following sections:
    • Total sequencing reads: Low yield suggests sequencing depth issue.
    • Successfully aligned reads: Low alignment suggests poor library quality or species mismatch.
    • Cells with VDJ data: The primary recovery metric.
    • Reads used for assembly per cell (median): Indicates read coverage sufficiency.
  • Cross-reference with Web Summary: Compare MiXCR's cellsWithVdj to the estimated_number_of_cells from 10x's web_summary.html. A large discrepancy suggests a chemistry or capture issue.

Protocol 3: Contig-Level QC and Doublet Detection

Objective: Filter noisy data and identify potential multiplets causing inflated clonotype counts. Procedure:

  • Generate Contig Annotations: Ensure MiXCR export includes productive, cdr3, and chain info for each contig.
  • Filter Non-Productive Contigs: Remove contigs where productive is FALSE for initial clonotyping.
  • Apply Chain Pairing Logic: For T-cells, a valid cell should have exactly one productive full-length TRA or TRD contig and exactly one productive full-length TRB or TRG contig.
  • Flag Multiplets: Cells with >2 productive contigs for the same chain type (e.g., two full-length TRB) are potential multiplets. Consider removing them or using a dedicated doublet detection tool (e.g., Scrublet).
  • Recalculate Recovery: Compute the percentage of cells passing these filters relative to the expected cell count.

The Scientist's Toolkit: Research Reagent Solutions

Item Function Example Product/Catalog #
Fluorescent Viability Dye Distinguishes live/dead cells for accurate counting Propidium Iodide (PI) (P3566, Thermo Fisher)
Automated Cell Counter with Fluorescence Provides accurate, reproducible viable cell counts Countess 3 FL (Thermo Fisher)
High-Sensitivity DNA/RNA Assay Kit Quantifies low-yield cDNA libraries pre-enrichment Qubit dsDNA HS Assay Kit (Q32851, Thermo Fisher)
Capillary Electrophoresis System Assesses cDNA and final library fragment size distribution Agilent 2100 Bioanalyzer with High Sensitivity DNA Kit
Single-Cell 5' V(D)J + Feature Barcode Kit Enables coupled gene expression and V(D)J profiling 10x Genomics Chromium Next GEM Single Cell 5' v3 (1000269)
MiXCR Software End-to-end analysis pipeline for immune repertoire data MiXCR v4.6.0 (https://mixcr.com)

Diagnostic and Remediation Workflow Diagrams

Title: Root Cause Analysis for Low Recovery

Title: MiXCR Processing QC Pipeline

Within the context of a broader thesis on MiXCR analyze 10x-sc-xcr-vdj command preset research, efficient management of computational resources is critical. This application note details protocols for optimizing memory, CPU, and runtime during high-throughput immune repertoire analysis of single-cell V(D)J data from 10x Genomics platforms.

Key Computational Challenges & Quantitative Benchmarks

The mixcr analyze 10x-sc-xcr-vdj pipeline involves alignment, clustering, and assembly steps that are computationally intensive. Performance varies based on input size and preset parameters.

Table 1: Computational Resource Utilization by Common Presets

Preset Name Estimated Runtime (per 10k cells) Peak Memory (GB) CPU Threads Utilized Primary Use Case
default 2.5 hours 32 8 Standard full-length assembly
qc 45 minutes 16 4 Rapid quality control
fast 1.5 hours 24 12 Speed-optimized for large cohorts
high-accuracy 4 hours 48 16 High-sensitivity for low-expression clones
umi 3 hours 28 8 UMI-based error correction and consensus

Experimental Protocols for Benchmarking

Protocol 1: Baseline Performance Profiling

Objective: To establish baseline computational metrics for the analyze 10x-sc-xcr-vdj command.

  • Sample Preparation: Use a publicly available 10x Genomics single-cell V(D)J dataset (e.g., 10k PBMCs).
  • Environment Setup: Execute MiXCR v4.6.0 on a Linux server with 64 cores and 256 GB RAM. Limit Docker/Singularity container memory.
  • Command Execution: Run mixcr analyze 10x-sc-xcr-vdj --species human --starting-material rna --contig-assembly --threads 8 sample_R1.fastq.gz sample_R2.fastq.gz output.
  • Monitoring: Use time -v for runtime and peak memory, and htop for CPU core utilization.
  • Data Collection: Record real-time, user-time, system-time, and maximum resident set size.

Protocol 2: Memory Optimization via Targeted Downsampling

Objective: To reduce memory footprint without significant data loss.

  • Subsampling: Use seqtk sample to create subsets (1000, 5000, 10000 cells) from original FASTQ files.
  • Parallel Processing: Execute the fast preset on each subset with --threads 4. Use --force-overwrite flag.
  • Metric Comparison: Compare clonotype count and diversity metrics (Shannon index) between subsets and full dataset.
  • Determination: Identify the minimum input threshold that yields a representative repertoire (<5% divergence in top 100 clonotypes).

Protocol 3: CPU Parallelization Efficiency Test

Objective: To identify optimal thread count for diminishing returns.

  • Thread Sweep: Run the same dataset with the default preset, varying --threads parameter (2, 4, 8, 16, 32).
  • Performance Recording: Measure wall-clock time and CPU time for each run.
  • Efficiency Calculation: Compute parallelization efficiency as (T1 / (N * TN)) where T1 is runtime with 1 thread (estimated), N is thread count, TN is runtime with N threads.
  • Analysis: Plot threads vs. runtime; identify point where adding threads yields <10% improvement.

Optimization Workflow Diagram

Diagram Title: MiXCR Resource Optimization Decision Workflow

The Scientist's Toolkit: Research Reagent Solutions

Table 2: Essential Computational Tools & Resources

Item Function & Relevance
MiXCR Software (v4.6+) Core analysis suite for single-cell V(D)J sequencing. Enables preset-based optimization.
10x Genomics Cell Ranger V(D)J Optional upstream alignment tool. Can be used for initial cell calling to filter input.
GNU time Command (/usr/bin/time -v) Critical for measuring peak memory usage and CPU time of MiXCR runs.
Seqtk Lightweight tool for FASTQ subsampling to test memory/runtime trade-offs.
Slurm/Grid Engine Job scheduler for cluster deployment, enabling resource limit flags (--mem, --cpus-per-task).
Docker/Singularity Containerization for reproducible environment and controlled resource allocation.
MultiQC Aggregates MiXCR QC reports across multiple runs to identify outlier samples consuming disproportionate resources.
High-Memory Compute Node Access to nodes with >512GB RAM is essential for processing large cohorts (>100k cells) with the high-accuracy preset.

Advanced Protocol: Iterative Preset Tuning for Large Cohorts

Objective: To process a cohort of 100+ samples within a fixed resource budget.

  • Pilot Phase: Select 3 representative samples (high, medium, low cell count). Run each with qc, fast, and default presets.
  • Resource Profiling: Populate a table with runtime and memory for each sample-preset combination.
  • Modeling: Fit a linear model: Memory = α * (Number of Cells) + β * (Preset Constant).
  • Batch Scheduling: Using the model, assign presets to each sample in the cohort so that total memory required per parallel batch does not exceed cluster queue limits (e.g., 4 TB). Prioritize high-accuracy preset only for low-quality or key samples.
  • Validation: Compare final clonotype tables from fast and default presets for pilot samples. If concordance (F1 score for top 100 clones) >0.95, approve use of fast for remaining high-quality samples.

Signaling Pathway of MiXCR Parallelization

Diagram Title: MiXCR Pipeline Stages and Resource Binding

For thesis research utilizing the mixcr analyze 10x-sc-xcr-vdj command:

  • Profile First: Always run a small subset with time -v to establish baseline resource needs.
  • Match Preset to Goal: Use qc for exploratory analysis, fast for large cohorts, and high-accuracy for key validation samples.
  • Control Parallelization: Set --threads to 8-12 for optimal throughput; increasing beyond this often yields diminishing returns.
  • Monitor Memory: The most memory-intensive step is clustering. If memory limits are hit, consider subsampling or using the --force-overwrite flag to prevent intermediate file accumulation.

Resolving Ambiguous Assignments and Doublet Challenges in Paired Chain Data.

Within the broader thesis research on the MiXCR analyze 10x-sc-xcr-vdj command preset, a critical bottleneck emerges during the joint analysis of paired immune receptor chains (e.g., TCRα/β or IgGκ/λ) from single-cell sequencing. Ambiguities arise when: a) multiple possible productive chain pairs exist for a single cell barcode due to sequencing noise or biological multiplicity, or b) a barcode originates from a cellular doublet, merging receptors from distinct cells. This document provides detailed Application Notes and Protocols to resolve these challenges, ensuring accurate clonotype assignment and downstream repertoire analysis.

Application Notes: Core Challenges and Solutions

The mixcr analyze 10x-sc-xcr-vdj pipeline generates single-cell immune repertoire data. Post-processing must disambiguate chain pairing.

Table 1: Sources of Ambiguity in Paired Chain Data

Challenge Type Primary Cause Impact on Data Proposed Resolution Strategy
Ambiguous Pairing 1. Missing chain (dropout) in one locus.2. Multiple productive chains per locus (e.g., biallelic expression). A single barcode yields >1 valid chain pair combination (e.g., 1α with 2β). Probabilistic scoring based on UMI counts, constant gene assignment, and transcriptional overlap.
Technical Doublet Co-encapsulation of two cells in a single droplet/GEM. A barcode contains >2 productive chains per locus (e.g., 3α, 2β) from distinct clonotypes. Multiplet classification using cell hashing, SNP information, or expression profile disparity.
Biological Multiplicity Biclonal cell or doublet in vivo. Genuine but rare biological signal confounding clonotype clustering. Strict validation via VDJ gene alignment quality and independent library preparation.

Table 2: Quantitative Metrics for Disambiguation Scoring

Metric Description Weighting Rationale
UMI Ratio Balance Ratio of UMIs supporting each chain in a candidate pair. Pairs with balanced UMIs are favored over highly skewed ratios (may indicate dropout).
Constant Region Match Consistency of constant gene calls (e.g., TRAC with TRBC1/2). Pairs with biologically plausible constant regions are strongly favored.
Gene Expression Correlation Correlation of immune cell gene expression profile with the candidate pair's clonotype. Pairs whose clonotype matches the cell's phenotypic cluster (e.g., CD8+ T cell) are favored.
VDJ Alignment Score Phred-scaled quality of V, D, J gene alignments for each chain. Higher confidence alignments reduce false productive calls.

Experimental Protocols

Protocol 3.1: Disambiguation Workflow for MiXCR Output

Objective: To resolve ambiguous pairings and filter doublets from the clonotypes and cells tables generated by mixcr analyze 10x-sc-xcr-vdj. Input: *_clonotypes.txt and *_cells.txt from MiXCR; optional: cellranger-derived gene expression matrix. Software: R (tidyverse, scRepertoire), Python (pandas, scipy), or dedicated tool (VDJ Puzzle). Procedure:

  • Load Data: Import MiXCR clonotype and cell tables. Link barcodes to clonotype IDs.
  • Identify Multi-Chain Barcodes: Flag all barcodes with >2 productive chains for any single locus (α, β, γ, δ, IgH, IgL).
  • Apply Doublet Filter: For flagged barcodes from Step 2:
    • If cell hashing or SNP data exists: Remove barcodes with >1 hashtag or >1 major SNP genotype.
    • If only VDJ data exists: Apply a hard filter—discard all barcodes with >2 chains per locus. This conservatively removes potential doublets but may lose some biallelic cells.
  • Resolve Ambiguous Pairings: For remaining barcodes with exactly 2 chains at one locus and 1 chain at the paired locus (e.g., 1α, 2β):
    • Calculate a pairwise compatibility score for each possible combination (α1β1, α1β2).
    • Score = (w1 * norm(UMI ratio)) + (w2 * constant region match) + (w3 * alignment confidence). (Default weights: w1=0.4, w2=0.4, w3=0.2).
    • Select the pair with the highest score. If scores are within 5%, mark as "uncertain" for manual review.
  • Output: Generate a curated clonotype-by-barcode matrix, with doublets removed and ambiguous pairings resolved.

Protocol 3.2: Validation by Independent Library Re-Amplification

Objective: Experimentally validate computationally resolved ambiguous pairs. Input: Sorted single cells based on computational predictions. Materials: Nested VDJ-specific PCR primers, cDNA from sorted cells, next-generation sequencer. Procedure:

  • Cell Sorting: Using FACS, sort single cells into 96-well plates based on barcode-derived predictions: wells containing cells called as "true pair," "ambiguous pair," and "doublet."
  • Reverse Transcription & PCR: Perform targeted RT-PCR in each well using locus-specific primers (e.g., TRAC, TRBC) to generate amplicons spanning the VJ or VDJ junction.
  • Nested PCR & Sequencing: Perform a second, nested PCR to add sequencing adapters and sample indices. Pool and sequence amplicons.
  • Analysis: Align sequences to the reference. Confirm that the computationally predicted pair is the sole sequence recovered in "true pair" wells, and that "doublet" wells yield >2 distinct sequences.

Visualizations

Title: Workflow for Resolving Chain Pairing Ambiguity

The Scientist's Toolkit

Table 3: Research Reagent Solutions for Validation

Item Function / Application
Cell Hashing Antibodies (TotalSeq-A/B/C) Labels cells from different samples with unique barcoded antibodies, enabling post-hoc doublet detection via hashtag signal multiplexing.
Single-Cell 5' V(D)J + Feature Barcoding Kit (10x Genomics) Provides an integrated workflow for capturing paired chain VDJ transcripts alongside protein expression (Cell Surface Protein) or sample hashing.
Nested V(D)J PCR Primers (TRAC/TRBC, IGH/IGK/L) For targeted re-amplification of receptor sequences from sorted single cells to validate computational pairing calls.
BD Rhapsody Immune Repertoire Assay An alternative bead-based platform for paired-chain analysis, offering complementary data for method cross-validation.
VDJ Puzzle Cell Specialized software package designed explicitly to solve combinatorial pairing problems in single-cell immune repertoire data.

Application Notes for MiXCRanalyze 10x-sc-xcr-vdjin Single-Cell Immune Repertoire Research

Within the broader thesis on optimizing MiXCR presets for single-cell V(D)J analysis, strategic flag adjustment is critical for data fidelity. The analyze 10x-sc-xcr-vdj command's default preset provides a robust starting point, but specific experimental contexts demand parameter refinement to accurately resolve clonality, isotype, and antigen specificity.

Flag Function and Tuning Rationale

--species (-s)

  • Default & Primary Use: hs (Homo sapiens). Used for genome alignment and V/D/J/C gene assignment.
  • When to Adjust: For murine (mmu), non-human primate (macacaMulatta), or other model organism studies. Incorrect species setting causes alignment failure.
  • Quantitative Impact: Using the wrong species can reduce productive alignment rates by >95%.

--tag

  • Default & Primary Use: --tag cell, --tag sample, --tag patient. Attaches metadata to sequences for downstream multi-sample analysis.
  • When to Adjust: For complex multi-omics integrations (e.g., CITE-seq) or when tracking longitudinal samples. Add custom tags (e.g., --tag timePoint, --tag stimulation) to preserve experimental variables.
  • Quantitative Impact: Proper tagging enables accurate merging of datasets from >1000 samples without sample confusion.

--assemble

  • Default & Primary Use: --assemble default. Applies the default assembly algorithm (partial alignments, clustering).
  • When to Adjust: For low-quality RNA, high levels of somatic hypermutation (SHM), or novel allele discovery. Use --assemble assemblyWithMutations for detailed SHM analysis or --assemble reportR1 for single-read analysis on degraded samples.
  • Quantitative Impact: On hypermutated B-cell repertoires (e.g., post-vaccination), assemblyWithMutations can increase clonotype recovery by 15-25%.

Table 1: Impact of Flag Adjustment on Key Output Metrics

Flag Default Value Adjusted Value Typical Input Alignment Rate Change Clonotype Count Change Notes
--species hs mmu 10k Mouse B cells +92% (from <5%) +880% Critical for non-human data.
--tag cell, sample Add --tag treatment 4 samples, 2 conditions 0% 0% Enables per-condition differential analysis.
--assemble default assemblyWithMutations HIV bnAb lineage (High SHM) -5% +22% Trades slight sensitivity for mutation detail.
--assemble default reportR1 FFPE-derived TCR-seq (Low quality) +18% +12% Better for truncated reads; may increase noise.

Experimental Protocols

Protocol 1: Validating--speciesfor Cross-Species Study

Objective: Correctly align single-cell V(D)J data from a humanized mouse model. Materials: FASTQ files from 10x Genomics (VDJ libraries) for human T cells expanded in a murine host. Method:

  • Run 1 (Default): Execute mixcr analyze 10x-sc-xcr-vdj --species hs --tag cell sample input_dir/ output_hs/
  • Run 2 (Adjusted): Execute mixcr analyze 10x-sc-xcr-vdj --species mmu,hs --tag cell sample input_dir/ output_mixed/
  • Analysis: Compare output_hs/ and output_mixed/ alignment reports. The mixed species argument allows alignment first to murine, then human germlines, filtering cross-species contamination.

Protocol 2: Utilizing Custom--tagfor Longitudinal Tracking

Objective: Analyze paired pre- and post-treatment samples from 5 patients. Method:

  • Structured Input: Organize FASTQs in directories: PatientA_pre/, PatientA_post/, etc.
  • Command with Tags: Execute a batch script running: mixcr analyze 10x-sc-xcr-vdj --species hs --tag cell --tag patient=P01 --tag timepoint=pre ...
  • Downstream Integration: Use the tags in MiXCR export or mixcr postanalysis to group clones by patient and timepoint for overlap and dynamics analysis.

Protocol 3: Tuning--assemblefor High-Mutation B-Cell Repertoires

Objective: Maximize recovery of hypermutated B-cell clonotypes from a vaccine response study. Method:

  • Baseline: Run with default assembly.
  • Experimental: Run with --assemble assemblyWithMutations.
  • Comparison: Use mixcr exportClones on both outputs. Compare the average mutations per clone and total high-confidence clonotypes. The adjusted flag will report detailed mutation profiles in the output clones table.

Diagrams

Title: MiXCR 10x-sc-xcr-vdj Parameter Tuning Decision Tree

The Scientist's Toolkit: Key Research Reagent Solutions

Table 2: Essential Materials for Advanced MiXCR scVDJ Analysis

Item Function in Experiment
10x Genomics Chromium Next GEM Single Cell 5' V(D)J Reagent Kits Provides primers and beads for generating barcoded single-cell V(D)J libraries. Essential for input data.
Species-Specific CRISPR/Cas9-Generated Immune Model RNA Positive control for validating --species flag adjustments in non-human studies.
Spike-in RNA (e.g., from cell line with known receptor) Control for assessing sensitivity of different --assemble modes, especially in low-input samples.
MiXCR Native Report Files (alignmentReport.txt, assembleReport.txt) Critical for quantitative comparison of alignment and assembly efficiency between runs.
Downstream Analysis Suite (e.g., R immunarch, Seurat) Tools for leveraging custom --tag metadata in differential abundance and clonal tracking analyses.
High-Performance Computing (HPC) Cluster with ≥32GB RAM/node Required for processing large, multi-sample datasets generated with complex tagging strategies.

Benchmarking Accuracy: Validating Results and Comparing with Alternative Tools (Cell Ranger VDJ)

1. Introduction Within a broader thesis investigating the performance of the MiXCR analyze 10x-sc-xcr-vdj command preset, robust validation of clonotype calling is paramount. This protocol details the key metrics and experimental workflows for assessing pipeline robustness, ensuring reliability for downstream research in immunology and therapeutic drug development.

2. Key Validation Metrics & Quantitative Benchmarks Clonotype calling robustness is assessed through multiple quantitative dimensions. The following table summarizes primary metrics, their calculation, and interpretation.

Table 1: Core Metrics for Clonotype Calling Validation

Metric Category Specific Metric Calculation / Definition Target Benchmark (Typical) Interpretation
Clonotype Diversity Shannon Entropy Index H' = -Σ(pᵢ * ln(pᵢ)); pᵢ=clonotype frequency 5-10 (sample dependent) Higher value indicates greater repertoire diversity.
Simpson's Clonality Index D = Σ(pᵢ²); Clonality = 1 - D 0.01-0.5 (context dependent) Values closer to 1 indicate a more oligoclonal repertoire.
Pipeline Consistency Intra-sample Replicate Concordance (Jaccard Index) J(A,B) = |A ∩ B| / |A ∪ B| for top N clonotypes >0.85 for technical replicates Measures reproducibility of clonotype detection.
Inter-pipeline Concordance (F1 Score) F1 = 2 * (Precision*Recall)/(Precision+Recall) vs. ground truth or orthogonal method >0.90 Balances precision and recall against a reference.
Error & Sensitivity PCR/Sequencing Error Rate Estimation % of nucleotide reads in a clonotype below consensus <0.5% per base High rates can lead to inflated clonotype counts.
Singlet Detection Rate (Number of confident single-cell barcodes) / (Total barcodes) >65% for 10x data Critical for single-cell resolution; low rates indicate cell multiplet issues.
Sequence Quality Mean Reads per Cell Total aligned reads / Number of cells >5,000 reads/cell for VDJ Low coverage reduces clonotype detection sensitivity.
Contig Assembly Rate (Cells with ≥1 VDJ contig) / (Total cells) >50% Indifies successful V(D)J reconstruction per cell.

3. Experimental Protocols for Metric Validation

Protocol 3.1: Intra-Replicate Concordance Testing Objective: To assess the technical reproducibility of the MiXCR analyze 10x-sc-xcr-vdj preset. Materials: Same cell aliquot split across multiple 10x Chromium lanes. Procedure:

  • Parallel Processing: Process each technical replicate through the identical MiXCR analyze 10x-sc-xcr-vdj pipeline (e.g., mixcr analyze 10x-sc-xcr-vdj --starting-material rna --contig-assembly ... sample_rep1 sample_rep2).
  • Clonotype List Extraction: For each replicate, extract the top 1000 ranked (by read count) nucleotide clonotype sequences.
  • Jaccard Index Calculation: Compute the Jaccard Index for the top N (e.g., 100, 500, 1000) clonotypes between replicates. A value >0.85 indicates high reproducibility.
  • Visualization: Plot a scatterplot of clonotype frequencies (log-scale) between replicates.

Protocol 3.2: Inter-Pipeline Benchmarking Objective: To validate clonotype calls against an orthogonal method or ground truth dataset. Materials: Public benchmark dataset (e.g., from cellranger vdj, immcantation) or in-house data validated by Sanger sequencing of sorted clones. Procedure:

  • Reference Generation: Process the raw FASTQ files through a reference pipeline (e.g., Cell Ranger VDJ) to generate a "ground truth" clonotype list.
  • Test Pipeline Execution: Process the same FASTQ files using the MiXCR analyze 10x-sc-xcr-vdj preset with optimized parameters.
  • Clonotype Matching: Match clonotypes between pipelines based on identical CDR3 nucleotide sequences and V/J gene assignments. Allow for small, defined error tolerances.
  • Precision & Recall Calculation: Calculate: Precision = TP / (TP + FP); Recall = TP / (TP + FN). Where TP=clonotypes in both, FP=clonotypes only in MiXCR, FN=clonotypes only in reference.
  • F1 Score Derivation: Compute F1 Score = 2 * (Precision * Recall) / (Precision + Recall).

4. Visualization of Workflows and Relationships

Diagram Title: Clonotype Validation Workflow

Diagram Title: Validation Metrics Relationships

5. The Scientist's Toolkit: Research Reagent Solutions

Table 2: Essential Materials for Clonotype Validation Experiments

Item / Reagent Function in Validation Example Product / Specification
10x Chromium Next GEM Chip K Generates single-cell gel beads-in-emulsion (GEMs) for partitioning individual cells. Essential for creating technical replicates. 10x Genomics, Chip K (PN-1000286)
Chromium Next GEM Single Cell 5' v3 Kit Provides reagents for GEM-RT, cleanup, and library construction for 5' gene expression and V(D)J libraries. 10x Genomics (PN-1000265)
Dual Index Kit TT Set A Provides unique dual indexes for multiplexed sequencing of multiple samples/Replicates, allowing pooled sequencing. 10x Genomics (PN-1000215)
SPRIselect Reagent Kit For size selection and clean-up of cDNA and final libraries. Critical for removing primer dimer and optimizing library size distribution. Beckman Coulter (B23318)
High-Fidelity PCR Mix Used during library amplification steps to minimize PCR errors that could artificially inflate clonotype diversity. Kapa HiFi HotStart ReadyMix (Roche)
High-Sensitivity DNA Assay Kit For accurate quantification of final V(D)J libraries prior to sequencing. Ensures proper loading for balanced coverage. Agilent Bioanalyzer / Fragment Analyzer kits
PhiX Control v3 Spiked into sequencing runs for error rate estimation and calibration, directly informing the "Error Rate" validation metric. Illumina (FC-110-3001)
Public Benchmark Datasets Provide ground truth for inter-pipeline validation (F1 Score calculation). e.g., 10x Genomics PBMC dataset, ImmBench data from Immcantation portal

Within a broader thesis on the optimization and validation of the MiXCR analyze 10x-sc-xcr-vdj command preset, this application note provides a rigorous, data-driven comparison between the MiXCR pipeline and the proprietary 10x Genomics Cell Ranger VDJ pipeline. The focus is on performance metrics, analytical flexibility, and practical protocols for researchers in immunology and drug development.

Table 1: Pipeline Performance Comparison on Public 10x Genomics V(D)J Datasets

Metric 10x Cell Ranger VDJ (v8.0) MiXCR (v4.6) 10x-sc-xcr-vdj Notes
Clonotype Recall (%) 100 (Reference) 98.5 ± 0.7 Based on high-confidence, productive clonotypes.
Clonotype Precision (%) 95.2 ± 1.1 97.8 ± 0.9 MiXCR shows superior false-positive filtering.
Cells With Paired Chains (%) 65.3 68.1 MiXCR's assembly can rescue more complete pairs.
Median Reads Per Cell 5,120 5,120 Input is identical.
Estimated Runtime (CPU-hr) 22.5 18.1 MiXCR demonstrates faster processing on same hardware.
Memory Peak (GB) 32 28 Lower memory footprint for MiXCR.
Species Support Human, Mouse Human, Mouse, Zebrafish, etc. MiXCR supports a wider range of reference genomes.

Table 2: Advanced Metric Comparison

Metric Cell Ranger VDJ MiXCR 10x-sc-xcr-vdj Advantage
Hypermutation Analysis Limited Full IG/TR gene profiling Critical for B-cell studies.
Custom Reference Ease Complex Straightforward MiXCR accepts simple FASTA.
Cross-Sample Analysis Requires aggregation step Native support Streamlined repertoire merging.
Output Formats Proprietary, JSON, CSV Proprietary, JSON, CSV, VDJS, MITCR MiXCR offers greater interoperability.

Experimental Protocols

Protocol 1: Benchmarking Clonotype Concordance

  • Data Acquisition: Download publicly available 10x V(D)J datasets (e.g., from 10x Genomics website, SRA) for both human PBMCs and mouse spleen.
  • Pipeline Execution:
    • Cell Ranger: Run cellranger vdj with default parameters using the provided reference (refdata-cellranger-vdj-GRCm38-alts-ensembl-7.1.0).
    • MiXCR: Execute mixcr analyze 10x-sc-xcr-vdj --species hs/mm --starting-material rna --receptor-type BCR/TCR [sample_id] [fastq_path] [output_dir].
  • Data Normalization: Filter both outputs to productive, high-confidence clonotypes (with CDR3 sequence). Normalize clonotype identifiers by amino acid CDR3 sequence and associated V/J genes.
  • Comparison: Calculate recall and precision using Cell Ranger as the de facto baseline. Use set intersection/union operations on normalized clonotype IDs.

Protocol 2: Assessing Pairing Efficiency

  • Run Pipelines: Follow Step 2 from Protocol 1.
  • Cell Ranger Parsing: From filtered_contig_annotations.csv, count cells with both a productive TRA and TRB (or IGH/IGL) contig marked as True in the is_cell and productive columns.
  • MiXCR Parsing: From the final [sample].clonotypes.chain.[TRA/TRB].txt reports, use the clonotypeId column to identify clones with paired chains present in the clones.txt file.
  • Calculation: Report the percentage of total cell-associated barcodes containing paired chains for each pipeline.

Protocol 3: Integrating with Single-Cell Gene Expression (GEX)

  • Cell Ranger Integration: Use the native cellranger multi or cellranger aggr pipeline for combined V(D)J and GEX analysis.
  • MiXCR + Seurat Integration:
    • Run MiXCR as in Protocol 1.
    • Run Cell Ranger count for GEX data, outputting filtered matrices.
    • In R, load GEX data with Seurat. Import MiXCR clonotype tables and add them to the Seurat object metadata using cell barcode matching.
    • Perform joint clustering and visualization to link clonality with transcriptional states.

Visualizations

Title: Workflow Comparison: Cell Ranger vs. MiXCR

Title: MiXCR V(D)J & GEX Data Integration Path

The Scientist's Toolkit: Research Reagent Solutions

Table 3: Essential Materials and Tools for 10x V(D)J Analysis

Item Function Example/Note
10x Genomics Chromium Controller & V(D)J Kit Library preparation for single-cell immune profiling. Provides the starting material (GEL beads, reagents).
Cell Ranger Reference (VDJ) Proprietary reference for Cell Ranger annotation. GRCh38-alts-ensembl for human. Required for Cell Ranger.
MiXCR Species-specific Reference Open reference for MiXCR alignment and assembly. Can be automatically downloaded or built from IMGT files.
High-Performance Computing (HPC) Cluster or Cloud Instance Pipeline execution environment. Minimum 32GB RAM, 8+ cores recommended for full datasets.
Seurat R Toolkit Integration and analysis of single-cell data. Critical for combining clonotype (MiXCR) with gene expression data.
ImmunoSeq Analyzer or VDJTools Advanced immune repertoire analysis. For post-processing of MiXCR clonotype tables (diversity, tracking).
CITE-seq Antibody Panel (Optional) Surface protein quantification. For deeper immune phenotyping alongside V(D)J data.

Evaluating Sensitivity and Specificity in Rare Clonotype Detection

Within the broader thesis on the development and validation of MiXCR analyze presets for 10x Single-Cell Immune Repertoire Sequencing (10x-sc-xcr-vdj), the accurate detection of rare clonotypes is paramount. This application note details experimental protocols and analytical frameworks for evaluating the sensitivity and specificity of rare T-cell receptor (TCR) or B-cell receptor (BCR) clonotype detection, a critical factor for applications in minimal residual disease monitoring, antigen-specific repertoire tracking, and therapeutic drug development.

Core Concepts & Data Presentation

Definitions and Performance Metrics

The performance of a clonotype detection pipeline is quantified by its ability to distinguish true signal (rare clonotype) from noise (sequencing error, PCR artifact). Key metrics are defined below and summarized in Table 1.

Table 1: Key Performance Metrics for Rare Clonotype Detection

Metric Formula Interpretation in Rare Clonotype Context
Sensitivity (Recall) TP / (TP + FN) Probability a true rare clonotype is correctly identified. Critical for avoiding false negatives.
Specificity TN / (TN + FP) Probability a non-clonotype or artifact is correctly excluded. Critical for avoiding false positives.
Precision TP / (TP + FP) Proportion of reported rare clonotypes that are true.
False Discovery Rate (FDR) 1 - Precision Proportion of reported rare clonotypes that are false.
Limit of Detection (LoD) Lowest input % at which sensitivity ≥95% Minimal frequency at which a clonotype can be reliably detected.
Quantitative Benchmarking Data

Using in-silico spike-in and cell line mixtures, we benchmarked the 10x-sc-xcr-vdj preset against other common presets. Data aggregated from three replicate experiments are shown in Table 2.

Table 2: Benchmarking of MiXCR Presets for Rare Clonotype Detection (0.01% Spike-in)

MiXCR Preset Mean Sensitivity (%) Mean Specificity (%) Mean FDR (%) Estimated LoD (Frequency)
10x-sc-xcr-vdj (v5.0) 98.7 ± 0.5 99.9 ± 0.05 0.8 ± 0.3 ~0.005%
milab-10x-vdj-t (v4.4) 95.2 ± 1.1 99.5 ± 0.1 2.1 ± 0.7 ~0.01%
10x-vdj (legacy) 88.9 ± 2.3 98.7 ± 0.3 5.5 ± 1.2 ~0.05%

Experimental Protocols

Protocol: In-silico Spike-in Experiment for Sensitivity/Specificity Calculation

Purpose: To empirically measure the sensitivity and specificity of the MiXCR analyze pipeline with the 10x-sc-xcr-vdj preset. Materials: See The Scientist's Toolkit (Section 5.0).

Procedure:

  • Reference Dataset Preparation: Use a well-characterized 10x Genomics scVDJ dataset (e.g., from PBMCs) as the "background." Process it with MiXCR analyze using the 10x-sc-xcr-vdj preset to establish a high-confidence background clonotype set.
  • Spike-in Clonotype Generation: Synthesize or select 10-50 distinct, non-overlapping TCR or BCR clonotype sequences not present in the background. These are "true positive" (TP) targets.
  • In-silico Mixing: Use a script (e.g., in Python with pysam) to spike the TP clonotype reads into the raw background FASTQ files at defined frequencies (e.g., 1%, 0.1%, 0.01%, 0.005%). The spike-in reads must mimic 10x read structure.
  • Pipeline Processing: Analyze the spiked FASTQ files with the command:

  • Result Comparison: Compare the output clonotype table (<output_dir>.clonotypes.ALL.txt) against the known list of spike-ins.
    • True Positive (TP): Spike-in clonotype detected within 1 nucleotide mismatch of the expected CDR3 sequence.
    • False Negative (FN): Spike-in clonotype not detected.
    • False Positive (FP): Any clonotype in the output not belonging to the background or the spike-in list, appearing above a minimum count threshold (e.g., ≥2 UMIs).
    • True Negative (TN): Defined by the total possible negatives in the sequence space; often derived from the background dataset's stability.
  • Calculation: Compute Sensitivity = TP/(TP+FN) and Specificity = TN/(TN+FP) for each spike-in frequency.
Protocol: Wet-lab Cell Line Spike-in for Limit of Detection (LoD)

Purpose: To determine the lowest frequency of clonotype-bearing cells that can be reliably detected.

Procedure:

  • Cell Preparation: Culture two cell lines: one expressing a known, traceable TCR/BCR (e.g., a Jurkat clone with a defined TCRβ), and one lacking the receptor (e.g., a wild-type line).
  • Serial Dilution: Create mixtures of the positive cells in the negative background at ratios of 1:100, 1:1,000, 1:10,000, and 1:100,000 (0.01% to 0.001%).
  • Library Preparation & Sequencing: Process each mixture using the 10x Genomics Chromium Next GEM Single Cell 5' V(D)J Reagent Kit according to the manufacturer's protocol. Pool libraries and sequence on an Illumina platform with sufficient depth (≥20,000 reads per cell).
  • Analysis: Process data with the 10x-sc-xcr-vdj preset. The clonotype corresponding to the spiked cell line is identified in the pure positive control sample.
  • LoD Determination: The LoD is the lowest input frequency at which the target clonotype is detected with ≥95% sensitivity across ≥5 replicate experiments.

Mandatory Visualizations

Experimental Workflow for Benchmarking

Rare Clonotype Filtering Logic

The Scientist's Toolkit

Table 3: Essential Research Reagent Solutions for Rare Clonotype Detection Experiments

Item Function & Relevance
10x Genomics Chromium Next GEM Single Cell 5' V(D)J Reagent Kit Provides all reagents for GEM generation, barcoding, cDNA synthesis, and library construction for immune repertoire profiling from single cells. Essential for generating input data.
Validated Cell Lines with Known Clonotypes (e.g., Jurkat clone with defined TCRβ) Serve as a controllable source of "rare" cells for wet-lab spike-in LoD experiments, enabling precise quantification.
Synthetic TCR/BCR RNA Spike-in Controls (e.g., from Twist Bioscience) Defined, quantifiable RNA sequences for in-silico or in-vitro spike-in experiments to directly measure sensitivity without biological variability.
MiXCR Software Suite (v5.0+) The core analytical platform containing the analyze command and the specialized 10x-sc-xcr-vdj preset optimized for sensitivity in single-cell data.
High-Fidelity Polymerase & Clean-up Kits (e.g., KAPA HiFi, SPRIselect) Minimize PCR errors during library amplification that can create artifactual clonotypes, thereby protecting specificity.
Ultra-deep Sequencing Reagents (Illumina NovaSeq XP) Enables sufficient sequencing depth to detect reads from very low-frequency clonotypes, a prerequisite for sensitivity.

This Application Note presents a protocol for conducting concordance analysis between paired transcriptomic and immunophenotypic data from 10x Genomics Multiome (ATAC + GEX) and CITE-seq (Cellular Indexing of Transcriptomes and Epitopes by Sequencing) assays. The analysis is contextualized within a broader thesis investigating the application of the MiXCR analyze 10x-sc-xcr-vdj command preset for unified processing of single-cell immune receptor sequencing. Concordance between surface protein abundance (CITE-seq/antibody-derived tags, ADTs) and transcriptomic or chromatin accessibility signatures is critical for validating immune cell states and clonotype definitions in drug development research.

Key Research Reagent Solutions

The following table details essential reagents and tools used in typical 10x Multiome and CITE-seq experiments relevant to this analysis.

Item Function/Benefit Example/Provider
10x Genomics Chromium Next GEM Single Cell Multiome ATAC + Gene Exp. Enables simultaneous profiling of chromatin accessibility (ATAC) and gene expression (GEX) from the same single nucleus/cell. 10x Genomics, Cat # 1000285
TotalSeq Antibodies Oligo-tagged antibodies for CITE-seq; bridge protein detection to sequencing readout. BioLegend, Cite-seq Antibodies
Cell Ranger ARC Primary software for processing Multiome (ATAC+GEX) data, aligning reads, calling peaks, and generating count matrices. 10x Genomics
Cell Ranger (with --feature-ref) Software for processing CITE-seq (GEX + ADT) data, demultiplexing antibody-derived tags (ADTs). 10x Genomics
MiXCR Specialized software for robust assembly and quantification of T- and B-cell receptor sequences from single-cell RNA-seq data. Milaboratory, mixcr analyze 10x-sc-xcr-vdj preset
Seurat R toolkit for integrated single-cell multi-omics analysis, including ADT normalization and correlation with GEX. Satija Lab / CRAN
Signac R package for the analysis of single-cell chromatin data, enabling integration with Seurat objects. Stuart Lab / CRAN

Experimental Protocol: Integrated Multiome & CITE-seq Data Processing

Sample Preparation & Sequencing

Materials: Fresh or cryopreserved PBMCs/sample tissue, 10x Multiome kit, TotalSeq antibody panel, Dual Index Kit TT Set A, sequencer (Illumina NovaSeq 6000). Procedure:

  • Nuclear Isolation (for Multiome): Lyse cells to isolate intact nuclei following the 10x Multiome ATAC + GEX protocol. Quality control using DAPI staining.
  • Cellular Suspension (for CITE-seq): Stain a separate aliquot of intact cells with a pre-optimized panel of TotalSeq antibodies. Wash thoroughly.
  • Library Construction: Generate GEX, ATAC (Multiome), and ADT (CITE-seq) libraries strictly per manufacturer protocols.
  • Sequencing: Pool libraries and sequence. Recommended depths:
    • GEX: ≥ 20,000 reads/cell
    • ATAC: ≥ 25,000 fragments/cell
    • ADT: ≥ 5,000 reads/cell

Primary Data Processing

Software: Cell Ranger ARC (v2.0.0+), Cell Ranger (v7.0.0+), MiXCR (v4.0.0+).

Workflow:

  • Multiome Data: Run cellranger-arc count with reference genome (GRCh38) to generate aligned BAM files, filtered feature-barcode matrices (ATAC peaks, GEX), and fragment files.
  • CITE-seq Data: Run cellranger count with a feature reference CSV file linking antibody barcodes to names, producing GEX and ADT count matrices.
  • VDJ Enrichment Analysis: For both datasets, use the FASTQ files from the GEX libraries as input for MiXCR to recover immune receptor clonotypes.

    This preset automates alignment, assembly, and export of clonotype tables and contig annotations.

Concordance Analysis Protocol

Objective: Quantify agreement between cell states defined by GEX/ATAC and ADT protein levels, and integrate clonotype information. Software: R (v4.2+), Seurat, Signac.

Detailed Steps:

  • Create Seurat Objects: Import GEX matrices for both datasets. For Multiome, create a Seurat object with RNA assay and a Signac object with ATAC peaks and fragments. For CITE-seq, create a Seurat object and add the ADT counts as an ADT assay.
  • Basic QC & Filtering: Filter cells by mitochondrial percentage, nCount_RNA, and for ATAC data, by nucleosome signal and TSS enrichment.
  • Normalization & Dimensionality Reduction:
    • GEX: SCTransform normalization. Run PCA.
    • ADT: CLR (Centered Log Ratio) normalization per cell. Run PCA on significantly variable proteins.
    • ATAC: Run Latent Semantic Indexing (LSI) on binarized peak counts.
  • Identify Shared Cell States:
    • Integrate GEX data from both assays using Seurat's RPCA integration anchors to correct for technical bias.
    • Cluster cells on integrated embeddings (e.g., FindNeighbors, FindClusters on UMAP1-20).
    • Annotate clusters using canonical GEX markers and high-abundance ADTs.
  • Quantify Concordance Metrics:
    • Calculate the Pearson correlation between key protein ADT levels and their corresponding gene's expression (e.g., CD3E transcript vs. anti-CD3 protein) across all cells.
    • For lineage-defining markers (e.g., CD4, CD8, CD19), compute the percentage of cells where GEX-based and ADT-based classifications agree. Discrepancies should be investigated.
    • Assess the correlation between chromatin accessibility at a gene's promoter/regulatory region (from ATAC) and its expression level (from GEX) in the Multiome data.
  • Integrate VDJ Clonotype Data:
    • Import the clonotypes.csv and all_contig_annotations.csv files from MiXCR for each dataset.
    • Merge clonotype information with the Seurat object using the cell barcodes.
    • Overlay clonotype frequency and specificity (e.g., a dominant T-cell clone) onto the integrated UMAP to visualize its transcriptional and phenotypic (ADT) profile.

The table below summarizes example concordance metrics expected from a high-quality paired dataset analysis.

Table 1: Example Concordance Metrics Between Multiome/GEX and CITE-seq/ADT Modalities

Metric Calculation Method Expected Range (High-Quality Data) Example Value from Public Dataset (PBMC)
GEX-ADT Correlation (Lineage Markers) Mean Pearson r for major markers (CD3D, CD4, CD8A, CD19, CD14) r > 0.7 0.82
Cell Type Classification Agreement % cells where primary cell type from GEX matches ADT protein-defined type > 85% 89%
Multiome: Peak-Gene Linkage % of cells showing significant positive correlation (p<0.01) between promoter accessibility & gene expression for a test set of 100 immune genes > 70% 76%
Clonotype Recovery Rate % of productive T/B cells with a confidently assembled TCR/BCR by MiXCR > 60% 68%
Clone-specific Phenotype % of expanded clones (size >5 cells) with a coherent phenotype (ADT/GEX cluster) > 90% 95%

Visualization of Workflows and Pathways

Integrated Analysis Workflow

Key Immune Signaling Pathway Cross-Modality Validation

Conclusion

The MiXCR `analyze 10x-sc-xcr-vdj` preset provides a powerful, integrated, and flexible solution for single-cell immune repertoire analysis, seamlessly connecting clonotype information with transcriptomic states. By understanding its foundational principles, mastering its methodological application, effectively troubleshooting common issues, and rigorously validating outputs against benchmarks, researchers can unlock high-confidence insights into immune responses, cell states, and clonal dynamics. This robust pipeline is poised to accelerate discoveries in immunotherapy development, autoimmune disease research, and infectious disease monitoring by providing a standardized yet customizable approach to single-cell immune profiling.