scBCR-seq

Start an scBCR-seq analysis

In a project, click New session and choose scBCR-seq as the kind of analysis. The sidebar marks scBCR-seq with a cell beside a Y-shaped antibody.

What to upload

Each sample's gene expression, and beside it the same cells' receptor:

• gene expression: anything the single-cell upload reads — Cell Ranger's filtered_feature_bc_matrix folder or its .h5 file, .h5ad, loom, a Seurat or SingleCellExperiment .rds, or a count table, alone or in a .zip or .tar.gz;
• the receptor: 10x Genomics' V(D)J output (filtered_contig_annotations.csv or airr_rearrangement.tsv), or any AIRR rearrangement table with a cell_id column — IgBLAST through Change-O, nf-core/airrflow, Dandelion or MiXCR.

A receptor table is paired with its expression sample by the barcodes they share, not by its name: GEO sends the two libraries with matching prefixes, but the names cannot be trusted and the barcodes can. The suffix a pipeline adds to a barcode (-1, a sample prefix) does not matter, because both sides are compared on the 10x barcode inside the name. A table whose barcodes match no sample is reported and left out.

An upload with no receptor table is refused, and says where the data belongs instead: gene expression alone is a single-cell RNA-seq session, receptors without the cells a BCR repertoire one.

Give each sample its condition in the metadata dialog. Mutation frequency, isotypes, selection and diversity are all compared between conditions.

Cells, not samples

A BCR repertoire analysis measures a sample: its clone table is samples by clones, and every figure compares samples. It reads single-cell files too, but it counts the cells away. What the cells add is the pairing of a transcriptome with a receptor, so the questions change: which cell states hold the expanded clones, how somatic hypermutation rises along a differentiation path, which clones span two states or two time points, which isotype each cell carries, and the light chain, which only single-cell data pairs with its heavy chain.

So the data object is the single-cell one. Each cell keeps a column for everything a step groups or colours by (clone, clone_size, isotype, mu_freq, v_gene, cdr3_aa, light_chain and the rest), and the sequences, the clones and each cell's chains are kept beside them. A cell with no receptor is not dropped: a B-cell sample holds T cells and myeloid cells too, and the clustering needs them. The B-cell steps work on the cells that have a receptor and say how many they left out.

The workflow

The single-cell steps run as they do in a single-cell RNA-seq analysis: quality control, doublets, normalisation, variable genes, PCA, integration, clustering, annotation, markers, pseudobulk, trajectories and pathways. Three of them differ, because an antibody is expression as well as a receptor:

• Remove Outliers judges a cell on the counts it has outside its own antibody. A plasma cell is an antibody factory: its heavy and light chain can be most of its transcriptome, so a filter on total counts calls it a doublet and throws it away. The totals as they were are kept beside the corrected ones.
• Highly Variable Genes leaves out the receptor's own V, D and J segments and the antibody's constant genes. A plasma cell's own antibody is its largest transcript by far, so with them in, the cells of a clone cluster together by their receptor instead of by their state. Nothing is lost: the isotype is read from the receptor's own constant gene.
• Explore UMAP embeddings also colours the UMAP by the receptor: the clone's size, the isotype, the mutation frequency and the chains the cell carries.

The B-cell steps sit after them. Receptor QC and Clone Definition come first, since everything later reads the clones; Clones and Cell States, Somatic Hypermutation and Lineage Trees need the cell types to be annotated to be worth reading.

Mutations need a germline alignment

Somatic hypermutation is counted by comparing each sequence with the germline it started from, so the uploaded table has to carry that alignment. Cell Ranger writes none: its filtered_contig_annotations.csv has no germline at all, and its airr_rearrangement.tsv writes the whole contig against the whole reference, which is not an alignment. A plain 10x upload therefore gets no mutation frequencies, and Somatic Hypermutation and Selection Pressure say so in the figure and name what to run. Lineage Trees still work, rooted at each clone's own consensus instead of its germline.

Re-annotating the contigs gives them the alignment. With Immcantation: AssignGenes.py igblast, then MakeDb.py igblast --10x, which writes the IMGT-gapped alignment that mutations by region and selection need. nf-core/airrflow and Dandelion write it too, and MiXCR carries its own alignments. Upload the re-annotated table in place of Cell Ranger's.

Step reference