Stratification Pipeline

The Stratification pipeline extends hierarchical clustering with response-aware feature selection and a LOOCV SVM classifier. It takes a cohort with clinical response labels and reports how separable the two response groups are — pooled ROC/PR curves, a metrics table, and the clusters that drove the separation.

Web app slug: stratification-pipeline

---

When to use

Use this pipeline when your cohort TSV includes a response column (clinical outcome label, e.g., responder/non-responder) and you want to:

• Select immune repertoire features that distinguish response groups
• Evaluate separability with a Leave-One-Out Cross-Validation (LOOCV) SVM
• Generate interpretable heatmaps and volcano plots

Note

This is an evaluation pipeline, not a model-training one. Each LOOCV fold trains its own SVM to predict the held-out subject; no fitted model is serialized for reuse on new samples. What you get back is the cross-validated performance estimate and the feature evidence behind it.

---

How it works

The run is a chain of seven stages, referenced as T0–T6 in job logs and error messages:

Stage	What it does
T0	Validate the cohort sheet — subject, airr_file, and response columns; ≥ 2 subjects
T1	Sub-graph clustering — identical to Clustering Stage 1
T2	Hierarchical clustering of sub-graphs
T3	Map clusters back to subjects and sequences
T4	Optional interactive HTML report
T5	Response-aware feature selection — heatmap + volcano
T6	LOOCV SVM classification

T0–T3 are the Clustering pipeline; T4–T6 are what stratification adds.

---

Submitting a job

The stratification pipeline uses a 6-step stepper form in the web app.

Navigate to Dashboard → Stratification Pipeline → New Job.

Step 1: Cohort sheet

Upload a cohort TSV. Required columns:

Column	Description
subject	Unique, non-empty subject identifier
airr_file	Path to that subject’s AIRR TSV, resolved against the sheet’s own directory in the bundle
response	Clinical response label (e.g., responder, non-responder, or 0/1)

Extra metadata columns pass through; see Cohort TSV for the full contract, including the condition column the HTML report needs. The cohort needs at least 2 subjects — LOOCV cannot fold a single sample.

Step 2: Clustering parameters

Stages T1–T3 are the Clustering pipeline verbatim — every field in its optional inputs applies here unchanged (chain, species, sid, cov, clust_method, min_clones, ncpu, singleton, auto-tune, method, metrics, height_cutoff, fastcluster, sparse_linkage, RPD_method, S1).

Two of those are worth calling out here: Use sparse linkage backend trades exactness for the ability to cluster very large sub-graphs and changes the clusters you get — which in this pipeline means it changes the features T5 and T6 are built from. S1 is a no-op, retained only so existing presets keep loading.

CPU cores (ncpu, default 0) covers both T1’s similarity search and T2’s distance enumeration. At 0 each stage chooses for itself: T2 sizes its worker pools from the CPU quota the worker runs under, T1 from the host’s core count.

Step 3: HTML report

Field	Default	Description
Generate HTML Report	true	Emit report.html (T4). Note this defaults on here, unlike the Clustering pipeline. It reuses this page’s metric, transform, pt_key, and hc_key rather than the Clustering pipeline’s separate html_* fields

Step 4: Feature selection (T5)

Field	Default	Description
Count Metric	UMIs	Count column to weight clusters by: UMIs, Reads, or Clones (Clones weights every clonotype equally). Drives output filenames and the T6 column tag
Transformation	norm	norm (relative abundance) or clr (centered log-ratio, compositional)
Pre-Transform Cluster Filter	2	Keep clusters present in ≥ N subjects. An integer is a subject count; a fraction 0 < f < 1 means ≥ f × n_subjects
Enable Wilcoxon Filter	true	Run the differential-abundance filter that selects features for T6
Wilcoxon Confidence	0.9	Confidence level — the p-value cutoff is 1 − conf, so 0.9 keeps clusters with p ≤ 0.1
Responder (Group 2) Substring	_1	Substring identifying responder columns in lngs_trees.tsv
Non-Responder (Group 1) Substring	_0	Substring identifying non-responder columns
CLR Reference Sample Substring	—	Optional reference-sample substring for the CLR scatter plots

Caution

pt_key / hc_key are substring matches against column names, not metadata lookups. Column names are built by appending each subject’s response value to its subject name, so the defaults _1 / _0 only work if your response column literally contains 1 and 0. With responder / non-responder, set pt_key to something that matches responders without also matching non-responders — _responder is a substring of _non-responder, so it matches both. Validation only checks that the two differ and are non-empty; a silently wrong match produces a meaningless classifier rather than an error.

Step 5: Classification (T6)

Field	Default	Description
LOO Per-Fold Confidence	0.75	Per-fold Wilcoxon threshold (p ≤ 1 − loo_conf), applied inside each LOOCV fold so the held-out sample never influences feature selection
LOO Parallel Jobs	0	Parallel R workers for the per-fold filter. 0 = auto, clamped to min(4, cpu/2)
Group 1 Label	non_responder	Human-readable label for the hc_key group
Group 2 Label	responder	Human-readable label for the pt_key group

The classifier itself is not configurable: a linear-kernel SVC with probability=True and a fixed random seed, one model per leave-one-out fold. There is no kernel, class-weight, or fold-count choice.

Step 6: Review & submit

Review all parameters and submit. Cleanup Temporary Files (default true) removes the run’s temp directory after upload.

---

Output files

results.zip holds the full T1–T6 output tree, so everything the Clustering pipeline produces is in there too. The stratification-specific files live under a <metric>_<transform>/ subdirectory of the hierarchical output directory — e.g. UMIs_norm/ for the defaults. In the filenames below, <pfx> is lngs_trees-<metric><transform> (e.g. lngs_trees-UMIsnorm).

T5 — feature selection, in <metric>_<transform>/:

File	Description
<pfx>_heatmap.tsv	Cluster × subject abundance matrix after the transform — the T6 input
<pfx>_heatmap.pdf	Heatmap of that matrix
<pfx>_heatmap-filtered.tsv	Same matrix restricted to Wilcoxon-significant clusters (only with Enable Wilcoxon Filter)
<pfx>_heatmap-matrix.tsv	Row/column-ordered matrix backing the heatmap figure
<pfx>_volcano.tsv	Per-cluster log2FC, neg_log10_p, nsubjects, and a PT/HC/NS direction call
<pfx>_volcano.pdf	Volcano plot of the above

T6 — LOOCV classification, in <metric>_<transform>/LOO/:

File	Description
LOO_pipeline-metrics.tsv	One row: ROC_AUC, PR_AUC, Sensitivity, Specificity, TP, FP, TN, FN
LOO_pipeline-ROC_values.csv	Bootstrapped ROC points for replotting
LOO_pipeline-AUC.pdf	ROC curve
LOO_pipeline-PR.pdf	Precision-recall curve
LOO_pipeline-features.pdf	Feature-selection frequency across folds
LOO_<n>.tsv, LOO_<n>-filtered.tsv, LOO_<n>-feature.tsv	Per-fold tables, one set per subject

Uploaded separately to the same run prefix (not inside results.zip):

File	Description
report.html	Interactive cluster report — when Generate HTML Report is enabled

---

Interpreting results

LOO_pipeline-metrics.tsv — a single row summarizing every fold pooled together:

ROC_AUC	PR_AUC	Sensitivity	Specificity	TP	FP	TN	FN
0.84	0.79	0.80	0.73	12	4	11	3

Sensitivity and specificity come from thresholding each held-out prediction at 0.5; the two AUCs use the continuous probabilities. Because this is leave-one-out, every subject contributes exactly one prediction, so TP + FP + TN + FN equals your cohort size.

<pfx>_volcano.tsv — one row per cluster, the readout for “which clusters differ between arms”:

column	meaning
log2FC	Log2 fold-change between the pt_key and hc_key groups
neg_log10_p	−log₁₀ of the Wilcoxon p-value
nsubjects	Subjects the cluster appears in
direction	PT (up in group 2), HC (up in group 1), or NS

---

Troubleshooting

T0 fails: missing response column
Add the response column to your cohort TSV. Validation rejects null/empty values and cohorts with fewer than 2 subjects, but does not check that the values are binary — keep them consistent (only 0/1, or only responder/non-responder) or the classifier is meaningless.

T0 fails: pt_key and hc_key must differ
The two substrings are identical. They must also each contain at least one alphanumeric character or underscore.

T5 fails: 0 significant clusters at conf
The Wilcoxon filter selected nothing, so T6 would have no features to train on. Lower Wilcoxon Confidence (0.9 → 0.8 raises the p-value cutoff from 0.1 to 0.2), lower the Pre-Transform Cluster Filter so more clusters survive into the test, or disable Enable Wilcoxon Filter entirely.

T5 fails: R packages not found
This is an environment fault on the compute worker, not something your cohort sheet or parameters caused — re-submitting will fail the same way. Report it to your administrator.

T6 fails: expected N LOO_*-feature.tsv files, got M
One or more folds did not complete. Check the T6 logs for per-fold R failures.

T6 gives AUC close to 0.5
Either the selected features don’t separate the response groups, or pt_key/hc_key aren’t matching the columns you think they are — confirm the group assignment first, since a bad substring match silently mislabels subjects. Otherwise try raising Pre-Transform Cluster Filter to drop clusters seen in few subjects, or tightening Wilcoxon Confidence to reduce noise features.

Warning: folds had zero significant features
Some folds selected nothing at LOO Per-Fold Confidence and trained a degraded SVM. This is logged, not fatal. Lower loo_conf if it affects many folds.