Paratope Tree

Turns a whole cohort’s immune receptor repertoire into a single interactive tree of paratope sequences. It reuses the same two clustering stages as the Clustering Pipeline — near-identical sequences collapse into sub-graphs, sub-graphs merge into clusters — and then adds a rendering stage that lays the resulting clusters out as a tree you can explore in the browser, colouring nodes by abundance, CDR3 length, or germline gene call.

Web app slug: paratope-tree-workflow

---

When to use

Use this pipeline when you already know clustering is the right analysis and what you actually want is to look at the result: which cluster families dominate a cohort, how they relate to each other, which subjects populate which branch, and how abundance is distributed across the tree. It is the visual counterpart to the Clustering Pipeline — same inputs, same knobs, different deliverable.

If you only need the cluster tables (cluster_list.tsv, subject → cluster map), run the Clustering Pipeline instead. If you have response labels and want a classifier, run the Stratification Pipeline.

---

How it works

Four stages run strictly in sequence, each verified before the next starts:

T1 sub-graph clustering  →  T2 hierarchical clustering  →  T3 paratope tree render
──────────────────────────  ──────────────────────────────  ──────────────────────────────
ALL subjects' paratope       distances between sub-graphs    clusters reduced to
sequences pooled; near-      computed with the chosen         representatives, BLOSUM
identical ones (sid + cov)   metric, agglomerated, cut at     distances, average linkage,
collapse into sub-graphs     height_cutoff → clusters         laid out and rendered

1. T0 — Validate & ingest — the input bundle is downloaded and unzipped, the cohort sheet is built (or auto-generated) and validated, and every referenced AIRR file is checked before any heavy compute starts. The cohort is capped at 5,000,000 sequences total; larger cohorts are rejected up front rather than failing hours later.

2. T1 — Sub-graph (subG) clustering — all subjects’ paratope sequences are pooled into a single similarity graph. Two sequences are linked when they clear both the sequence-identity (sid) and coverage (cov) thresholds. The connected components are the sub-graphs; with the default sid 0.9 / cov 0.95 a sub-graph is essentially a clonal family. Sub-graph Method picks how they are formed: gsc (default), clonotype, or louvain.

3. T2 — Hierarchical clustering of sub-graphs — a distance is computed between sub-graphs using the chosen metrics, agglomerated with the chosen linkage method, and the dendrogram is cut at height_cutoff to give the final flat clusters. This is the stage that produces lngs_trees.tsv, the input the renderer consumes.

4. T3 — Render the paratope tree — the clusters are turned into a drawable tree and written out as a self-contained HTML report plus a Cytoscape graph. See What the renderer actually draws.

Tip

Stages T1 and T2 are exactly the Clustering Pipeline’s two stages, run with the same parameters and the same defaults. If you have already tuned sid/cov/metrics/height_cutoff for a cohort there, reuse those values here and the tree will be drawn over the same clusters.

What the renderer actually draws

Drawing one node per clonotype would be unreadable and quadratic, so T3 reduces the cohort in three steps before it lays anything out:

• Deduplication — exact-duplicate aligned pseudo-sequences collapse into one weighted entry. Identical sequences are distance 0 from each other, so this is lossless; repertoires are redundant enough that it is usually the single largest reduction.
• Representatives — each cluster is drawn as its representative sequence, with its members folded in as attached leaves. If a run exceeds 50,000 representatives, the set is capped by expression-weighted sampling, so abundant clusters keep their own node.
• Distances & layout — pairwise distances between representatives are computed with a BLOSUM62-based kernel (streamed in row tiles, so memory scales with the tile, not with the square of the cohort), agglomerated with average linkage, and laid out with Graphviz sfdp.

The rendered report is a single self-contained HTML file — no server, no external assets — and it carries every feature at once; you pick which one colours the tree from a selector inside the report rather than at submit time:

Feature	Kind	Notes
nUMIs CLR	numeric	Centered-log-ratio transformed UMI abundance (the default view)
nClones CLR	numeric	CLR-transformed clone abundance
nUMIs log-frequency	numeric	Log-frequency of UMI counts
nClones log-frequency	numeric	Log-frequency of clone counts
CDR3 length	numeric	Coloured on its own scale; does not resize nodes
V / J / C gene	categorical	Germline call per representative, on a categorical palette

Values are aggregated per (representative, subject), so a colour means the same thing in every subject and you can step through subjects without the scale moving under you. A feature whose source data is missing from your AIRR files is simply dropped from the selector rather than silently substituted.

Note

This pipeline does not retry. If a stage fails, the run stops there — fix the cause and submit a new job.

---

Submitting a job

Navigate to Dashboard → Paratope Tree Workflow → New Job.

Required inputs

Field	Description
Job name	A label for this run
Input bundle (zip)	A zip containing the cohort sheet plus one AIRR TSV per subject

The cohort sheet (default filename cohort.tsv, set via Cohort Sheet Filename) needs at minimum a subject column and an airr_file column; any extra metadata columns pass through. If no cohort sheet is found in the bundle, a minimal one is auto-generated from the discovered *.tsv files (one subject per file). Each referenced AIRR TSV must contain sequence_id, v_call, j_call, and sequence_aa (or the alternative set cell_id, v_gene, j_gene, sequence_aa).

Optional inputs

Stage 1 — sub-graph clustering

Field	Default	Description
Receptor chain	TRB	One of IGH, IGL, IGK, TRB, TRA
Species	human	human, mouse, or none (affects germline V/J calls)
Sequence identity (sid)	0.9	Identity cutoff for pairwise similarity, 0 < sid ≤ 1. Ignored when auto-tune is on
Coverage (cov)	0.95	Alignment coverage cutoff, 0 < cov ≤ 1. Ignored when auto-tune is on
Sub-graph method	gsc	Sub-graph algorithm: gsc, louvain, or clonotype
Minimum clones	1	Skip AIRR files with fewer clones than this
CPU cores	0	Threads for similarity calculation (0 = all available cores)
Keep singletons	true	Retain sequences that fall in no sub-graph
Auto-tune sid/cov	false	Detect thresholds from the data (valley search over a random pair sample) instead of using the fixed values
Auto-tune sample size	100000	Random pairs sampled for valley detection; only used when auto-tune is on

Stage 2 — hierarchical clustering

Field	Default	Description
Linkage method	average	single, complete, average, weighted, centroid, median, or ward
Distance metric	sid_cov	See Choosing a Stage 2 metric for the full list
Height cutoff	0.1	Tree-cut height (> 0); units depend on the chosen metric
RPD method	—	Required only when metric is blosum_RPD (integer 1–4); must be unset otherwise
fastcluster backend	true	Faster linkage computation
Use sparse linkage backend	false	Cluster very large sub-graphs that the default path cannot handle. Changes results — see Sparse linkage
S1 lookup table	false	No effect. Every run already takes the lookup-table path, so this flag is accepted and ignored

Lifecycle

Field	Default	Description
Cleanup temporary files	true	Remove the run’s temp directory after upload

Note

Keep singletons defaults to true here, unlike the Clustering Pipeline. Singleton clusters still get a node in the tree, which is usually what you want when you are looking at a repertoire — dropping them hides the low-abundance periphery. Turn it off if the tree is dominated by one-off sequences.

Note

Auto-tune adds an extra sampling/optimization pass and can noticeably increase runtime on large cohorts. Disable it if you already know good sid/cov values. The resolved values are recorded in info.txt so a tuned run stays reproducible.

---

Output files

Everything is packaged into a single results.zip under the run’s output prefix. The archive is the full T1–T3 output tree:

Path	Description
visualization/GMBD_condense.html	The paratope tree — self-contained interactive report with the feature and subject selectors
visualization/GMBD_condense.cyjs	The same graph as Cytoscape JSON, for import into Cytoscape or another graph tool
GMBD.npy	The linkage matrix computed over the representatives
<method>_<sid>_<cov>/hierarchical/<linkage>-<metric>/cluster_list.tsv	All clusters with their member sequences (T2)
<method>_<sid>_<cov>/hierarchical/<linkage>-<metric>/lngs_trees.tsv	The hierarchical tree from T2 — what the renderer consumes
<method>_<sid>_<cov>/config.json	Stage-1 sentinel with the resolved run config (including the real sid/cov when auto-tuned)
airr/	Per-subject AIRR TSVs written by T1, plus subjects.json
db/	Sequence databases built by T1 (pseudo_seq.npz, and clonotype.npz for the clonotype method)
info.txt	Run metadata — chain, species, every resolved parameter, subject counts
logs/error.txt	Errors recorded during the run (No errors recorded when clean)

Tip

The stage-1 and stage-2 directory names encode the parameters that produced them (gsc_0.9_0.95/hierarchical/average-sid_cov/). That is deliberate: you can tell which settings produced a given table from its path alone, and re-running with different settings does not overwrite an earlier result.

---

Troubleshooting

Job rejected: too many sequences The cohort exceeds the 5,000,000-sequence cap. Raise Minimum clones to drop tiny repertoires, pre-filter your AIRR files, or split the cohort into batches.

T2 fails: lngs_trees.tsv has no data rows Stage 2 built a tree but produced no clusters to render. Usually height_cutoff is cutting above every merge — lower it. If T1 also produced very few sub-graphs, sid/cov are too strict; lower them or enable Auto-tune.

metrics='blosum_RPD' but the run fails validation blosum_RPD requires RPD_method set to one of 1–4. Conversely, leaving RPD_method set while choosing any other metric is also rejected — clear it.

Cohort sheet rejected The sheet must have subject and airr_file columns, unique non-empty subjects, and every airr_file must resolve on disk with the required AIRR columns present. The validation error names the exact missing column or unreadable file.

A feature is missing from the report’s selector Features are offered only when the data behind them exists. Abundance features need UMI/clone counts in your AIRR files; the gene-call colourings need v_call / j_call / c_call. A missing source column drops that feature rather than colouring it from a substitute.

The tree looks sparser than the cluster count Above 50,000 representatives the render caps the set by expression-weighted sampling, so rare clusters may not get their own node. Tighten Stage 2 (a lower height_cutoff merges less, a higher one merges more) or raise Minimum clones to bring the count down instead.