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/clones.py ADDED
@@ -0,0 +1,653 @@
1
+ """B-cell clones: clone-level summaries (and a deprecated heavy-chain-only caller).
2
+
3
+ .. deprecated::
4
+ Clone definition in Threadfin is Dandelion's paired heavy + light definition —
5
+ :func:`threadfin.define_clones_dandelion`. The internal :func:`define_clones`
6
+ below groups cells by the heavy chain alone and is kept only for backward
7
+ compatibility with old analyses.
8
+
9
+ Clone definition (:func:`define_clones`) follows the established rules for
10
+ B-cell receptors (Gupta et al. 2017; Nouri & Kleinstein 2018):
11
+
12
+ * cells are compared **only within a donor** - two people never share a clone,
13
+ so identical sequences from different donors are convergent, not clonal;
14
+ * candidate relatives must use the same IGHV gene, the same IGHJ gene and a
15
+ junction of the same length (somatic hypermutation rarely changes length);
16
+ * sequences closer than a normalised Hamming-distance threshold are joined by
17
+ single linkage. With ``threshold="auto"`` the threshold is the valley of the
18
+ bimodal distance-to-nearest distribution (the "density" method of SHazaM);
19
+ * optionally, heavy-chain clones are split by light chain.
20
+
21
+ Unlike exact clonotypes, this merges the hypermutated variants of one
22
+ germinal-centre lineage into a single clone.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ import warnings
28
+
29
+ import numpy as np
30
+ import pandas as pd
31
+
32
+ from ._utils import log
33
+
34
+ _ISOTYPES = ("IGHM", "IGHD", "IGHG", "IGHA", "IGHE")
35
+
36
+
37
+ # =========================================================================== clone definition
38
+
39
+
40
+ def _gene_call(x) -> str | None:
41
+ """First call of a (possibly multi-call) V/J assignment, without allele."""
42
+ if x is None or (isinstance(x, float) and np.isnan(x)) or x is pd.NA:
43
+ return None
44
+ s = str(x).split(",")[0].split("*")[0].strip()
45
+ return s or None
46
+
47
+
48
+ def _encode(seqs) -> np.ndarray:
49
+ """Equal-length strings -> uint8 matrix."""
50
+ return np.frombuffer("".join(seqs).encode("ascii", "replace"), dtype=np.uint8).reshape(len(seqs), -1)
51
+
52
+
53
+ def _hamming_rows(codes: np.ndarray, rows: np.ndarray) -> np.ndarray:
54
+ """Normalised Hamming distances between ``rows`` and all sequences."""
55
+ return (codes[rows][:, None, :] != codes[None, :, :]).mean(axis=2)
56
+
57
+
58
+ def _chunk_rows(codes: np.ndarray, budget: float = 2e8) -> int:
59
+ """Rows per chunk so that one (chunk x n x length) comparison stays ~200 MB."""
60
+ n, length = codes.shape
61
+ return int(max(8, min(4096, budget // max(n * length, 1))))
62
+
63
+
64
+ def _distance_to_nearest(codes: np.ndarray) -> np.ndarray:
65
+ """Distance of every (unique) sequence to its nearest other sequence."""
66
+ n = codes.shape[0]
67
+ out = np.full(n, np.nan)
68
+ if n < 2:
69
+ return out
70
+ chunk = _chunk_rows(codes)
71
+ for start in range(0, n, chunk):
72
+ rows = np.arange(start, min(start + chunk, n))
73
+ d = _hamming_rows(codes, rows)
74
+ d[np.arange(rows.size), rows] = np.inf
75
+ out[rows] = d.min(axis=1)
76
+ return out
77
+
78
+
79
+ def _linkage_edges(codes: np.ndarray, threshold: float):
80
+ """Pairs (i < j) with normalised Hamming distance <= threshold."""
81
+ n = codes.shape[0]
82
+ chunk = _chunk_rows(codes)
83
+ src, dst = [], []
84
+ for start in range(0, n, chunk):
85
+ rows = np.arange(start, min(start + chunk, n))
86
+ d = _hamming_rows(codes, rows)
87
+ i, j = np.nonzero(d <= threshold + 1e-12)
88
+ i = rows[i]
89
+ keep = i < j
90
+ src.append(i[keep])
91
+ dst.append(j[keep])
92
+ return np.concatenate(src), np.concatenate(dst)
93
+
94
+
95
+ def find_threshold(distances, *, default: float = 0.15, lo: float = 0.02, hi: float = 0.25,
96
+ max_first_mode: float = 0.12) -> dict:
97
+ """Threshold at the density valley of a distance-to-nearest distribution.
98
+
99
+ Clonally related sequences sit close to their nearest relative, unrelated
100
+ sequences far away, so the distance-to-nearest distribution is bimodal;
101
+ the valley between the modes separates them. The first ("related") mode
102
+ must lie below ``max_first_mode`` and the valley inside ``[lo, hi]``;
103
+ otherwise (for example in repertoires dominated by unmutated naive B
104
+ cells, where no clean related mode exists) ``default`` is returned. The
105
+ upper bound follows common practice for nucleotide junction distances
106
+ (thresholds of roughly 0.05-0.20; Gupta et al. 2017).
107
+ """
108
+ from scipy.stats import gaussian_kde
109
+
110
+ d = np.asarray(distances, dtype=float)
111
+ d = d[np.isfinite(d)]
112
+ info = {"threshold": default, "method": "default", "n": int(d.size)}
113
+ if d.size < 50 or np.ptp(d) == 0:
114
+ return info
115
+ grid = np.linspace(0.0, max(0.6, float(np.quantile(d, 0.99))), 601)
116
+ dens = gaussian_kde(d)(grid)
117
+ peaks = np.flatnonzero((dens[1:-1] > dens[:-2]) & (dens[1:-1] >= dens[2:])) + 1
118
+ first = peaks[grid[peaks] <= max_first_mode]
119
+ if first.size:
120
+ p1 = first[np.argmax(dens[first])]
121
+ later = peaks[peaks > p1]
122
+ if later.size:
123
+ p2 = later[np.argmax(dens[later])]
124
+ valley = p1 + int(np.argmin(dens[p1:p2 + 1]))
125
+ if lo <= grid[valley] <= hi:
126
+ info.update(threshold=float(grid[valley]), method="density")
127
+ return info
128
+
129
+
130
+ def define_clones(
131
+ bcr: pd.DataFrame,
132
+ *,
133
+ donor_key: str | None = "donor",
134
+ v_col: str = "v_call",
135
+ j_col: str = "j_call",
136
+ junction_col: str | None = None,
137
+ threshold: float | str = "auto",
138
+ light_chain: bool = False,
139
+ light_v_col: str = "v_call_light",
140
+ light_j_col: str = "j_call_light",
141
+ light_junction_col: str | None = None,
142
+ out_col: str = "clone_id",
143
+ verbose: bool = True,
144
+ ) -> pd.DataFrame:
145
+ """Group cells into B-cell clones (lineages) from their receptor sequences.
146
+
147
+ A clone is the family of cells descended from one V(D)J recombination.
148
+ B cells hypermutate their receptor, so relatives are joined when their
149
+ junctions are similar enough (single linkage below ``threshold``).
150
+
151
+ Parameters
152
+ ----------
153
+ bcr
154
+ Per-cell table (one row per cell, e.g. from :func:`threadfin.read_bcr`)
155
+ with V gene, J gene and junction (or CDR3) sequence of the heavy chain.
156
+ donor_key
157
+ Column identifying the individual. Clones are never formed across
158
+ donors. ``None`` treats all cells as one donor.
159
+ junction_col
160
+ Heavy-chain junction/CDR3 column. Default: the first available of
161
+ ``junction``, ``cdr3_nt`` (nucleotides, preferred) and
162
+ ``junction_aa``, ``cdr3`` (amino acids).
163
+ threshold
164
+ Maximum normalised Hamming distance for single linkage, or ``"auto"``
165
+ (density valley, :func:`find_threshold`; defaults 0.15 for
166
+ nucleotides and 0.20 for amino acids if no valley is found).
167
+ light_chain
168
+ Split heavy-chain clones whose cells carry different light chains
169
+ (light V gene, light J gene and junction length). Cells without a
170
+ light chain join the clone's most common light-chain group.
171
+ out_col
172
+ Name of the new clone-id column. Ids look like ``"<donor>|C00001"``,
173
+ numbered by decreasing size within each donor.
174
+
175
+ Returns
176
+ -------
177
+ Copy of ``bcr`` with ``out_col`` (NaN where V, J or junction is
178
+ missing). ``.attrs['clone_definition']`` records the threshold, the
179
+ sequence type and the number of clones.
180
+
181
+ .. deprecated::
182
+ This heavy-chain-only caller is superseded by Dandelion's paired
183
+ heavy + light clone definition (:func:`threadfin.define_clones_dandelion`),
184
+ which is Threadfin's clone definition.
185
+ """
186
+ warnings.warn(
187
+ "threadfin.define_clones (heavy-chain-only) is deprecated and will be removed; "
188
+ "Threadfin's clone definition is Dandelion's paired heavy + light definition — "
189
+ "use threadfin.define_clones_dandelion.",
190
+ DeprecationWarning, stacklevel=2,
191
+ )
192
+ from scipy.sparse import coo_matrix
193
+ from scipy.sparse.csgraph import connected_components
194
+
195
+ if not bcr.index.is_unique:
196
+ raise ValueError("bcr must contain one row per cell with unique barcodes.")
197
+ if donor_key is not None:
198
+ if donor_key not in bcr:
199
+ raise KeyError(f"Missing donor column: {donor_key}")
200
+ donor_values = bcr[donor_key]
201
+ if (donor_values.isna() | donor_values.astype("string").str.strip().eq("").fillna(False)).any():
202
+ raise ValueError("Every BCR cell needs a non-missing donor label; clones cannot pool unknown donors.")
203
+ if threshold != "auto" and (not np.isfinite(float(threshold)) or not 0 <= float(threshold) <= 1):
204
+ raise ValueError("threshold must be 'auto' or a finite number between 0 and 1.")
205
+ out = bcr.copy()
206
+ if junction_col is None:
207
+ junction_col = next((c for c in ("junction", "cdr3_nt", "junction_aa", "cdr3") if c in out.columns), None)
208
+ for col in (v_col, j_col, junction_col):
209
+ if col is None or col not in out.columns:
210
+ raise KeyError(f"define_clones needs a '{col}' column (V gene, J gene, junction).")
211
+ seq_type = "nt" if junction_col in ("junction", "cdr3_nt") else "aa"
212
+ default = 0.15 if seq_type == "nt" else 0.20
213
+
214
+ donor = out[donor_key].astype(str) if donor_key is not None else pd.Series("all", index=out.index)
215
+ junction = out[junction_col].astype("object").where(out[junction_col].notna())
216
+ junction = junction.map(lambda s: str(s).strip().upper() if isinstance(s, str) and s.strip() else None)
217
+ work = pd.DataFrame({
218
+ "donor": donor, "v": out[v_col].map(_gene_call), "j": out[j_col].map(_gene_call), "seq": junction,
219
+ }, index=out.index).dropna()
220
+ work["len"] = work["seq"].str.len()
221
+
222
+ # unique sequences per partition (donor, V, J, junction length)
223
+ uniq = work.drop_duplicates(["donor", "v", "j", "len", "seq"]).reset_index(drop=True)
224
+ parts = uniq.groupby(["donor", "v", "j", "len"], sort=False).indices
225
+
226
+ # 1) threshold
227
+ if threshold == "auto":
228
+ dtn = np.full(len(uniq), np.nan)
229
+ for idx in parts.values():
230
+ if idx.size >= 2:
231
+ dtn[idx] = _distance_to_nearest(_encode(uniq.loc[idx, "seq"].tolist()))
232
+ info = find_threshold(dtn, default=default)
233
+ if info["method"] == "default":
234
+ warnings.warn(
235
+ f"No bimodal distance-to-nearest distribution found; using the default "
236
+ f"threshold {default} ({seq_type}).", stacklevel=2,
237
+ )
238
+ thr = info["threshold"]
239
+ else:
240
+ thr, info = float(threshold), {"threshold": float(threshold), "method": "user", "n": None}
241
+
242
+ # 2) single linkage within each partition
243
+ group = np.empty(len(uniq), dtype=np.int64)
244
+ next_id = 0
245
+ for idx in parts.values():
246
+ if idx.size == 1:
247
+ group[idx] = next_id
248
+ next_id += 1
249
+ continue
250
+ src, dst = _linkage_edges(_encode(uniq.loc[idx, "seq"].tolist()), thr)
251
+ adj = coo_matrix((np.ones(src.size), (src, dst)), shape=(idx.size, idx.size))
252
+ n_comp, lab = connected_components(adj, directed=False)
253
+ group[idx] = next_id + lab
254
+ next_id += n_comp
255
+ uniq["group"] = group
256
+ key = ["donor", "v", "j", "len", "seq"]
257
+ work = work.merge(uniq[key + ["group"]], on=key, how="left").set_index(work.index)
258
+
259
+ # 3) optional light-chain split
260
+ if light_chain:
261
+ work["group"] = _split_by_light(out, work, light_v_col, light_j_col, light_junction_col)
262
+
263
+ # 4) readable ids, numbered by size within donor
264
+ sizes = work.groupby(["donor", "group"]).size().rename("n").reset_index()
265
+ sizes = sizes.sort_values(["donor", "n", "group"], ascending=[True, False, True])
266
+ sizes["rank"] = sizes.groupby("donor").cumcount() + 1
267
+ sizes["clone"] = sizes["donor"] + "|C" + sizes["rank"].astype(str).str.zfill(5)
268
+ lut = sizes.set_index(["donor", "group"])["clone"]
269
+ labels = pd.Series(lut.reindex(pd.MultiIndex.from_arrays([work["donor"], work["group"]])).to_numpy(),
270
+ index=work.index)
271
+ out[out_col] = labels.reindex(out.index)
272
+
273
+ n_clones = int(labels.nunique())
274
+ expanded = int((labels.value_counts() >= 2).sum())
275
+ out.attrs["clone_definition"] = {
276
+ "threshold": thr, "threshold_method": info["method"], "sequence": seq_type,
277
+ "junction_col": junction_col, "donor_key": donor_key, "light_chain": light_chain,
278
+ "n_cells": int(labels.notna().sum()), "n_clones": n_clones, "n_expanded": expanded,
279
+ }
280
+ log(f"define_clones: {labels.notna().sum()} cells -> {n_clones} clones ({expanded} with >= 2 "
281
+ f"cells); {seq_type} Hamming threshold {thr:.3f} ({info['method']}).", verbose)
282
+ return out
283
+
284
+
285
+ def _split_by_light(bcr, work, v_col, j_col, junction_col):
286
+ """Sub-split heavy-chain groups by light chain (V, J, junction length)."""
287
+ if junction_col is None:
288
+ junction_col = next((c for c in ("junction_light", "cdr3_nt_light", "cdr3_light") if c in bcr.columns), None)
289
+ if v_col not in bcr.columns or junction_col is None:
290
+ raise KeyError("light_chain=True needs light-chain V and junction columns.")
291
+ light = pd.Series(
292
+ bcr.loc[work.index, v_col].map(_gene_call).astype(str) + "|"
293
+ + (bcr.loc[work.index, j_col].map(_gene_call).astype(str) if j_col in bcr.columns else "")
294
+ + "|" + bcr.loc[work.index, junction_col].astype("object").map(
295
+ lambda s: str(len(s)) if isinstance(s, str) else None).astype(str),
296
+ index=work.index,
297
+ )
298
+ has_light = bcr.loc[work.index, v_col].notna() & bcr.loc[work.index, junction_col].notna()
299
+ new = work["group"].astype(str).copy()
300
+ for grp, cells in work.groupby("group").groups.items():
301
+ lc = light.loc[cells][has_light.loc[cells]]
302
+ if lc.nunique() <= 1:
303
+ continue
304
+ top = lc.value_counts().index[0]
305
+ sub = light.loc[cells].where(has_light.loc[cells], top)
306
+ codes_ = {lab: k for k, lab in enumerate(sub.value_counts().index)}
307
+ new.loc[cells] = [f"{grp}_L{codes_[s]}" for s in sub]
308
+ return pd.factorize(new)[0]
309
+
310
+
311
+ SKIP_BASES = np.frombuffer(b"-.N", dtype=np.uint8)
312
+
313
+
314
+ def _encode_seq(s: str) -> np.ndarray:
315
+ return np.frombuffer(s.upper().encode("ascii", "replace"), dtype=np.uint8)
316
+
317
+
318
+ def _mismatch_rate(a: np.ndarray, b: np.ndarray) -> tuple[int, int]:
319
+ m = min(a.size, b.size)
320
+ a, b = a[:m], b[:m]
321
+ ok = ~(np.isin(a, SKIP_BASES) | np.isin(b, SKIP_BASES))
322
+ return int((a[ok] != b[ok]).sum()), int(ok.sum())
323
+
324
+
325
+ def _best_start(needle: str, haystack: str, max_offset: int, probe: int) -> tuple[int, float]:
326
+ """Offset in ``haystack`` where ``needle`` best matches, and that mismatch rate."""
327
+ a = _encode_seq(needle[:probe])
328
+ if a.size == 0 or len(haystack) < a.size:
329
+ return 0, 1.0
330
+ b = _encode_seq(haystack[: a.size + max_offset])
331
+ if b.size < a.size:
332
+ return 0, 1.0
333
+ from numpy.lib.stride_tricks import sliding_window_view
334
+
335
+ ok = ~np.isin(a, SKIP_BASES)
336
+ if not ok.any():
337
+ return 0, 1.0
338
+ counts = (sliding_window_view(b, a.size)[:, ok] != a[ok]).sum(axis=1)
339
+ i = int(np.argmin(counts))
340
+ return i, float(counts[i] / ok.sum())
341
+
342
+
343
+ def align_starts(sequence: str, germline: str, *, max_offset: int = 400, probe: int = 200) -> tuple[int, int]:
344
+ """Where the V region starts in the query and in the germline string.
345
+
346
+ AIRR files should give both in one coordinate system, but pipelines
347
+ differ in how much upstream sequence (5' UTR, leader) each string
348
+ carries, and the AIRR coordinate columns refer to the raw read rather
349
+ than to these alignment strings. The start of one string is therefore
350
+ located inside the other, in whichever direction matches better; the
351
+ result is ``(0, 0)`` for files that already agree.
352
+ """
353
+ g_in_s, rate_a = _best_start(germline, sequence, max_offset, probe) # germline starts later in the query
354
+ s_in_g, rate_b = _best_start(sequence, germline, max_offset, probe) # query starts later in the germline
355
+ return (g_in_s, 0) if rate_a <= rate_b else (0, s_in_g)
356
+
357
+
358
+ def v_region_windows(airr: pd.DataFrame, sequence_col: str, germline_col: str, *, align: str = "auto",
359
+ max_offset: int = 400) -> pd.DataFrame:
360
+ """Where the V segment sits in the query and germline strings, for every row.
361
+
362
+ Starts come from :func:`align_starts` (``align="auto"``) or are both 0
363
+ (``align="none"``, the AIRR standard). The length is the V length from
364
+ ``v_sequence_start`` / ``v_sequence_end`` when available, so the junction
365
+ - whose N additions have no germline to compare with - is excluded.
366
+
367
+ Returns 0-based ``query_start``, ``germline_start`` and ``length``
368
+ (NaN where the V region cannot be located).
369
+ """
370
+ def col(name):
371
+ return airr[name] if name in airr.columns else None
372
+
373
+ qs, qe = col("v_sequence_start"), col("v_sequence_end")
374
+ seq, germ = airr[sequence_col].to_numpy(), airr[germline_col].to_numpy()
375
+ out = np.full((len(airr), 3), np.nan)
376
+ for k in range(len(airr)):
377
+ s_, g_ = seq[k], germ[k]
378
+ if not (isinstance(s_, str) and isinstance(g_, str)) or not s_ or not g_:
379
+ continue
380
+ q0, g0 = align_starts(s_, g_, max_offset=max_offset) if align == "auto" else (0, 0)
381
+ if qs is not None and qe is not None and pd.notna(qs.iloc[k]) and pd.notna(qe.iloc[k]):
382
+ n = int(qe.iloc[k]) - int(qs.iloc[k]) + 1 # V length, not an offset
383
+ else:
384
+ n = min(len(s_) - q0, len(g_) - g0)
385
+ n = int(min(n, len(s_) - q0, len(g_) - g0))
386
+ if n > 0:
387
+ out[k] = (q0, g0, n)
388
+ return pd.DataFrame(out, index=airr.index, columns=["query_start", "germline_start", "length"])
389
+
390
+
391
+ def mutation_frequency(
392
+ airr: pd.DataFrame,
393
+ *,
394
+ sequence_col: str = "sequence_alignment",
395
+ germline_col: str = "germline_alignment",
396
+ align: str = "auto",
397
+ ) -> pd.Series:
398
+ """V-region somatic mutation frequency from AIRR alignments.
399
+
400
+ Counts substitutions between the query and its germline over the V
401
+ segment (:func:`v_region_windows`), ignoring gaps (``-``, ``.``) and
402
+ ambiguous ``N``; returns mismatches / compared positions per row (NaN
403
+ when the V region cannot be located).
404
+
405
+ With ``align="auto"`` (the default) the two strings are first put in a
406
+ common coordinate system, because pipelines differ in how much upstream
407
+ sequence each carries; without this, cells of such a dataset all look
408
+ hypermutated. ``align="none"`` compares them from their starts, as the
409
+ AIRR standard specifies. Insertions and deletions are not modelled, so a
410
+ clone with an indel in its V region can look more mutated than it is.
411
+ The windows used are reported in ``.attrs['windows']``.
412
+ """
413
+ if sequence_col not in airr.columns or germline_col not in airr.columns:
414
+ raise KeyError(f"mutation_frequency needs '{sequence_col}' and '{germline_col}'.")
415
+ if align not in ("auto", "none"):
416
+ raise ValueError("align must be 'auto' or 'none'.")
417
+ seq, germ = airr[sequence_col].to_numpy(), airr[germline_col].to_numpy()
418
+ win = v_region_windows(airr, sequence_col, germline_col, align=align, max_offset=400)
419
+ out = np.full(len(airr), np.nan)
420
+ for k in range(len(airr)):
421
+ s_, g_ = seq[k], germ[k]
422
+ q0, g0, n = win.iloc[k]
423
+ if not (isinstance(s_, str) and isinstance(g_, str)) or not np.isfinite(n):
424
+ continue
425
+ q0, g0, n = int(q0), int(g0), int(n)
426
+ mism, compared = _mismatch_rate(_encode_seq(s_[q0:q0 + n]), _encode_seq(g_[g0:g0 + n]))
427
+ if compared > 0:
428
+ out[k] = mism / compared
429
+ res = pd.Series(out, index=airr.index, name="mutation_frequency")
430
+ res.attrs["windows"] = win
431
+ return res
432
+
433
+
434
+ # =========================================================================== summaries
435
+
436
+
437
+ def _isotype_class(c_call):
438
+ """First call before ',' collapsed to the heavy-chain class (IGHG1 -> IGHG)."""
439
+ if c_call is None or (isinstance(c_call, float) and np.isnan(c_call)) or c_call is pd.NA:
440
+ return None
441
+ first = str(c_call).split(",")[0].strip()
442
+ for cls in _ISOTYPES:
443
+ if first.upper().startswith(cls):
444
+ return cls
445
+ return first or None
446
+
447
+
448
+ def isotype_class(values) -> pd.Series:
449
+ """Collapse constant-region calls (``IGHG1``, ``Ighg2c``) to classes (``IGHG``)."""
450
+ return pd.Series(values).map(_isotype_class)
451
+
452
+
453
+ def clone_isotype_summary(adata, *, cluster_key: str | None = "clone_cluster") -> pd.DataFrame:
454
+ """Per-group heavy-chain isotype composition.
455
+
456
+ Fractions are over cells with a non-missing ``bcr_c_call`` in the group.
457
+ With ``cluster_key=None`` the summary is per ``clone_id`` instead.
458
+
459
+ Returns
460
+ -------
461
+ Tidy DataFrame with columns ``[group, isotype, fraction, n_cells]``.
462
+ """
463
+ if "bcr_c_call" not in adata.obs.columns:
464
+ raise KeyError("'bcr_c_call' not found in adata.obs. Attach BCR annotations first.")
465
+ group_col = cluster_key if cluster_key is not None else "clone_id"
466
+ if group_col not in adata.obs.columns:
467
+ raise KeyError(f"'{group_col}' not found in adata.obs.")
468
+ df = pd.DataFrame({
469
+ "group": adata.obs[group_col].astype("string"),
470
+ "isotype": adata.obs["bcr_c_call"].map(_isotype_class),
471
+ }).dropna()
472
+ counts = df.groupby(["group", "isotype"]).size().rename("n_cells")
473
+ totals = df.groupby("group").size()
474
+ out = counts.reset_index()
475
+ out["fraction"] = out["n_cells"] / out["group"].map(totals)
476
+ out = out.rename(columns={"group": group_col})[[group_col, "isotype", "fraction", "n_cells"]]
477
+ return out.sort_values([group_col, "isotype"]).reset_index(drop=True)
478
+
479
+
480
+ def _cell_shm(adata, mut_col: str | None) -> pd.Series:
481
+ """Per-cell SHM values: ``obs[mut_col]``, else ``100 - obs['bcr_v_identity']``."""
482
+ if mut_col is not None and mut_col in adata.obs.columns:
483
+ return pd.to_numeric(adata.obs[mut_col], errors="coerce")
484
+ if "bcr_v_identity" in adata.obs.columns:
485
+ return 100.0 - pd.to_numeric(adata.obs["bcr_v_identity"], errors="coerce")
486
+ raise ValueError(
487
+ f"SHM summary needs '{mut_col}' or 'bcr_v_identity' in adata.obs "
488
+ "(an AIRR mutation count or V-gene identity column)."
489
+ )
490
+
491
+
492
+ def clone_shm_summary(adata, *, mut_col: str | None = "bcr_mu_count", cluster_key: str | None = None) -> pd.DataFrame:
493
+ """Mean/median somatic hypermutation per clone (and per cluster).
494
+
495
+ Returns
496
+ -------
497
+ Tidy DataFrame ``[level, group, shm_mean, shm_median, n_cells]``.
498
+ """
499
+ if "clone_id" not in adata.obs.columns:
500
+ raise KeyError("'clone_id' not found in adata.obs.")
501
+ df = pd.DataFrame({"clone_id": adata.obs["clone_id"], "shm": _cell_shm(adata, mut_col)})
502
+ df = df.dropna(subset=["clone_id", "shm"])
503
+
504
+ def _summarize(frame, level, name):
505
+ g = frame.groupby(name)["shm"].agg(["mean", "median", "count"])
506
+ g.columns = ["shm_mean", "shm_median", "n_cells"]
507
+ g["n_cells"] = g["n_cells"].astype(int)
508
+ g.insert(0, "group", g.index.astype(str))
509
+ g.insert(0, "level", level)
510
+ return g.reset_index(drop=True)
511
+
512
+ parts = [_summarize(df, "clone", "clone_id")]
513
+ if cluster_key is not None:
514
+ if cluster_key not in adata.obs.columns:
515
+ raise KeyError(f"'{cluster_key}' not found in adata.obs.")
516
+ dfc = df.assign(cluster=adata.obs[cluster_key]).dropna(subset=["cluster"])
517
+ parts.append(_summarize(dfc, "cluster", "cluster"))
518
+ return pd.concat(parts, ignore_index=True)
519
+
520
+
521
+ def clone_fate_table(adata, *, clone_key: str = "clone_id", time_key: str = "timepoint",
522
+ state_key: str = "state") -> pd.DataFrame:
523
+ """Cell counts per (clone, timepoint, state) for clones with >= 2 cells."""
524
+ for col in (clone_key, time_key, state_key):
525
+ if col not in adata.obs.columns:
526
+ raise KeyError(f"'{col}' not found in adata.obs.")
527
+ df = adata.obs[[clone_key, time_key, state_key]].dropna()
528
+ sizes = df.groupby(clone_key).size()
529
+ df = df[df[clone_key].isin(sizes[sizes >= 2].index)]
530
+ out = df.groupby([clone_key, time_key, state_key], observed=True).size().rename("n_cells").reset_index()
531
+ return out.sort_values([clone_key, time_key, state_key]).reset_index(drop=True)
532
+
533
+
534
+ def community_transition(adata, *, time_key: str, cluster_key: str = "clone_cluster",
535
+ clone_key: str = "clone_id") -> pd.DataFrame:
536
+ """Cluster-membership transition matrix for multi-timepoint clones.
537
+
538
+ Each clone's modal ``cluster_key`` is taken per timepoint and transitions
539
+ are counted between consecutive sorted timepoints.
540
+
541
+ .. warning::
542
+ If ``cluster_key`` is a *clone-level* label (one value per clone, as
543
+ produced by :func:`threadfin.clonotype_recluster` or
544
+ :func:`threadfin.tl.find_programmes`), every snapshot of a clone has
545
+ the same label and this matrix is diagonal by construction. Use
546
+ :func:`threadfin.tl.clonal_memory`, which profiles each time point
547
+ separately, to measure whether clones keep their state.
548
+ """
549
+ for col in (clone_key, time_key, cluster_key):
550
+ if col not in adata.obs.columns:
551
+ raise KeyError(f"'{col}' not found in adata.obs.")
552
+ df = adata.obs[[clone_key, time_key, cluster_key]].dropna()
553
+ if len(df) and df.groupby(clone_key, observed=True)[cluster_key].nunique().max() <= 1:
554
+ warnings.warn(
555
+ f"'{cluster_key}' is constant within every clone, so transitions are diagonal by "
556
+ "construction; use threadfin.tl.clonal_memory() instead.", stacklevel=2,
557
+ )
558
+ mode = df.groupby([clone_key, time_key], observed=True)[cluster_key].agg(
559
+ lambda s: s.mode().iloc[0] if len(s.mode()) else np.nan)
560
+ tab = mode.unstack(time_key)
561
+ cols = list(tab.columns)
562
+ as_num = pd.to_numeric(pd.Index(cols), errors="coerce")
563
+ if len(cols) and pd.notna(np.asarray(as_num)).all():
564
+ ordered = [cols[i] for i in np.argsort(np.asarray(as_num, dtype=float), kind="stable")]
565
+ else:
566
+ import re
567
+
568
+ m = [re.match(r"^(.*?)(\d+)$", str(c)) for c in cols]
569
+ if all(m):
570
+ ordered = [c for _, c in sorted(zip(m, cols), key=lambda t: (t[0].group(1), int(t[0].group(2))))]
571
+ else:
572
+ ordered = sorted(cols, key=str)
573
+ tab = tab[ordered]
574
+ tab = tab[tab.notna().sum(axis=1) >= 2]
575
+ counts: dict = {}
576
+ clusters: set = set()
577
+ for a, b in zip(ordered[:-1], ordered[1:]):
578
+ pair = tab[[a, b]].dropna()
579
+ for f_, t_ in zip(pair[a], pair[b]):
580
+ counts[(f_, t_)] = counts.get((f_, t_), 0) + 1
581
+ clusters.update((f_, t_))
582
+ labels = sorted(clusters, key=str)
583
+ mat = pd.DataFrame(0, index=labels, columns=labels)
584
+ for (f_, t_), n in counts.items():
585
+ mat.loc[f_, t_] = n
586
+ mat.index.name = "from_cluster"
587
+ mat.columns.name = "to_cluster"
588
+ return mat
589
+
590
+
591
+ def shm_gradient_test(adata, *, cluster_key: str = "clone_cluster", order: list | None = None,
592
+ mut_col: str | None = "bcr_mu_count") -> dict:
593
+ """Kruskal-Wallis test of somatic hypermutation across communities (cell level).
594
+
595
+ Kept for backward compatibility. Cells of one clone are not independent;
596
+ for inference use :func:`threadfin.tl.association_test` on a clone-level
597
+ SHM column, which counts clones and permutes within donors.
598
+ """
599
+ from scipy.stats import kruskal, spearmanr
600
+
601
+ if cluster_key not in adata.obs.columns:
602
+ raise KeyError(f"'{cluster_key}' not found in adata.obs.")
603
+ df = pd.DataFrame({"community": adata.obs[cluster_key], "shm": _cell_shm(adata, mut_col)}).dropna()
604
+ groups = [g["shm"].to_numpy() for _, g in df.groupby("community", observed=True)]
605
+ if len(groups) < 2:
606
+ raise ValueError(f"Need at least two communities with SHM values in '{cluster_key}'.")
607
+ stat, pval = kruskal(*groups)
608
+ medians = df.groupby("community", observed=True)["shm"].median()
609
+ rho = sp = None
610
+ if order is not None:
611
+ missing = [c for c in order if c not in medians.index]
612
+ if missing:
613
+ raise ValueError(f"order lists communities absent from '{cluster_key}': {missing}")
614
+ r = spearmanr(medians.loc[list(order)].to_numpy(), np.arange(len(order)))
615
+ rho, sp = float(r.statistic), float(r.pvalue)
616
+ return {"kruskal_H": float(stat), "kruskal_p": float(pval), "spearman_rho": rho,
617
+ "spearman_p": sp, "community_medians": medians}
618
+
619
+
620
+ def public_clone_summary(adata, *, clone_key: str = "clone_id", donor_key: str,
621
+ cluster_key: str | None = "clone_cluster") -> pd.DataFrame:
622
+ """Clone ids observed in >= 2 donors.
623
+
624
+ Note: true B-cell clones cannot be shared between people. With donor-aware
625
+ clone ids (:func:`define_clones`) this table should be empty; entries
626
+ indicate either *exact-sequence* clonotype keys (convergent "public"
627
+ receptors) or clone ids that were not namespaced by donor.
628
+ """
629
+ cols = [clone_key, donor_key]
630
+ for col in (clone_key, donor_key):
631
+ if col not in adata.obs.columns:
632
+ raise KeyError(f"'{col}' not found in adata.obs.")
633
+ if cluster_key is not None:
634
+ if cluster_key not in adata.obs.columns:
635
+ raise KeyError(f"'{cluster_key}' not found in adata.obs.")
636
+ cols.append(cluster_key)
637
+ df = adata.obs[cols].dropna()
638
+ rows = []
639
+ for clone, grp in df.groupby(clone_key, observed=True):
640
+ donors = sorted(grp[donor_key].unique(), key=str)
641
+ if len(donors) < 2:
642
+ continue
643
+ row = {clone_key: clone, "n_donors": int(len(donors)), "n_cells": int(len(grp)), "donor_list": list(donors)}
644
+ if cluster_key is not None:
645
+ freq = grp[cluster_key].value_counts(normalize=True)
646
+ row["dominant_cluster"] = freq.index[0]
647
+ row["state_purity"] = float(freq.iloc[0])
648
+ rows.append(row)
649
+ out_cols = [clone_key, "n_donors", "n_cells", "donor_list"]
650
+ if cluster_key is not None:
651
+ out_cols += ["dominant_cluster", "state_purity"]
652
+ out = pd.DataFrame(rows, columns=out_cols)
653
+ return out.sort_values(["n_donors", "n_cells"], ascending=[False, False], kind="stable").reset_index(drop=True)