baSeq docs › BCR repertoires

BCR repertoires

A BCR Repertoire analysis takes B-cell receptor sequences, from bulk or single-cell sequencing, groups them into clonal lineages and measures somatic hypermutation, isotypes and class switching, how the largest lineages evolved, and the antibodies different people made alike.

Start a BCR repertoire analysis

In a project, click New session and choose BCR Repertoire as the kind of analysis. The sidebar marks BCR repertoires with a Y-shaped antibody.

What to upload

A sequence table per sample, or one table with a sample column, from any of these:

AIRR rearrangement files from IgBLAST or Change-O (junction, v_call, j_call, c_call, duplicate_count, and for somatic hypermutation sequence_alignment with germline_alignment_d_mask, or v_identity), including Change-O's older column names (SEQUENCE_IMGT, GERMLINE_IMGT_D_MASK, FUNCTIONAL, DUPCOUNT);
10x Genomics airr_rearrangement.tsv or filtered_contig_annotations.csv, counted as cells: each cell's best heavy and light chain;
MiXCR clone exports, with allCHitsWithScore for the isotype and vBestIdentityPercent for somatic hypermutation;
Adaptive ImmunoSEQ IGH exports, TRUST4, VDJtools and immunarch tables.

Files can be gzipped. Each file's name becomes its sample's name (without 10x's _filtered_contig_annotations), unless the table names its samples. What the files hold decides what the steps can show: isotypes need C gene calls, mutations need a germline alignment or the V identity, and mutations by region need IMGT-gapped alignments (Change-O or IMGT/HighV-QUEST). A step says so when the files lack what it needs.

Clones are lineages

A B cell that meets its antigen divides and mutates its receptor (somatic hypermutation), so one clone is a family of related sequences, not one exact sequence as a T-cell clonotype is. baSeq groups heavy chains with the same V gene, J gene and junction length whose junctions differ at no more than a share of their positions, as Change-O and SCOPer do. That share is read from your data: each junction's distance to its nearest neighbour has two modes, relatives near 0 and unrelated junctions further out, and the threshold is the valley between them (as SHazaM's findThreshold). Clone Definition shows that distribution, and sets another threshold or keeps each donor's clones apart. Clones are named C1, C2 and so on, largest first. In single cell, cells with the same heavy chain but different light chains are different clones.

Clones then go through the same measures as TCR clonotypes: diversity, clonal expansion, overlap, clone tracking and expanded clones (where a "clonotype" is a clone).

Somatic hypermutation, isotypes and lineages

The mutation frequency is the share of the V gene's positions that differ from the germline: naive B cells barely mutate, memory and plasma cells often 5% or more. Class-switched cells (IgG, IgA) are usually more mutated than IgM and IgD. A cell switches class by deleting the constant genes before the new one, so switching runs one way along the locus, from IgM and IgD towards IgA2; the arc diagram in Isotypes and Class Switching follows that order and joins two isotypes as thickly as the clones that hold both. Lineage Trees draws the largest clones rooted at their germline, so the mutations every member shares (the trunk) and the branches that switched isotype or spread between time points are visible.

Sample metadata

As for TCR repertoires: a condition per sample, and a patient or donor column for Pair by (each person compared with their own samples), for Clone Definition (no clone across two people) and for Convergent Clones (antibodies two people or more made alike).

Step reference

Step	Stage	What it does	You get	Key inputs
Data Upload	Setup	Reads the sequence tables, names genes and isotypes as IMGT does, keeps the productive sequences, measures each sequence's mutations and groups the heavy chains into clones at a threshold read from the data.	A data object with every clone of every sample, every sequence with its clone, isotype and mutations, and where each sample came from. A plot of the counts by chain, the clones and the isotypes per sample.	Sequence tables (see What to upload).
Repertoire QC	QC	Shows how well each sample was sampled: productive counts, sequences and clones, the unproductive share, the share of clones seen once and of the ten largest, Chao1, rarefaction curves, and how many sequences the clones hold. In single cell, each cell's chains (two heavy chains are mostly doublets).	Rarefaction curves, the largest clones' and unproductive shares, the clone sizes or each cell's chains, and a table per sample.	None.
Clone Definition	QC	Groups the heavy chains into clones again: the same V and J gene and junction length, and junctions within the threshold (single linkage). Automatic reads the threshold from the valley of the distance-to-nearest distribution; a donor column keeps each person's clones apart. In single cell the light chain splits a clone. The later steps read the new clones.	The distances with the threshold, the clones' sizes, the clones per sample before and now, and a table of the clones with two sequences or more.	Junction distance: Automatic (default), 0.10 to 0.25, or Identical junctions; Donor.
Diversity	Analysis	As for TCR repertoires, on clones: every sample at the same depth, Hill numbers, the groups compared.	The diversity profile, three measures per group with p-values, and the tables.	Parameter to compare, Sequencing depth, Pair by.
Clonal Expansion	Analysis	How much of each sample its large clones hold, by clone size and by rank, and D50.	Stacked bars per sample and each sample's 20 largest clones.	Parameter to compare.
Somatic Hypermutation	Analysis	Each heavy chain's mutation frequency from its germline V gene (IMGT positions 1-312), per sample and group, by isotype and against clone size; with IMGT-gapped alignments, replacement and silent mutations in the CDRs and FWRs.	Violins per sample, the mean by isotype per group, mutation against clone size, and R and S mutations by region.	Parameter to compare, Pair by.
Isotypes and Class Switching	Analysis	Each isotype's share of a sample's heavy chains (IgM, IgD, IgG1-4, IgA1-2, IgE), compared between the groups (Benjamini-Hochberg over the isotypes), and the clones that hold two isotypes or more.	Stacked bars per sample, each isotype by group, an arc diagram of class switching along the constant genes, and the share of clones that switched.	Parameter to compare, Count: Counts (default) or Clones, Pair by.
V and J Gene Usage	Analysis	As for TCR repertoires, on the heavy chain's V and J genes.	Heatmaps per sample, and tables.	Parameter to compare, Weight by.
Lineage Trees	Analysis	The largest clones with three distinct sequences or more, as trees rooted at their germline: neighbor-joining on the mutations between sequences. The trunk is the mutations all of a clone's sequences share.	A tree per clone, tips sized by count and coloured by isotype, sample or a metadata column, and a table.	Clones to draw (3 to 12), Colour tips by.
CDR3 Properties	Analysis	Each clone's CDR-H3: length (the spectratype), hydropathy (GRAVY), net charge, aromatic and tyrosine residues, and the share of long CDR-H3s; each sample's means compared between the groups.	The spectratype, hydropathy and charge by group, and each sample's means.	Parameter to compare, Weight by: Clones (default) or Counts.
Heavy and Light Chains	Analysis	Kappa and lambda per sample and group, the light-chain V genes, and in single cell each cell's chains and which heavy V genes pair with which light V genes.	The kappa share per group, the light-chain V genes per sample, and the paired V genes.	Parameter to compare.
Repertoire Overlap	Analysis	As for TCR repertoires: Morisita-Horn and Jaccard between samples, on clones.	Two heatmaps and the clones in two samples or more.	Parameter to compare.
Clone Tracking	Analysis	Follows the largest clones of one group through every sample (with Pair by, each person's own).	A line per clone across the samples.	Parameter to compare, Follow, Clonotypes to follow, Pair by.
Expanded Clones	Analysis	The clones that take a larger or smaller share in one group than in another (a binomial test per clone, Benjamini-Hochberg adjusted); with Pair by, each person against their own samples.	Each clone's share in the two groups, the largest expanded clones, and tables.	Parameter to compare, two values, Pair by.
Convergent Clones	Analysis	Clones of different people with the same V and J genes and nearly the same CDR-H3: antibodies made alike, often against the same antigen.	The groups in the most people, and their CDR3s with the residues coloured by chemistry.	Donor, CDR3 amino acids alike: 80% (default), 85%, 90% or Identical.

Checked on planted data

On a simulated vaccine response in two donors (IMGT-gapped AIRR files: naive and memory B cells, and eight responding lineages per donor, mutated and class-switched), every responding lineage is found as one clone, the responders' mutation frequency, IgG1 share and expansion rise after the vaccine, their lineage trees are rooted at the germline with the planted trunk, and the one antibody both donors made alike is the one convergent group (tests/pipelines, TestBcr).