threadfin 4.5.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
threadfin/api.py ADDED
@@ -0,0 +1,658 @@
1
+ """One-call entry point: :func:`run`.
2
+
3
+ ``threadfin.run`` answers three questions about a paired single-cell
4
+ RNA-seq + BCR-seq dataset, in this order:
5
+
6
+ 1. **Is cell state inherited within clones?** - the *clonal coherence*: how
7
+ much of the transcriptional variation inside each sample is explained by
8
+ which clone a cell belongs to, tested against shuffled clone labels.
9
+ 2. **Which clones behave alike?** - genetically distinct clones are grouped
10
+ into *clonal programmes* by the state bias of their cells (for example
11
+ "plasmablast-biased" or "germinal-centre-retained" clones). Every split
12
+ between programmes must pass a significance test, and every programme
13
+ gets a bootstrap stability score; if no split is significant, the clones
14
+ vary along a continuum and a single programme is reported.
15
+ 3. **Do your labels explain how clones differ?** - optional clone-level
16
+ tests against any labels you have (antigen specificity, isotype,
17
+ infection, disease group): first whether the label explains clone
18
+ profiles at all, then which programmes differ; and clonal memory across
19
+ time points.
20
+
21
+ Every step is also available on its own in :mod:`threadfin.tl`.
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ from dataclasses import dataclass, field
27
+ from pathlib import Path
28
+
29
+ import numpy as np
30
+ import pandas as pd
31
+
32
+ from ._utils import ensure_actual, log, require_complete_groups, require_obs, require_positive_int
33
+
34
+ # --------------------------------------------------------------------------- reading BCR files
35
+
36
+
37
+ def _read_airr_cells(path) -> pd.DataFrame:
38
+ """AIRR rearrangement TSV -> one row per cell (heavy + best light chain)."""
39
+ from .clones import mutation_frequency
40
+
41
+ tab = pd.read_csv(path, sep="\t", low_memory=False)
42
+ cell_col = "cell_id" if "cell_id" in tab.columns else None
43
+ if cell_col is None:
44
+ if "sequence_id" not in tab.columns:
45
+ raise ValueError(f"{path}: no 'cell_id' or 'sequence_id' column.")
46
+ tab["cell_id"] = tab["sequence_id"].astype(str).str.replace(r"_contig_\d+$", "", regex=True)
47
+ if "productive" in tab.columns:
48
+ prod = tab["productive"].astype(str).str.upper().isin(("T", "TRUE", "1"))
49
+ tab = tab[prod]
50
+ locus = tab["locus"].astype(str) if "locus" in tab.columns else tab["v_call"].astype(str).str[:3]
51
+ if {"sequence_alignment", "germline_alignment"} <= set(tab.columns):
52
+ tab["mutation_frequency"] = mutation_frequency(tab)
53
+ count_col = next((c for c in ("umi_count", "duplicate_count", "consensus_count") if c in tab.columns), None)
54
+ if count_col is not None:
55
+ tab = tab.sort_values(count_col, ascending=False, kind="mergesort")
56
+ locus = locus.reindex(tab.index) # UMI sorting changes row order; keep chain labels aligned.
57
+ keep = [c for c in ("v_call", "d_call", "j_call", "c_call", "junction", "junction_aa", "cdr3",
58
+ "cdr3_aa", "clone_id", "mutation_frequency") if c in tab.columns]
59
+ heavy = tab[locus.str.upper().eq("IGH").to_numpy()].drop_duplicates("cell_id").set_index("cell_id")[keep]
60
+ light = tab[locus.str.upper().isin(("IGK", "IGL")).to_numpy()].drop_duplicates("cell_id").set_index("cell_id")
61
+ out = heavy.copy()
62
+ for col in ("v_call", "j_call", "junction", "junction_aa", "cdr3_aa"):
63
+ if col in light.columns:
64
+ out[f"{col}_light"] = light[col].reindex(out.index)
65
+ if "cdr3" not in out.columns:
66
+ src = "cdr3_aa" if "cdr3_aa" in out.columns else ("junction_aa" if "junction_aa" in out.columns else None)
67
+ if src:
68
+ out["cdr3"] = out[src]
69
+ out.index = out.index.astype(str)
70
+ out.index.name = "barcode"
71
+ return out
72
+
73
+
74
+ def read_bcr(path, *, barcode_prefix: str = "", barcode_suffix: str = "") -> pd.DataFrame:
75
+ """Read a BCR file into one row per cell.
76
+
77
+ Accepts the two common formats and detects which one by extension:
78
+
79
+ * Cell Ranger ``filtered_contig_annotations.csv`` (``.csv`` / ``.csv.gz``);
80
+ * AIRR rearrangement table (``.tsv`` / ``.tsv.gz``), e.g. Cell Ranger's
81
+ ``airr_rearrangement.tsv`` or an Immcantation ``*_db-pass.tsv``.
82
+
83
+ The table is indexed by cell barcode (with optional prefix/suffix, to
84
+ match ``adata.obs_names`` of multi-sample objects) and contains the
85
+ heavy-chain V/D/J/C calls, junction or CDR3 sequences, light-chain
86
+ calls and, for AIRR input with alignments, ``mutation_frequency``.
87
+ """
88
+ from .io import read_10x_vdj
89
+
90
+ name = str(path).lower()
91
+ if name.endswith((".csv", ".csv.gz")):
92
+ out = read_10x_vdj(str(path))
93
+ elif name.endswith((".tsv", ".tsv.gz", ".txt", ".txt.gz")):
94
+ out = _read_airr_cells(path)
95
+ else:
96
+ raise ValueError(f"Cannot tell the BCR format of {path}; expected .csv (10x) or .tsv (AIRR).")
97
+ out.index = [f"{barcode_prefix}{b}{barcode_suffix}" for b in out.index.astype(str)]
98
+ out.index.name = "barcode"
99
+ return out
100
+
101
+
102
+ # --------------------------------------------------------------------------- result object
103
+
104
+
105
+ @dataclass
106
+ class ThreadfinResult:
107
+ """Everything :func:`run` computed. Print :meth:`summary` for a readable report."""
108
+
109
+ adata: object = field(repr=False)
110
+ coherence: dict = field(repr=False)
111
+ programmes: pd.DataFrame = field(repr=False)
112
+ clones: pd.DataFrame = field(repr=False)
113
+ composition: pd.DataFrame | None = field(default=None, repr=False)
114
+ tests: dict = field(default_factory=dict, repr=False)
115
+ profile_tests: dict = field(default_factory=dict, repr=False)
116
+ memory: dict | None = field(default=None, repr=False)
117
+ settings: dict = field(default_factory=dict, repr=False)
118
+ #: analyses that were requested but could not be run on these data, with the reason
119
+ skipped: dict = field(default_factory=dict, repr=False)
120
+
121
+ def __repr__(self) -> str:
122
+ n_prog = self.programmes.shape[0]
123
+ n_cl = int(self.clones["clone_programme"].notna().sum()) if "clone_programme" in self.clones else 0
124
+ return (f"ThreadfinResult(clonal ICC={self.coherence['icc']:.3f}, "
125
+ f"p={self.coherence['p_value']:.3g}, programmes={n_prog}, clones in programmes={n_cl})")
126
+
127
+ def summary(self) -> str:
128
+ """Plain-language summary of the results."""
129
+ from .programmes import get_programmes
130
+
131
+ ad, coh = self.adata, self.coherence
132
+ clone_key = self.settings["clone_key"]
133
+ clones = ad.obs[clone_key].dropna()
134
+ sizes = clones.value_counts()
135
+ lines = [
136
+ "Threadfin summary",
137
+ "=================",
138
+ f"Cells with a {self.settings.get('receptor') or 'clone id'}: {clones.size:,} of {ad.n_obs:,}, "
139
+ f"in {sizes.size:,} clones "
140
+ f"({int((sizes >= 3).sum()):,} clones have >= 3 cells).",
141
+ "",
142
+ "1. Does clone identity shape cell state? (clonal coherence)",
143
+ f" Clone identity explains {100 * coh['icc']:.1f}% of transcriptional variance within "
144
+ f"'{coh['strata_key']}' strata; shuffled clones explain {100 * coh['null_mean']:.1f}% "
145
+ f"(p = {coh['p_value']:.3g}, {coh['n_perm']} permutations).",
146
+ ]
147
+ prof_vc = ad.uns["threadfin"]["profiles"]["variance_components"]
148
+ from .profiles import VarianceComponents
149
+
150
+ vc = VarianceComponents(np.asarray(prof_vc["sigma2"]), np.asarray(prof_vc["tau2"]),
151
+ prof_vc["n0"], prof_vc["n_clones"], prof_vc["n_cells"],
152
+ np.zeros(len(prof_vc["tau2"])))
153
+ lines.append(f" Profiles are shrunk towards the mean, so a clone reaches reliability 0.5 at "
154
+ f"{vc.min_cells_for(0.5)} cells. No clone is filtered out on reliability.")
155
+ prog = self.programmes
156
+ lines += ["", "2. Which clones behave alike? (clonal programmes)"]
157
+ if prog.empty:
158
+ lines.append(" Not enough reliably profiled clones to define programmes in this dataset.")
159
+ elif prog.shape[0] == 1:
160
+ tests = get_programmes(ad).get("split_tests", pd.DataFrame())
161
+ p_root = f" (split test p = {tests['pvalue'].iloc[0]:.2g})" if not tests.empty else ""
162
+ lines.append(f" No distinct programmes: the {int(prog['n_clones'].sum()):,} reliable clones differ, "
163
+ f"but along a continuum rather than in separate groups{p_root}.")
164
+ else:
165
+ params = get_programmes(ad)["params"]
166
+ n_stable = int((prog["stability"] >= params["stability_threshold"]).sum())
167
+ verb = "is" if n_stable == 1 else "are"
168
+ lines.append(f" {prog.shape[0]} programmes from {int(prog['n_clones'].sum()):,} reliable clones "
169
+ f"(every split significant); {n_stable} {verb} stable "
170
+ f"(bootstrap Jaccard >= {params['stability_threshold']}).")
171
+ for name, row in (prog.iterrows() if prog.shape[0] > 1 else []):
172
+ desc = ""
173
+ if self.composition is not None and name in self.composition.index:
174
+ comp = self.composition.loc[name].sort_values(ascending=False)
175
+ desc = "; " + ", ".join(f"{k} {100 * v:.0f}%" for k, v in comp.head(2).items())
176
+ flag = "" if row["stability"] >= 0.6 else " [unstable - do not interpret]"
177
+ lines.append(f" {name}: {int(row['n_clones']):,} clones, {int(row['n_cells']):,} cells, "
178
+ f"stability {row['stability']:.2f}{desc}{flag}")
179
+ if self.profile_tests or self.tests:
180
+ lines += ["", "3. Do your labels explain how clones differ? (clone-level tests)"]
181
+ for label, r in self.profile_tests.items():
182
+ verdict = "explains" if r["p_value"] < 0.05 else "does not significantly explain"
183
+ lines.append(f" {label} {verdict} clone states: {100 * r['r2']:.1f}% of clone-profile variance "
184
+ f"vs {100 * r['null_mean']:.1f}% for shuffled labels (p = {r['p_value']:.3g}, "
185
+ f"{r['n_clones']} clones).")
186
+ if self.tests:
187
+ lines.append(" Programme differences (FDR < 0.05):")
188
+ for label, tab in self.tests.items():
189
+ sig = tab[tab["fdr"] < 0.05]
190
+ if sig.empty:
191
+ lines.append(f" {label}: no significant programme effect.")
192
+ continue
193
+ for _, r in sig.sort_values("pvalue").head(6).iterrows():
194
+ if "level" in r:
195
+ lines.append(
196
+ f" {label}: {r['programme']} {'enriched' if r['odds_ratio'] > 1 else 'depleted'} "
197
+ f"for '{r['level']}' ({100 * r['frac_in_programme']:.0f}% vs "
198
+ f"{100 * r['frac_elsewhere']:.0f}% of clones; OR {r['odds_ratio']:.2f}, FDR {r['fdr']:.2g})")
199
+ else:
200
+ lines.append(
201
+ f" {label}: {r['programme']} median {r['median_in_programme']:.3g} vs "
202
+ f"{r['median_elsewhere']:.3g} elsewhere (FDR {r['fdr']:.2g})")
203
+ if self.memory is not None:
204
+ m = self.memory
205
+ lo, hi = m["memory_index_ci"]
206
+ lines += [
207
+ "",
208
+ f"4. Do clones keep their state over '{m['time_key']}'? (clonal memory)",
209
+ f" {m['n_clones']} clones seen at >= 2 levels: memory index {m['memory_index']:.2f} "
210
+ f"[{lo:.2f}, {hi:.2f}], p = {m['p_value']:.3g} (1 = clones stay as distinct as they were, "
211
+ "0 = no more similar to their earlier self than to a random clone).",
212
+ ]
213
+ if "persistence" in m:
214
+ lines.append(f" Same programme at the next level: {100 * m['persistence']:.0f}% of clones vs "
215
+ f"{100 * m['persistence_null']:.0f}% expected for random clones.")
216
+ if self.skipped:
217
+ lines += ["", "Not run (everything above is complete):"]
218
+ lines += [f" {what}: {why}" for what, why in self.skipped.items()]
219
+ lines += ["", "Per-cell programme labels: adata.obs['clone_programme']; "
220
+ "per-clone table: result.clones."]
221
+ return "\n".join(lines)
222
+
223
+ def methods(self, clone_ids: pd.Series | None = None) -> str:
224
+ """A Methods paragraph for this analysis, with the settings and package versions that were used.
225
+
226
+ Written from the settings recorded by :func:`run`, followed by the references it cites. Check it
227
+ against your own description of the data before using it.
228
+
229
+ Parameters
230
+ ----------
231
+ clone_ids
232
+ When the clones were called before :func:`run` (``adata.obs['clone_id']`` filled from
233
+ :func:`threadfin.define_clones_dandelion`), pass the Series that call returned: its recorded
234
+ settings are then described too.
235
+ """
236
+ import platform
237
+ from importlib.metadata import PackageNotFoundError, version
238
+
239
+ from . import __version__
240
+
241
+ def ver(dist):
242
+ try:
243
+ return version(dist)
244
+ except PackageNotFoundError:
245
+ return "unknown"
246
+
247
+ def n(x):
248
+ return f"{int(x):,}"
249
+
250
+ ad, st = self.adata, self.settings
251
+ uns = ad.uns.get("threadfin", {})
252
+ refs = {"threadfin": "Threadfin (https://github.com/Reynold4k/Threadfin)"}
253
+ text = [f"Clonal analyses used Threadfin {__version__} (Python {platform.python_version()}, "
254
+ f"scanpy {ver('scanpy')}, anndata {ver('anndata')})."]
255
+
256
+ # clones
257
+ cc = st.get("clone_calling")
258
+ if cc is None and clone_ids is not None and clone_ids.attrs.get("method") == "dandelion":
259
+ cc = dict(clone_ids.attrs)
260
+ clones = ad.obs[st["clone_key"]].dropna().astype(str)
261
+ sizes = clones.value_counts()
262
+ if cc:
263
+ ident = cc.get("identity")
264
+
265
+ def identity_for(kind, default):
266
+ value = float(ident.get(kind, default)) if isinstance(ident, dict) else float(ident)
267
+ return ("identical junction amino-acid sequences" if value >= 1
268
+ else f"a junction amino-acid identity of at least {value:g}")
269
+
270
+ light = cc.get("use_light_chain", True)
271
+ receptor = st.get("receptor") or cc.get("receptor") or "BCR"
272
+ if receptor == "TCR":
273
+ chains, ident_txt, vdj = ("the beta and alpha chains" if light else "the beta chain",
274
+ identity_for("tr-ab", 1.0), "a beta (or delta) chain")
275
+ elif receptor == "BCR":
276
+ chains, ident_txt, vdj = ("the heavy and light chains" if light else "the heavy chain",
277
+ identity_for("ig", 0.85), "a heavy chain")
278
+ else:
279
+ chains = ("both chains (heavy and light; beta and alpha)" if light else "the heavy (beta) chain")
280
+ ident_txt = f"{identity_for('ig', 0.85)} for B-cell and {identity_for('tr-ab', 1.0)} for T-cell receptors"
281
+ vdj = "a heavy (beta) chain"
282
+ # run() passes its own column of donors to the clone caller; an earlier call names the user's column
283
+ donor = st.get("donor_key") if st.get("clone_calling") else cc.get("donor_key")
284
+ text.append(
285
+ f"Clones were called with Dandelion {cc.get('dandelion_version', '')} (ref. dandelion)"
286
+ + (f" within each donor ({donor!r})" if donor else "")
287
+ + f", from productive contigs, requiring the same V and J genes and junction length on {chains} and "
288
+ f"{ident_txt}" + (", after Dandelion's contig check" if cc.get("check_contigs") else "") + ". "
289
+ + (f"Cells without {vdj} were not assigned to a clone. " if cc.get("require_heavy_chain", True) else "")
290
+ + (f"Python's hash seed was fixed ({cc['python_hash_seed']}) so that clone calls are reproducible."
291
+ if cc.get("python_hash_seed") is not None else
292
+ "Python's hash seed was not fixed, so clone calls can differ slightly between sessions."))
293
+ refs["dandelion"] = ("Suo C et al. Dandelion uses the single-cell adaptive immune receptor repertoire "
294
+ "to explore lymphocyte developmental origins. Nat Biotechnol 2024;42:40-51.")
295
+ else:
296
+ text.append(f"Clone identities were taken from adata.obs['{st['clone_key']}'].")
297
+ text.append(f"{n(sizes.sum())} of {n(ad.n_obs)} cells belonged to {n(sizes.size)} clones, "
298
+ f"{n((sizes >= 2).sum())} of them with two or more cells.")
299
+
300
+ # embedding
301
+ emb = uns.get("prepare_embedding")
302
+ if emb and st.get("basis") == emb.get("key_added", "X_threadfin"):
303
+ batch = emb.get("batch_key")
304
+ text.append(
305
+ f"Counts were normalised to 10,000 per cell and log-transformed; {n(emb['n_top_genes'])} highly "
306
+ f"variable genes (Seurat flavour{f', batch-aware over {batch!r}' if batch else ''}) were selected "
307
+ + ("after excluding immunoglobulin and T-cell receptor genes, " if emb.get("exclude_receptor_genes")
308
+ else "") + f"scaled and reduced to {emb['n_comps']} principal components"
309
+ + (f", integrated over {batch!r} with Harmony (ref. harmony)" if emb.get("integrate") == "harmony"
310
+ else "") + ".")
311
+ if emb.get("integrate") == "harmony":
312
+ refs["harmony"] = ("Korsunsky I et al. Fast, sensitive and accurate integration of single-cell "
313
+ "data with Harmony. Nat Methods 2019;16:1289-1296.")
314
+ else:
315
+ text.append(f"Cell states were the coordinates of the embedding '{st.get('basis')}'.")
316
+
317
+ # clone profiles
318
+ prof = uns.get("profiles", {})
319
+ pp_ = prof.get("params", {})
320
+ ctx = pp_.get("context_key")
321
+ centring = (f"Each cell's coordinates were centred on the mean of its sampling context ({ctx!r}). " if ctx
322
+ else "")
323
+ if pp_.get("representation") == "kernel":
324
+ smooth = int(pp_.get("smooth", 0))
325
+ text.append(
326
+ centring
327
+ + (f"Each cell was averaged with its {smooth} nearest neighbours and " if smooth else "Cells were ")
328
+ + f"mapped to {pp_.get('n_features', 256)} random Fourier features of a Gaussian kernel (bandwidth "
329
+ f"{float(pp_.get('bandwidth', float('nan'))):.3g}, the median distance between cells; ref. rff); every "
330
+ f"clone with at least {pp_.get('min_cells', 2)} cells was described by the mean of its cells' "
331
+ "features (kernel mean embedding; ref. kme), shrunk towards the context average the more, the fewer "
332
+ "cells it has (best linear unbiased prediction under a random-effects model; ref. searle), and the "
333
+ f"profiles were reduced to {pp_.get('n_components', 30)} principal components.")
334
+ refs["rff"] = "Rahimi A, Recht B. Random features for large-scale kernel machines. NeurIPS 2007."
335
+ refs["kme"] = ("Muandet K, Fukumizu K, Sriperumbudur B, Schoelkopf B. Kernel mean embedding of "
336
+ "distributions: a review and beyond. Found Trends Mach Learn 2017;10:1-141.")
337
+ else:
338
+ text.append(centring + f"Every clone with at least {pp_.get('min_cells', 2)} cells was described by the "
339
+ "mean of its cells' coordinates, shrunk towards the context average the more, the fewer cells "
340
+ "it has (best linear unbiased prediction under a random-effects model; ref. searle).")
341
+ refs["searle"] = "Searle SR, Casella G, McCulloch CE. Variance Components. Wiley, 1992."
342
+
343
+ # coherence
344
+ coh = self.coherence
345
+ floor = np.isclose(coh["p_value"], 1 / (coh["n_perm"] + 1))
346
+ text.append(
347
+ "Clonal coherence was the intraclass correlation of cell states within clones (the share of variance "
348
+ "explained by clone, on unsmoothed, context-centred coordinates), tested against "
349
+ f"{n(coh['n_perm'])} permutations of clone labels"
350
+ + (f" within {coh['strata_key']!r}" if coh.get("strata_key") else "")
351
+ + f" (observed {coh['icc']:.3f}, shuffled {coh['null_mean']:.3f}, P = {coh['p_value']:.2g}"
352
+ + (", the smallest possible with this number of permutations" if floor else "") + ").")
353
+
354
+ # clone map
355
+ mp = prof.get("map_params")
356
+ if mp:
357
+ text.append(f"The clone map is a UMAP (ref. umap) of the clone profiles with n_neighbors "
358
+ f"{mp['n_neighbors']} and min_dist {mp['min_dist']:g}"
359
+ + (", chosen by Threadfin's layout search" if mp.get("chosen_by") == "tune_clone_map" else "")
360
+ + "; it is a display, and no statistic depends on it.")
361
+ refs["umap"] = ("McInnes L, Healy J, Saul N, Grossberger L. UMAP: uniform manifold approximation and "
362
+ "projection. J Open Source Softw 2018;3:861.")
363
+
364
+ # programmes
365
+ prog = uns.get("programmes")
366
+ if prog and not self.programmes.empty:
367
+ pr = prog["params"]
368
+ k = self.programmes.shape[0]
369
+ text.append(
370
+ f"Clonal programmes were Leiden communities (ref. leiden) of the {pr['n_neighbors']}-nearest-neighbour "
371
+ "graph of clone profiles"
372
+ + (" (edges weighted by the clones' reliabilities), " if pr.get("weight_by_reliability", True) else ", ")
373
+ + ("at the resolution chosen for bootstrap stability" if pr.get("auto", True)
374
+ else f"at resolution {pr['resolution']:g}")
375
+ + f"; every split was tested against a single Gaussian group (alpha {pr['alpha']:g}) and splits "
376
+ "that failed were merged; "
377
+ f"stability was the mean Jaccard overlap with the best-matching group over {pr['n_boot']} bootstrap "
378
+ "replicates (ref. hennig). "
379
+ + (f"This gave {k} programmes." if k > 1 else "No split was significant: one programme."))
380
+ refs["leiden"] = ("Traag VA, Waltman L, van Eck NJ. From Louvain to Leiden: guaranteeing well-connected "
381
+ "communities. Sci Rep 2019;9:5233.")
382
+ refs["hennig"] = ("Hennig C. Cluster-wise assessment of cluster stability. Comput Stat Data Anal "
383
+ "2007;52:258-271.")
384
+
385
+ # label tests and memory
386
+ if self.profile_tests:
387
+ r0 = next(iter(self.profile_tests.values()))
388
+ labels = ", ".join(repr(k) for k in self.profile_tests)
389
+ text.append(
390
+ f"For {labels}, the share of the variance between clone profiles explained by the clone-level label "
391
+ f"(as in PERMANOVA; ref. anderson) was tested with {n(r0.get('n_perm', 2000))} permutations of the label "
392
+ + (f"among clones of the same {r0['strata_key']!r}" if r0.get("strata_key") else "among clones")
393
+ + ".")
394
+ refs["anderson"] = ("Anderson MJ. A new method for non-parametric multivariate analysis of variance. "
395
+ "Austral Ecol 2001;26:32-46.")
396
+ if self.memory is not None:
397
+ text.append(f"Clonal memory over {self.memory['time_key']!r} compared the change of each clone's profile "
398
+ "between levels, corrected for sampling, with the distance to a random clone of the same donor.")
399
+
400
+ body = " ".join(text)
401
+ order = list(dict.fromkeys(k for k in refs if k != "threadfin"))
402
+ for i, key in enumerate(order, 1):
403
+ body = body.replace(f"ref. {key}", f"ref. {i}")
404
+ lines = [body, "", "References"] + [f"{i}. {refs[key]}" for i, key in enumerate(order, 1)]
405
+ return "\n".join(lines)
406
+
407
+ def plot(self, save: str | Path | None = None):
408
+ """Overview figure (clone map, coherence test, programme composition, stability)."""
409
+ from .plotting import overview
410
+
411
+ return overview(self.adata, state_key=self.settings.get("state_key"), save=save)
412
+
413
+
414
+ # --------------------------------------------------------------------------- the pipeline
415
+
416
+
417
+ def run(
418
+ adata,
419
+ bcr=None,
420
+ *,
421
+ donor_key: str | None = None,
422
+ sample_key: str | None = None,
423
+ batch_key: str | None = None,
424
+ state_key: str | None = None,
425
+ time_key: str | None = None,
426
+ test=None,
427
+ clone_key: str = "clone_id",
428
+ basis: str | None = None,
429
+ representation: str = "kernel",
430
+ map_n_neighbors: int | str = "auto",
431
+ map_min_dist: float | str = "auto",
432
+ n_perm: int = 200,
433
+ n_boot: int = 30,
434
+ random_state: int = 0,
435
+ n_jobs: int | None = 1,
436
+ clone_options: dict | None = None,
437
+ verbose: bool = True,
438
+ ) -> ThreadfinResult:
439
+ """Run the complete Threadfin analysis in one call.
440
+
441
+ Parameters
442
+ ----------
443
+ adata
444
+ AnnData of B cells, or T cells (one row per cell). Needs raw counts in
445
+ ``X`` (or ``layers['counts']``) unless you pass a ready-made ``basis``.
446
+ bcr
447
+ Receptor data, BCR or TCR: a path to a Cell Ranger
448
+ ``filtered_contig_annotations.csv`` or an AIRR ``.tsv``, a contig-level
449
+ DataFrame (one row per receptor chain), or a scirpy AnnData/MuData.
450
+ Clones are defined with Dandelion's paired definition (heavy + light
451
+ chain; TCR beta + alpha) within each donor
452
+ (:func:`threadfin.define_clones_dandelion`); this needs the
453
+ sc-dandelion package. Leave ``None`` if ``adata.obs[clone_key]``
454
+ already holds clone ids.
455
+ donor_key
456
+ ``obs`` column naming the individual each cell came from. Strongly
457
+ recommended: clones are defined within donors and tests are
458
+ stratified by donor.
459
+ sample_key
460
+ ``obs`` column naming the sample/library of each cell. Clones are
461
+ compared with the other cells of their own sample, and the null
462
+ model shuffles clone labels only within samples.
463
+ batch_key
464
+ Optional ``obs`` column to integrate over with Harmony when the
465
+ embedding is built (technical batches only).
466
+ state_key
467
+ Optional cell-type/state annotation, used to describe programmes.
468
+ time_key
469
+ Optional time point (or tissue) column; enables the clonal-memory test.
470
+ test
471
+ Optional list of ``obs`` columns to test against programmes at clone
472
+ level (e.g. ``["isotype", "antigen_binding"]``).
473
+ clone_key
474
+ Name of the clone-id column (created when ``bcr`` is given).
475
+ basis
476
+ Existing ``obsm`` embedding to use instead of building one. It
477
+ should exclude immunoglobulin genes (see
478
+ :func:`threadfin.pp.ig_gene_mask`).
479
+ representation
480
+ How each clone is summarised for grouping into programmes:
481
+ ``"kernel"`` (default; the whole distribution of the clone's cells,
482
+ so two clones with the same average but different spreads differ)
483
+ or ``"mean"`` (the clone centroid only). The coherence test always
484
+ uses clone means.
485
+ map_n_neighbors, map_min_dist
486
+ UMAP settings of the clone map. ``"auto"`` (default) chooses them
487
+ for this dataset by optimisation (:func:`threadfin.tl.tune_clone_map`),
488
+ so that clones that vary continuously are drawn as one connected
489
+ picture; pass numbers to set them by hand. The map is a display only:
490
+ no statistic depends on it.
491
+ n_perm, n_boot
492
+ Permutations for the coherence test; bootstrap replicates for
493
+ programme stability.
494
+ n_jobs
495
+ Processes for the two most time-consuming steps, the automatic choice
496
+ of the clone-map settings and the bootstrap of programme stability
497
+ (``-1``: all available cores). Results are identical for any value;
498
+ only the run time changes.
499
+ clone_options
500
+ Settings for calling clones from ``bcr``, passed to
501
+ :func:`threadfin.define_clones_dandelion`, e.g. ``{"identity": 0.9}`` or
502
+ ``{"check_contigs": True}`` (Dandelion's check for cells with several chains of one kind).
503
+
504
+ Returns
505
+ -------
506
+ :class:`ThreadfinResult`. Also adds ``obs[clone_key]`` (if ``bcr`` is
507
+ given), ``obs['clone_programme']`` and results under
508
+ ``adata.uns['threadfin']``.
509
+
510
+ Examples
511
+ --------
512
+ >>> import threadfin as tf
513
+ >>> result = tf.run(adata, bcr="filtered_contig_annotations.csv",
514
+ ... donor_key="donor", sample_key="sample")
515
+ >>> print(result.summary())
516
+ >>> result.plot("threadfin_overview.pdf")
517
+ """
518
+ ensure_actual(adata, verbose)
519
+ from .dynamics import clonal_memory
520
+ from .io import attach_bcr
521
+ from .pp import prepare_embedding
522
+ from .profiles import clone_profiles
523
+ from .programmes import embed_clones, find_programmes, programme_composition
524
+ from .stats import association_test, clonal_coherence, profile_association
525
+
526
+ # Check user-supplied column names before mutating ``adata`` or entering a
527
+ # downstream statistical routine. In particular, a misspelled requested
528
+ # test label must not be silently reported as a skipped analysis.
529
+ test_cols = [test] if isinstance(test, str) else list(test or [])
530
+ require_obs(adata, donor_key, sample_key, state_key, time_key, batch_key, *test_cols,
531
+ context="threadfin.run()")
532
+ require_complete_groups(adata, donor_key, sample_key, batch_key, context="threadfin.run()")
533
+ require_positive_int(n_perm, "n_perm")
534
+ require_positive_int(n_boot, "n_boot")
535
+ if representation not in {"mean", "kernel"}:
536
+ raise ValueError("representation must be 'mean' or 'kernel'.")
537
+
538
+ # Step 1 - clones from receptor sequences (within each donor).
539
+ # Threadfin's clone definition is Dandelion's paired heavy + light definition, so the
540
+ # contig-level table (one row per receptor chain) is required — a per-cell summary cannot
541
+ # recover the light-chain pairing.
542
+ if bcr is not None:
543
+ if not isinstance(bcr, (pd.DataFrame, str, Path)) and not (hasattr(bcr, "mod") or hasattr(bcr, "obsm")):
544
+ raise TypeError("bcr must be a contig-level pandas DataFrame, a path to a 10x "
545
+ "filtered_contig_annotations.csv / AIRR .tsv file, or a scirpy AnnData/MuData.")
546
+ from .dandelion import _locus, _receptor_name, define_clones_dandelion, read_contigs
547
+
548
+ contigs = read_contigs(bcr, obs_names=adata.obs_names)
549
+ contigs["cell_id"] = contigs["cell_id"].astype(str)
550
+ contigs = contigs[contigs["cell_id"].isin(adata.obs_names.astype(str))]
551
+ receptor = _receptor_name(_locus(contigs))
552
+ if contigs["cell_id"].nunique() == 0:
553
+ raise ValueError(
554
+ "No barcode of the receptor data matches adata.obs_names. Check that both use the same barcode "
555
+ "format; for multi-sample data, harmonise the barcodes first (see "
556
+ "barcode_prefix/barcode_suffix in threadfin.read_bcr())."
557
+ )
558
+ if donor_key is not None:
559
+ donor_of_cell = pd.Series(adata.obs[donor_key].astype(str).to_numpy(),
560
+ index=adata.obs_names.astype(str))
561
+ contigs["donor"] = contigs["cell_id"].map(donor_of_cell)
562
+ ids = define_clones_dandelion(contigs, cell_key="cell_id",
563
+ donor_key="donor" if donor_key else None,
564
+ out_col=clone_key, verbose=verbose, **(clone_options or {}))
565
+ clone_calling = dict(ids.attrs)
566
+ if int(ids.notna().sum()) == 0:
567
+ raise ValueError(
568
+ "Matched receptor contigs produced no clone calls. Each retained cell needs "
569
+ "heavy-chain (TCR: beta or delta) V and J calls plus a non-empty junction/CDR3 sequence."
570
+ )
571
+ if not isinstance(bcr, (str, Path)): # a DataFrame or a scirpy object: clone ids only
572
+ table = ids.rename(clone_key).to_frame()
573
+ table.index.name = "barcode"
574
+ else:
575
+ # per-cell V/J/C/SHM summary attached beside the Dandelion clone ids
576
+ table = read_bcr(bcr)
577
+ table.index = table.index.astype(str)
578
+ table = table[table.index.isin(ids.index)]
579
+ table[clone_key] = ids.reindex(table.index)
580
+ attach_bcr(adata, table, clone_col=clone_key, summarize=False, verbose=verbose)
581
+ elif clone_key not in adata.obs.columns:
582
+ raise ValueError(f"Pass `bcr`, or provide clone ids in adata.obs['{clone_key}'].")
583
+ else:
584
+ receptor, clone_calling = None, None
585
+
586
+ # Threadfin needs clones observed more than once; say so plainly instead of failing deep inside the model
587
+ sizes = adata.obs[clone_key].dropna().astype(str).value_counts()
588
+ if int((sizes >= 2).sum()) < 2:
589
+ raise ValueError(
590
+ f"Only {int((sizes >= 2).sum())} clone(s) have two or more cells ({sizes.size:,} clones, "
591
+ f"{int(sizes.sum()):,} cells with a clone id). Threadfin compares the cells within a clone, so it needs "
592
+ "clones seen at least twice. Check that the receptor barcodes match adata.obs_names (the share of cells with a "
593
+ "clone id), that clones were called within donors, and that the data contain expanded B cells.")
594
+
595
+ # Step 2 - expression embedding without immunoglobulin genes
596
+ if basis is None:
597
+ basis = "X_threadfin"
598
+ if basis not in adata.obsm:
599
+ prepare_embedding(adata, batch_key=batch_key, random_state=random_state, verbose=verbose)
600
+
601
+ # Step 3 - one profile per clone, relative to its own sample
602
+ clone_profiles(adata, clone_key=clone_key, basis=basis, context_key=sample_key,
603
+ donor_key=donor_key, representation=representation,
604
+ random_state=random_state, verbose=verbose)
605
+
606
+ # Step 4 - is clone identity informative at all?
607
+ coherence = clonal_coherence(adata, strata_key=sample_key, n_perm=n_perm,
608
+ random_state=random_state, verbose=verbose)
609
+
610
+ # Step 5 - group clones into programmes (significant splits only), with bootstrap stability
611
+ try:
612
+ # the clone map is drawn separately from programme discovery, over every profiled clone;
613
+ # find_programmes used to do it over its reliability-gated subset, which silently left some
614
+ # datasets with no map at all
615
+ embed_clones(adata, n_neighbors=map_n_neighbors, min_dist=map_min_dist,
616
+ random_state=random_state, n_jobs=n_jobs, verbose=verbose)
617
+ programmes = find_programmes(adata, n_boot=n_boot, random_state=random_state, n_jobs=n_jobs,
618
+ verbose=verbose)
619
+ except ValueError as e: # too few expanded clones: keep the coherence result
620
+ log(f"no programmes: {e}", verbose)
621
+ programmes = pd.DataFrame(columns=["n_clones", "n_cells", "mean_reliability", "mean_confidence",
622
+ "stability"])
623
+
624
+ # Step 6 - describe and test the programmes
625
+ composition = None
626
+ tests, profile_tests, skipped = {}, {}, {}
627
+ if not programmes.empty:
628
+ composition = programme_composition(adata, state_key) if state_key else None
629
+ for col in test_cols:
630
+ # does the label explain clone states at all? (needs no programmes)
631
+ try:
632
+ profile_tests[col] = profile_association(adata, col, random_state=random_state, verbose=verbose)
633
+ except ValueError as e:
634
+ skipped[f"clone-level test of '{col}'"] = str(e)
635
+ log(f"profile test '{col}' skipped: {e}", verbose)
636
+ if programmes.shape[0] >= 2: # which programmes differ? (needs >= 2 programmes)
637
+ tests[col] = association_test(adata, col, random_state=random_state, verbose=verbose)
638
+ memory = None
639
+ if time_key is not None:
640
+ # optional like the label tests: a time point or tissue column that cannot be tested (e.g. no clone seen at
641
+ # two of its levels) is reported, not allowed to discard the analysis that is already complete
642
+ try:
643
+ memory = clonal_memory(adata, time_key, random_state=random_state, verbose=verbose)
644
+ except ValueError as e:
645
+ skipped[f"clonal memory over '{time_key}'"] = str(e)
646
+ log(f"clonal memory over '{time_key}' skipped: {e}", verbose)
647
+
648
+ clones = adata.uns["threadfin"]["profiles"]["clone_table"]
649
+ result = ThreadfinResult(
650
+ adata=adata, coherence=coherence, programmes=programmes, clones=clones,
651
+ composition=composition, tests=tests, profile_tests=profile_tests, memory=memory, skipped=skipped,
652
+ settings={"clone_key": clone_key, "donor_key": donor_key, "sample_key": sample_key,
653
+ "state_key": state_key, "time_key": time_key, "basis": basis,
654
+ "representation": representation, "receptor": receptor, "clone_calling": clone_calling,
655
+ "n_perm": int(n_perm), "n_boot": int(n_boot), "random_state": int(random_state)},
656
+ )
657
+ log("done. print(result.summary()) for a readable report.", verbose)
658
+ return result