Assemble B-cell and T-cell receptor sequences from single-cell RNA-seq.
Version 2.0 (2026/10/18) · patch 2.0.1
BASIC reconstructs candidate immune-receptor transcripts from a cell's short RNA-seq reads. It assembles B-cell receptor (BCR) heavy and light chains and T-cell receptor (TCR) chains. Each run takes the cell's reads, species, and receptor type and produces assembled sequences and reports. Human and mouse references are included.
Reads must already be separated by cell. BASIC does not separate cell barcodes or deduplicate UMIs.
Download and run · Conda · Agent skills
Assembly settings · Other organisms · IgBLAST · Benchmarks
BASIC runs directly from the downloaded source on Linux or macOS. You need Python 3.10+ and Bowtie2; no Conda, pip installation, or additional Python packages are required.
- Download the BASIC 2.0 source ZIP.
- Extract it and open a terminal in the extracted folder.
- Run the included human B-cell example:
python3 BASIC.py --version
python3 BASIC.py -SE examples/cell_A1/ERR1421621_1M_reads.fastq.gz \
-g human -i BCR -n result -o results/cell_A1 -p 2Keep the source folder together: BASIC.py uses the accompanying
basic_assembler/ code and db/ references. If Bowtie2 is not on your
executable search path, append -b /path/to/bowtie2 to the assembly command.
Check python3 --version if you are unsure which Python is installed.
This example has one million single-end reads. Expect two contigs: a heavy
chain of 878 nucleotides and a light chain of 829 nucleotides, saved in
results/cell_A1/result.fasta. Reports are saved in the same directory. The
comparison below checks both sequences against the supplied result.
Add --check to verify paths, indexes, and dependencies before assembly; it
does not read every FASTQ record. To rerun, choose a new output directory or
add --overwrite to replace existing results.
If you prefer Conda to manage Python and Bowtie2, run these commands from the extracted source folder:
conda env create -f environment.yml
conda activate basic-2
python3 BASIC.py --versionThen run the examples with python3 BASIC.py as above. To also install the
basic-assemble command used in the extended guides, run
python -m pip install . in this environment. It accepts the same arguments
as python3 BASIC.py.
The installation guide covers release wheels, pipx,
uv, and platform details. PyPI publication is deferred; the Bioconda basic
package update is still pending. The Conda environment above works with the
downloaded source now.
BASIC includes a portable skill for Codex, Claude Code, and Antigravity (agy). It guides an assistant through input checks, BCR/TCR assembly, custom references, optional annotation, and interpreting results.
From the extracted BASIC folder, copy the skill into an existing analysis project:
python3 -m basic_assembler.skill_cli --agent all \
--project '/path/to/analysis-project'This installs the skill in the project's .agents/skills/basic-assemble/
and .claude/skills/basic-assemble/ folders. It copies instructions only;
Python, Bowtie2, and the BASIC source must still be available.
Open that project in your assistant and provide the BASIC source location. For example:
Use the basic-assemble skill and the BASIC source at /path/to/BASIC to assemble the human BCR reads in reads/cell_001.fastq.gz. Check the inputs first and save the results in results/cell_001.
See the agent skill guide for individual assistant options and updating an existing skill.
Each sequencing read covers a short part of a transcript. Assembly joins overlapping reads into a longer sequence, called a contig. BASIC assembles immune-receptor contigs in three steps:
- Find starting reads. Bowtie2 finds reads that match known variable and constant regions of a receptor. BASIC uses these reads as seeds.
- Extend through overlaps. BASIC extends the seeds using exact sequence overlaps with other reads from the same cell.
- Report candidate chains. BASIC writes the assembled sequences and reports whether the variable and constant seeds connect, the read support, and any ambiguity encountered during assembly.
A complete assembly connects its seeds. This does not guarantee a full coding sequence, a productive receptor, or a correct CDR3. Optional IgBLAST annotation can add gene calls, junction/CDR3 information, and predicted productivity.
Use reads with coverage across the receptor transcript. BASIC accepts single-end or paired-end FASTQ files, plain or gzipped, with Phred+33 quality scores. Paired files must contain the same number of reads with matching identifiers.
Replace the filenames below with reads from one cell:
# Human BCR, paired-end reads
python3 BASIC.py -PE_1 cell_R1.fastq.gz -PE_2 cell_R2.fastq.gz \
-g human -i BCR -n cell_001 -o results
# Human TCR, single-end reads
python3 BASIC.py -SE t_cell.fastq.gz \
-g human -i TCR -n t_cell_001 -o resultsUse -g mouse for mouse reads. TCR outputs carry locus labels such as TRA
and TRB; matching mouse reads and references also support gamma/delta
(TRG/TRD) candidates. Recovery depends on the reads and available seeds.
By default, BASIC exits with an error if assembly is incomplete. Add -a
to retain partial or empty assembly results. Invalid input and execution
errors still cause the run to fail. Use -p 4 for four Bowtie2 threads or
-b /path/to/bowtie2 to select the executable. Run python3 BASIC.py --help for
all options.
For the included example, look in results/cell_A1/:
| File | What it tells you |
|---|---|
result.fasta |
Assembled nucleotide sequences |
result.summary.tsv |
Status and ambiguity by chain or reference group |
result.airr.tsv |
Sequences and assembly metadata in an AIRR-compatible table |
result.run.json |
Parameters, versions, diagnostics, and file checksums |
result.logs/ |
Bowtie2 diagnostics |
A chain is complete when its seeds connect, partial when a seed yields a contig but the seeds do not connect, or unsupported when neither seed is usable. Execution failures are recorded separately when possible. Gene-call, CDR3, and productivity fields remain empty unless annotation supplies them. Read support counts read observations, not molecules, and is not a confidence score.
For automated workflows, use the run manifest as the completion marker and verify its output checksums. See output and algorithm details.
The defaults retain BASIC's original extension scoring. If a chain is partial, beam search can explore alternative overlaps, and additional anchors can give assembly different starting reads. Compare the same cell in separate output directories:
# Default search; retain partial results for inspection
python3 BASIC.py -PE_1 cell_R1.fastq.gz -PE_2 cell_R2.fastq.gz \
-g human -i BCR -n cell_001 -o results/default -a
# Try more paths and starting reads
python3 BASIC.py -PE_1 cell_R1.fastq.gz -PE_2 cell_R2.fastq.gz \
-g human -i BCR -n cell_001 -o results/beam -a \
--beam-width 4 --max-anchors 2These are settings to try, not established accuracy improvements. They cost more time and memory and can produce competing contigs.
| Option | What it changes |
|---|---|
--beam-width 4 |
Keeps alternative overlap paths instead of following one path; default 1 |
--max-anchors 2 |
Tries up to two starting reads per locus on each V/C side; default 1 |
--max-candidates 2 |
Retains more distinct seed-pair results; default 1. It does not widen the search or impose a two-contig limit |
For a separate paired-read experiment, add
--scoring evidence --quality-weighted --mate-aware to the broader-search
command and choose another output directory. This ranks extensions using
read quality and mate support. Both flags require --scoring evidence;
--mate-aware also requires paired reads and does not enforce fragment length
or orientation. See the algorithm guide for the scoring rules.
Use the summary and run manifest to decide what to try next:
| Observation | What to check |
|---|---|
Missing seeds or an unsupported chain |
Species, reference content, and receptor read coverage |
no_supported_overlap |
Coverage gaps and read quality; extension requires exact overlaps |
max_steps or max_contig_length |
Whether a search limit stopped a plausible assembly before increasing that limit |
If receptor reads are present but divergent from the references, try
--local-seeding in a separate run. It allows local reference matches during
seed selection and can admit less specific reads; extension still requires
exact read overlaps.
Keep --min-overlap 15 and --min-support 2 initially. Lower thresholds can
create false joins. Quality trimming (--trim-quality 20) may help poor read
ends but also removes overlap evidence. More search cannot recover sequence
absent from the reads, and a longer contig is not necessarily more accurate.
BASIC can assemble BCRs and TCRs from other species when suitable variable and constant references are available. The reference tool can search NCBI and download selected accessions or HTTPS FASTA files; local FASTA files work too.
For example, search for rabbit records:
python3 -m basic_assembler.reference_builder search \
--organism 'Oryctolagus cuniculus' --query 'immunoglobulin' \
--limit 10 --output rabbit_candidates.jsonSearch results need biological review. Select the relevant regional sequences
and prepare rabbit_sources.json using the
manifest example.
It declares all four V/C reference groups, their loci, and sequence orientation.
Then build the indexes and assemble a cell:
python3 -m basic_assembler.reference_builder build \
--manifest rabbit_sources.json --output ./references \
--species rabbit --receptor BCR \
--bowtie-build /path/to/bowtie2-build
python3 BASIC.py -SE rabbit_cell.fastq.gz -g rabbit -i BCR \
-d ./references -n rabbit_cell -o results/rabbitAccession downloads retrieve whole records; the builder does not extract
exons or turn a chromosome into a receptor reference. Supported locus names
are IGH, IGK, IGL, TRA, TRB, TRG, and TRD.
If references are unavailable, --seed-species related_species --local-seeding
can try an existing related-species library while -g names the target
species. This is experimental: BASIC neither chooses the related species nor
infers a germline catalogue. It still assembles the target cell's reads by
exact overlaps. See the non-model organism guide
for the full workflow and its limits.
Optional IgBLAST annotation adds V/D/J gene calls, junction/CDR3 sequences,
and predicted productivity to <sample>.airr.tsv. It annotates the assembled
contigs; it does not extend or repair them.
Install igblastn and obtain or build species-matched nucleotide BLAST
databases using the NCBI setup guide.
Supply V and J databases, a D database for VDJ loci, and a J auxiliary file
matching the database sequences and identifiers. These are separate from
BASIC's Bowtie2 seed indexes.
Replace the paths below with your installation and database prefixes:
python3 BASIC.py -PE_1 cell_R1.fastq.gz -PE_2 cell_R2.fastq.gz \
-g human -i BCR -n cell_001 -o results/annotated \
--igblast /opt/igblast/bin/igblastn \
--germline-v /data/igblast/human_ig_V \
--germline-d /data/igblast/human_ig_D \
--germline-j /data/igblast/human_ig_J \
--auxiliary-data /opt/igblast/optional_file/human_gl.aux \
--igdata /opt/igblast--igdata points to the directory containing internal_data. For TCRs, use
-i TCR with TCR databases and matching J auxiliary data. Add
--germline-c /data/igblast/human_ig_C for C-gene calls when supported by your
IgBLAST version; isotype assignment depends on sufficient constant sequence.
For a non-model species, IgBLAST also needs the
custom-organism setup
under the species name passed to -g. Building BASIC references alone does
not provide it. Missing annotations stay empty: an empty productive field
does not mean an unproductive receptor. See annotation details.
Compare the example you just assembled with the supplied BASIC result:
python3 benchmarks/benchmark.py \
--expected-fasta examples/cell_A1/result.fasta \
--actual-fasta results/cell_A1/result.fasta \
--label included-human-bcr-regression \
--output results/cell_A1/comparison.jsonExpect exact_match_count: 2, exact_recall: 1.0, and exact_precision: 1.0
in the JSON report's sequences object. Keep -n result in the example
assembly command so the FASTA identifiers match. This checks that the run
reproduces the stored assembly. Measuring biological accuracy requires
independently validated sequences.
For your own benchmark, pass the validated sequence file to --expected-fasta
and your assembly file to --actual-fasta. Match FASTA identifiers
and sequence orientation first: the script does not align or automatically
pair contigs. Optional AIRR tables add gene-call, junction/CDR3, and productivity
comparisons. The benchmark guide covers timing,
metric definitions, and comparisons between tools or settings. See the
validation report for measured results and their limits.
For benchmarking, compare the defaults with --beam-width 4 --max-anchors 2
as a starting point for a broader search. For paired reads, also test adding
--scoring evidence --quality-weighted --mate-aware. These options target
missed paths, alternative starting reads, and branch selection; they are not
validated accuracy presets. The benchmark settings guide
includes a runnable example and explains how to compare recovery, extra
predictions, and runtime.
| Task | Where to start |
|---|---|
| Process many cells | Batch TSV format and commands |
| Add gene and CDR3 annotations | IgBLAST setup and usage |
| Work with another organism | Build references from FASTA, HTTPS sources, or NCBI accessions |
| Use an AI coding assistant | Portable skill for Codex, Claude, and Antigravity |
| Explore assembly settings | Algorithms and experimental options |
- BCR and TCR assembly: indexed overlap searches, shared read pools, deterministic tie-breaking, and bounded searches; the default retains BASIC's original entropy-based extension rule.
- TCR reporting: locus-aware chain labels, corrected historical mouse ordering, and support for matching mouse gamma/delta seeds.
- Workflows: stricter input checks, protected outputs, structured reports, per-cell batches, optional annotation, and custom reference tools.
- Optional features: quality and mate evidence, alternative assembly paths, and multiple candidates.
Patch 2.0.1 fixes error handling when the operating system denies process-group cleanup. See the changelog and migration notes. For development, see testing and release instructions.
Canzar S, Neu KE, Tang Q, Wilson PC, Khan AA. BASIC: BCR assembly from single cells. Bioinformatics 33(3), 1 February 2017.
BASIC is released under the MIT license. The bundled references come from BASIC 1.5.0; their original download dates are unknown. See reference provenance and the historical license notice. Reference data and external tools remain under their own terms.