home / skills / gptomics / bioskills / tcr-pipeline

tcr-pipeline skill

safe

This skill guides end-to-end TCR/BCR repertoire analysis from FASTQ to clonotype diversity, coordinating MiXCR, VDJtools, and Immcantation workflows.

npx playbooks add skill gptomics/bioskills --skill tcr-pipeline

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

2.1 KB

---
name: bio-workflows-tcr-pipeline
description: End-to-end TCR/BCR repertoire analysis from FASTQ to clonotype diversity metrics. Use when analyzing immune repertoire sequencing data from bulk or single-cell experiments.
tool_type: cli
primary_tool: MiXCR
---

## Version Compatibility

Reference examples tested with: MiXCR 4.6+, VDJtools 1.2.1+

Before using code patterns, verify installed versions match. If versions differ:
- CLI: `<tool> --version` then `<tool> --help` to confirm flags

If code throws ImportError, AttributeError, or TypeError, introspect the installed
package and adapt the example to match the actual API rather than retrying.

# TCR/BCR Analysis Pipeline

**"Analyze my TCR/BCR repertoire sequencing data end-to-end"** → Orchestrate MiXCR clonotype extraction, VDJtools diversity/repertoire analysis, Immcantation SHM and lineage analysis, and visualization of V/J gene usage and clonal dynamics.

## Pipeline Overview

```
FASTQ → MiXCR align → Assemble → Export → VDJtools diversity → Visualization
```

## Step 1: MiXCR Processing

```bash
# Align reads to V(D)J segments
mixcr align -s hsa -p rna-seq \
    R1.fastq.gz R2.fastq.gz \
    aligned.vdjca

# Assemble clonotypes
mixcr assemble aligned.vdjca clones.clns

# Export
mixcr exportClones clones.clns clones.txt
```

## Step 2: VDJtools Analysis

```bash
# Convert to VDJtools format
vdjtools Convert -S mixcr clones.txt vdjtools/

# Diversity metrics
vdjtools CalcDiversityStats vdjtools/clones.txt diversity/

# Sample overlap
vdjtools CalcPairwiseDistances vdjtools/*.txt overlap/
```

## Step 3: Visualization

```bash
# Spectratype plot
vdjtools PlotFancySpectratype vdjtools/clones.txt spectra/

# V usage
vdjtools PlotFancyVJUsage vdjtools/clones.txt usage/
```

## QC Checkpoints

1. **After alignment**: Check V/J assignment rate (>70% typical)
2. **After assembly**: Verify clonotype count and coverage
3. **After diversity**: Compare metrics to expected range

## Related Skills

- tcr-bcr-analysis/mixcr-analysis - Detailed MiXCR usage
- tcr-bcr-analysis/vdjtools-analysis - Diversity metrics
- tcr-bcr-analysis/repertoire-visualization - Plots

Overview

This skill provides an end-to-end pipeline for TCR/BCR repertoire analysis, taking sequencing FASTQ files through clonotype extraction, diversity metrics, and visualization. It orchestrates MiXCR for alignment and assembly, VDJtools for diversity and overlap statistics, and common visualization steps for V/J usage and spectratypes. The workflow includes QC checkpoints to validate assignment rates and clonotype coverage.

How this skill works

The pipeline runs MiXCR to align reads to V(D)J segments, assemble clonotypes, and export clone tables. It then converts MiXCR output to VDJtools format and computes diversity statistics, pairwise sample distances, and overlap measures. Finally, the pipeline produces standard visualizations—spectratypes, V/J usage plots, and clonal dynamics—while exposing QC metrics at defined checkpoints.

When to use it

Analyzing bulk TCR/BCR immune repertoire sequencing from FASTQ to metrics
Processing single-cell V(D)J data after read pre-processing
Generating diversity and overlap statistics across samples or timepoints
Producing publication-ready V/J usage and spectratype visualizations
Validating immune profiling QC (assignment rates, clonotype coverage)

Best practices

Confirm tool versions (MiXCR >=4.6, VDJtools ~1.2.1) before running; check --version and help flags if different.
Inspect CLI outputs and sample-level QC after each checkpoint: alignment V/J assignment rate and clonotype counts.
If Python APIs throw ImportError/AttributeError, introspect installed package attributes and adapt examples to the local API.
Run MiXCR with appropriate species and protocol flags (for example -s hsa and -p rna-seq for human RNA-seq).
Organize intermediate files (vdjca, clns, exported clones) in folders to simplify VDJtools conversion and downstream plotting.

Example use cases

Bulk immune repertoire study comparing disease vs control: FASTQ → MiXCR → VDJtools diversity → differential interpretation.
Longitudinal patient monitoring: compute pairwise overlap and clonal dynamics across timepoints to track expansions/contractions.
Single-cell V(D)J follow-up: extract clonotypes from cell-level FASTQ then visualize V/J usage and spectratype distributions.
Method development: test different MiXCR parameters and compare resulting diversity metrics with VDJtools to optimize pipeline settings.

FAQ

What versions of tools are recommended?

Examples were tested with MiXCR 4.6+ and VDJtools 1.2.1+. Verify installed versions and adapt flags/APIs if versions differ.

What QC thresholds should I use?

A common checkpoint is V/J assignment rate >70% after alignment; clonotype counts should be consistent with expected library complexity. Interpret diversity metrics relative to matched controls and experiment design.