B-cell clonal families

B cells → Families keeps threshold-dependent families separate from existing junction clonotypes.

Inspect distances first

Open BCR data, annotate each sample's subject in Data, then choose B cells → Families. Leave the threshold empty and select Measure nearest distances. The distribution counts each distinct nucleotide receptor once within its scope, without abundance weighting. A receptor with no comparable neighbor is reported separately, not as distance zero.

Choose Within subject to compare samples of the same person. Missing subjects are excluded; they are never pooled. Within sample is an explicit alternative when subject annotations are unavailable or samples should be analyzed independently. The QC filter applies before grouping.

Choose an explicit threshold

Distance is nucleotide mismatches divided by junction length, within identical V gene, J gene and junction-length partitions. Only productive ACGT junctions with resolved genes are eligible. Same-gene allele ties are accepted. Ambiguous genes, junctions and missing evidence are reported as exclusions.

Enter a value between 0 and 1, choose Apply threshold, then Find clonal families. Edges join receptors whose distance is at most the threshold. Connected components implement single linkage: a chain of links can join endpoints farther apart than that threshold. Zero gives exact identity; an empty threshold gives distances only. ClonoLoom does not fit a threshold automatically.

The method follows the published partitioning and clustering framework of Gupta et al. (2015) and Gupta et al. (2017). Families express a chosen sequence-similarity criterion, not proven ancestry or antigen specificity.

Heavy and light chains

Auto selects paired mode when cell IDs are present; otherwise it uses heavy chains. Paired mode requires exactly one distinct heavy and one distinct kappa or lambda chain per cell. Identical duplicate chains collapse. Missing, invalid or multiple distinct chains exclude that observation. Cell IDs are scoped by sample.

Paired distance is the larger heavy/light normalized distance, and both chains must match their own V/J/length partitions. This conservative paired policy is specific to ClonoLoom. Heavy-only mode is also available. Each eligible cell contributes one to sample abundance, regardless of contig counts. Bulk rows retain their count unit; unknown abundance remains missing.

Inspect and export

Select a family to page through its observations, then select an observation to inspect cell, sequence and source identities. Nearest receptors and all observations, including exclusions, have separate pages. Results are immutable and reopen from the project tree even after choices change.

Export result writes every family/sample total, nearest receptor and source-row membership, alongside the complete JSON, manifest and cited NOTICE. Membership abundance belongs to the observation: do not sum its repeated value across heavy/light source rows. Blank nearest distances and abundance are missing, not zero. The figure export carries its method caption; the methods paragraph names the saved choices and sources.

Exact work is limited to 250,000 observations and 200 million base comparisons. Exceeding a limit stops the job with an explanation; no hidden sampling occurs. Narrow the QC filter or explicitly analyze within sample when appropriate.

Review descriptive candidates

From saved thresholded families, choose Review B-cell candidates. Select one current sample, optional matching SHM/isotype results, and one to four ordered criteria with their directions. The ranked universe includes every family in the selected scope, even when its current count is zero. There is no automatic composite score.

Assigned observations counts sample-scoped cells or bulk heavy-chain rows, without read or molecule weighting. Heavy nucleotide divergence pools observed differences over evaluable V/J bases in current heavy rows. Every row must contribute evaluable evidence; this does not require complete V/J coverage or provide independent replicates. Preferred isotype share needs an explicit class and complete observed class resolution. Partial counts remain visible when either metric is unavailable.

Observed share change is the current family share minus its share in an explicitly named different sample from the same subject, under subject-scoped families. It is not an expansion test. Sampling and QC affect both denominators. Missing evidence sorts last in either direction; exact rational comparisons preserve tied competition ranks. Stable identifiers order display ties without breaking ranks.

Select one current observation and one source chain separately. Review supplied amino acids rechecks the original AIRR source bytes and shows its unchanged sequence_aa. FASTA accepts only 25–5,000 canonical uppercase amino acids; missing values are not translated or repaired. The complete_vdj annotation does not establish full protein completeness, and a cell-associated assignment does not independently validate biological pairing. Review the sequence limits and provider terms before downloading FASTA and its two exact evidence companions. These are not synthesis-ready constructs.

Open Proteoscope review (sends nothing) opens the existing handoff workflow with that row selected. Review the destination and grant fresh local/public/provider permissions there. No destination is probed and no query is sent by opening the dialog.

Save the native review before closing. It contains the complete ranked universe, current source observations, original parent JSON text/hashes, methods and provider notice. It is separate from project artifacts and scientific replay, and is not de-identification. The bounded review accepts at most 50,000 observations and 5,000 families; parent and output size limits are documented in the full candidate contract.

These ordering policies are ClonoLoom choices. The study of plasma-cell repertoires by Neumeier et al. (2022) illustrates why expansion or mutation burden alone should not be treated as a calibrated affinity predictor; its findings do not establish a universal absence of associations. Independent rational/count checks validate this implementation, not biological efficacy.

Known artificial families

Open the artificial B-cell immunization example and follow its distance and family steps. The 2,160 cells contain 133 distinct paired nucleotide receptors. At 0.05 they form 43 families; at 0.1 they recover the exact 36 known families. An independent CSV/graph calculation verifies all memberships and nearest distances. This checks artificial truth, not biological accuracy. Continue to Germlines for reference reconstruction. Continue from germlines to SHM and Lineages, or summarize Isotypes directly from saved families.