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/plotting.py ADDED
@@ -0,0 +1,535 @@
1
+ """Figures for Threadfin results (matplotlib; publication style).
2
+
3
+ Every function accepts an optional ``ax`` (or ``fig``), never calls
4
+ ``plt.show()`` and returns the figure for further editing. ``save=`` writes
5
+ the figure (PDF/SVG keep text editable).
6
+
7
+ Colour rules used throughout (validated categorical palette, fixed order):
8
+
9
+ * programmes / categories take slots 1-8 in a fixed order and never cycle;
10
+ a 9th category folds into grey "other";
11
+ * scatter plots with more than three categories are drawn as small
12
+ multiples (each category highlighted on grey), because more than three
13
+ hues cannot all be told apart when any two points may touch;
14
+ * text is always ink-coloured; colour lives on the marks only.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import matplotlib as mpl
20
+ import matplotlib.pyplot as plt
21
+ import numpy as np
22
+ import pandas as pd
23
+
24
+ __all__ = [
25
+ "set_style",
26
+ "category_colors",
27
+ "clone_map",
28
+ "coherence",
29
+ "programme_composition",
30
+ "stability",
31
+ "association",
32
+ "memory",
33
+ "label_effects",
34
+ "heritability",
35
+ "overview",
36
+ "cells",
37
+ "signature_heatmap",
38
+ ]
39
+
40
+ # validated categorical order (adjacent-pair CVD and normal-vision checks pass)
41
+ PALETTE = ["#2a78d6", "#eb6834", "#1baf7a", "#eda100", "#e87ba4", "#008300", "#4a3aa7", "#e34948"]
42
+ OTHER = "#c3c2b7"
43
+ INK = "#0b0b0b"
44
+ INK_2 = "#52514e"
45
+ MUTED = "#898781"
46
+ GRID = "#e1e0d9"
47
+ BLUE_RAMP = ["#cde2fb", "#9ec5f4", "#6da7ec", "#3987e5", "#256abf", "#184f95", "#0d366b"]
48
+ DIVERGING = ["#1c5cab", "#6da7ec", "#f0efec", "#ec8a7e", "#c03a3a"]
49
+
50
+
51
+ # --------------------------------------------------------------------------- style
52
+
53
+
54
+ def set_style(font_size: float = 7.0) -> None:
55
+ """Nature-style defaults: small sans text, hairline axes, editable PDF text."""
56
+ mpl.rcParams.update({
57
+ "font.family": "sans-serif",
58
+ "font.sans-serif": ["Arial", "Helvetica", "Liberation Sans", "DejaVu Sans"],
59
+ "font.size": font_size,
60
+ "axes.titlesize": font_size + 1,
61
+ "axes.labelsize": font_size,
62
+ "xtick.labelsize": font_size - 0.5,
63
+ "ytick.labelsize": font_size - 0.5,
64
+ "legend.fontsize": font_size - 0.5,
65
+ "axes.linewidth": 0.6,
66
+ "axes.edgecolor": INK_2,
67
+ "axes.labelcolor": INK,
68
+ "axes.spines.top": False,
69
+ "axes.spines.right": False,
70
+ "xtick.color": INK_2,
71
+ "ytick.color": INK_2,
72
+ "xtick.major.width": 0.6,
73
+ "ytick.major.width": 0.6,
74
+ "xtick.major.size": 2.5,
75
+ "ytick.major.size": 2.5,
76
+ "lines.linewidth": 1.2,
77
+ "legend.frameon": False,
78
+ "figure.dpi": 150,
79
+ "savefig.dpi": 300,
80
+ "savefig.bbox": "tight",
81
+ "pdf.fonttype": 42,
82
+ "ps.fonttype": 42,
83
+ "svg.fonttype": "none",
84
+ })
85
+
86
+
87
+ def category_colors(categories) -> dict:
88
+ """Fixed-order colours for categories; beyond eight, grey 'other'."""
89
+ cats = list(categories)
90
+ return {c: (PALETTE[i] if i < len(PALETTE) else OTHER) for i, c in enumerate(cats)}
91
+
92
+
93
+ def _finish(fig, save):
94
+ if save:
95
+ fig.savefig(save)
96
+ return fig
97
+
98
+
99
+ def _ax(ax, figsize=(3.2, 2.6)):
100
+ if ax is None:
101
+ fig, ax = plt.subplots(figsize=figsize)
102
+ return fig, ax
103
+ return ax.get_figure(), ax
104
+
105
+
106
+ def _clone_table(adata):
107
+ prof = adata.uns.get("threadfin", {}).get("profiles")
108
+ return None if prof is None else prof["clone_table"]
109
+
110
+
111
+ # --------------------------------------------------------------------------- clone map
112
+
113
+
114
+ def clone_map(
115
+ adata,
116
+ color: str | None = None,
117
+ *,
118
+ size_range: tuple = (2, 60),
119
+ facet: bool | None = None,
120
+ ncols: int = 4,
121
+ ax=None,
122
+ fig=None,
123
+ title: str | None = None,
124
+ save: str | None = None,
125
+ **legacy_kwargs,
126
+ ):
127
+ """Scatter of clones (one point per clone; size = number of cells).
128
+
129
+ With :func:`threadfin.tl.find_programmes` results, points are placed by
130
+ the UMAP of clone profiles and ``color`` defaults to ``clone_programme``.
131
+ More than three categories are drawn as small multiples (one panel per
132
+ category, highlighted on grey) unless ``facet=False``. Numeric columns use
133
+ a single-hue blue scale.
134
+
135
+ Falls back to the v3 layout (``uns['threadfin']['clone_map']`` from
136
+ :func:`threadfin.clonotype_recluster`) when no v4 clone table exists.
137
+ """
138
+ table = _clone_table(adata)
139
+ if table is None or "x" not in table.columns:
140
+ return _legacy_clone_map(adata, color=color or "clone_cluster", ax=ax, title=title, save=save,
141
+ **legacy_kwargs)
142
+ color = color or "clone_programme"
143
+ tab = table.dropna(subset=["x", "y"])
144
+ if color not in tab.columns:
145
+ raise KeyError(f"'{color}' is not a column of the clone table.")
146
+ n = tab["n_cells"].astype(float)
147
+ lo, hi = size_range
148
+ s = lo + (hi - lo) * (np.log1p(n) - np.log1p(n.min())) / max(np.log1p(n.max()) - np.log1p(n.min()), 1e-9)
149
+ order = np.argsort(n.to_numpy())[::-1] # draw big clones first, small on top
150
+ values = tab[color]
151
+ categorical = not pd.api.types.is_numeric_dtype(values) or isinstance(values.dtype, pd.CategoricalDtype)
152
+
153
+ if categorical:
154
+ cats = [c for c in pd.Categorical(values.dropna()).categories if (values == c).any()]
155
+ if facet is None:
156
+ facet = len(cats) > 3
157
+ if facet:
158
+ nrow = int(np.ceil(len(cats) / ncols))
159
+ if fig is None:
160
+ fig, axes = plt.subplots(nrow, ncols, figsize=(1.45 * ncols, 1.45 * nrow), squeeze=False)
161
+ else:
162
+ axes = np.array(fig.subplots(nrow, ncols, squeeze=False))
163
+ for k, ax_k in enumerate(axes.ravel()):
164
+ ax_k.set_xticks([]), ax_k.set_yticks([])
165
+ for sp_ in ax_k.spines.values():
166
+ sp_.set_visible(False)
167
+ if k >= len(cats):
168
+ continue
169
+ cat = cats[k]
170
+ hit = (values == cat).to_numpy()
171
+ ax_k.scatter(tab["x"].to_numpy()[order], tab["y"].to_numpy()[order], s=s.to_numpy()[order] * 0.5,
172
+ color=OTHER, alpha=0.35, linewidths=0, rasterized=True)
173
+ idx = order[hit[order]]
174
+ ax_k.scatter(tab["x"].to_numpy()[idx], tab["y"].to_numpy()[idx], s=s.to_numpy()[idx],
175
+ color=PALETTE[0], edgecolors="white", linewidths=0.3, rasterized=True)
176
+ ax_k.set_title(f"{cat} (n={int(hit.sum())})", fontsize=mpl.rcParams["font.size"], color=INK, pad=2)
177
+ if title:
178
+ fig.suptitle(title, color=INK)
179
+ return _finish(fig, save)
180
+ fig, ax = _ax(ax)
181
+ colors = category_colors(cats)
182
+ for cat in cats:
183
+ hit = (values == cat).to_numpy()
184
+ idx = order[hit[order]]
185
+ ax.scatter(tab["x"].to_numpy()[idx], tab["y"].to_numpy()[idx], s=s.to_numpy()[idx],
186
+ color=colors[cat], edgecolors="white", linewidths=0.3, label=str(cat), rasterized=True)
187
+ ax.legend(loc="center left", bbox_to_anchor=(1.0, 0.5), markerscale=1.2, handletextpad=0.3)
188
+ else:
189
+ fig, ax = _ax(ax)
190
+ cmap = mpl.colors.LinearSegmentedColormap.from_list("tf_blue", BLUE_RAMP)
191
+ sc_ = ax.scatter(tab["x"].to_numpy()[order], tab["y"].to_numpy()[order], s=s.to_numpy()[order],
192
+ c=values.astype(float).to_numpy()[order], cmap=cmap, edgecolors="white",
193
+ linewidths=0.3, rasterized=True)
194
+ fig.colorbar(sc_, ax=ax, shrink=0.7, label=color)
195
+ ax.set_xticks([]), ax.set_yticks([])
196
+ ax.set_xlabel("clone profile UMAP 1")
197
+ ax.set_ylabel("clone profile UMAP 2")
198
+ ax.set_title(title or f"{len(tab):,} clones", color=INK)
199
+ return _finish(fig, save)
200
+
201
+
202
+ def _legacy_clone_map(adata, color="clone_cluster", size_by="n_cells", size_range=(20, 400), ax=None,
203
+ palette=None, title=None, save=None):
204
+ """v3 clone map (one point per clonotype from clonotype_recluster)."""
205
+ cm = adata.uns.get("threadfin", {}).get("clone_map")
206
+ if cm is None:
207
+ raise ValueError("Run threadfin.run() / threadfin.tl.find_programmes() (or the v3 "
208
+ "clonotype_recluster) first.")
209
+ if "x" not in cm.columns:
210
+ raise ValueError("Clone map has no embedding; run clonotype_recluster(embed_clones=True).")
211
+ fig, ax = _ax(ax, figsize=(7, 6))
212
+ sizes = cm[size_by].astype(float)
213
+ lo, hi = size_range
214
+ s = ((sizes - sizes.min()) / (sizes.max() - sizes.min()) * (hi - lo) + lo
215
+ if sizes.max() > sizes.min() else np.full(len(sizes), (lo + hi) / 2))
216
+ values = cm[color]
217
+ if isinstance(values.dtype, pd.CategoricalDtype) or values.dtype == object:
218
+ cats = pd.Categorical(values)
219
+ palette = palette or category_colors(cats.categories)
220
+ for cat in cats.categories:
221
+ m = np.asarray(cats == cat)
222
+ ax.scatter(cm["x"][m], cm["y"][m], s=s[m], color=palette.get(cat, OTHER), label=str(cat),
223
+ alpha=0.85, edgecolors="white", linewidths=0.3)
224
+ ax.legend(title=color, loc="center left", bbox_to_anchor=(1.0, 0.5))
225
+ else:
226
+ sc_ = ax.scatter(cm["x"], cm["y"], s=s, c=values.astype(float), cmap="viridis", alpha=0.85,
227
+ edgecolors="white", linewidths=0.3)
228
+ plt.colorbar(sc_, ax=ax, label=color)
229
+ ax.set_xlabel("Clone UMAP 1")
230
+ ax.set_ylabel("Clone UMAP 2")
231
+ ax.set_title(title or f"Clonotype map (n={len(cm)} clones, colored by {color})")
232
+ fig.tight_layout()
233
+ if save:
234
+ fig.savefig(save, dpi=300, bbox_inches="tight")
235
+ return fig, ax
236
+
237
+
238
+ # --------------------------------------------------------------------------- statistics panels
239
+
240
+
241
+ def coherence(adata, *, ax=None, save=None):
242
+ """Observed clonal ICC next to the within-stratum permutation null.
243
+
244
+ Two bars: the share of variance explained by clone identity, and the same
245
+ statistic after shuffling clone labels within strata (whisker = 95% of
246
+ permutations). The excess of the first over the second is the clonal
247
+ signal beyond sampling.
248
+ """
249
+ res = adata.uns.get("threadfin", {}).get("coherence")
250
+ if res is None:
251
+ raise ValueError("Run threadfin.tl.clonal_coherence() first.")
252
+ fig, ax = _ax(ax, figsize=(2.2, 2.2))
253
+ null = np.asarray(res["null"]) * 100
254
+ obs = res["icc"] * 100
255
+ lo, hi = np.quantile(null, [0.025, 0.975])
256
+ ax.bar([0, 1], [obs, null.mean()], width=0.6, color=[PALETTE[0], OTHER])
257
+ ax.errorbar([1], [null.mean()], yerr=[[null.mean() - lo], [hi - null.mean()]], fmt="none",
258
+ ecolor=INK_2, elinewidth=0.8, capsize=2)
259
+ top = max(obs, hi)
260
+ for x, v in ((0, obs), (1, null.mean())):
261
+ ax.text(x, (hi if x == 1 else v) + 0.03 * top, f"{v:.1f}%", ha="center", va="bottom", color=INK)
262
+ ax.set_xticks([0, 1], ["observed", "shuffled\nwithin samples"])
263
+ ax.set_ylim(0, top * 1.25)
264
+ ax.set_ylabel("variance explained by clone (%)")
265
+ ax.set_title(f"clonal coherence (p = {res['p_value']:.2g})", color=INK)
266
+ return _finish(fig, save)
267
+
268
+
269
+ def programme_composition(adata, state_key: str, *, programme_key: str = "clone_programme",
270
+ ax=None, save=None, legend: bool = True):
271
+ """Stacked bars: fraction of each programme's cells in each cell state."""
272
+ df = adata.obs[[programme_key, state_key]].dropna()
273
+ tab = pd.crosstab(df[programme_key], df[state_key])
274
+ frac = tab.div(tab.sum(axis=1), axis=0)
275
+ states = list(frac.sum(axis=0).sort_values(ascending=False).index)
276
+ if len(states) > 8: # fold the tail into "other"
277
+ frac["other"] = frac[states[7:]].sum(axis=1)
278
+ states = states[:7] + ["other"]
279
+ frac = frac[states]
280
+ colors = category_colors(states)
281
+ if "other" in colors:
282
+ colors["other"] = OTHER
283
+ fig, ax = _ax(ax, figsize=(3.0, 0.25 * len(frac) + 0.8))
284
+ left = np.zeros(len(frac))
285
+ ypos = np.arange(len(frac))[::-1]
286
+ for st in states:
287
+ vals = frac[st].to_numpy()
288
+ ax.barh(ypos, vals, left=left, height=0.7, color=colors[st], edgecolor="white", linewidth=0.8, label=str(st))
289
+ left += vals
290
+ ax.set_yticks(ypos, [str(i) for i in frac.index])
291
+ ax.set_xlim(0, 1)
292
+ ax.set_xlabel("fraction of programme cells")
293
+ ax.spines["left"].set_visible(False)
294
+ ax.tick_params(axis="y", length=0)
295
+ if legend:
296
+ ax.legend(loc="upper left", bbox_to_anchor=(1.0, 1.0), handlelength=0.8, handletextpad=0.4)
297
+ return _finish(fig, save)
298
+
299
+
300
+ def stability(adata, *, ax=None, save=None):
301
+ """Bootstrap stability (Jaccard) of each programme, with the 0.75 / 0.6 guides."""
302
+ prog = adata.uns.get("threadfin", {}).get("programmes")
303
+ if prog is None:
304
+ raise ValueError("Run threadfin.tl.find_programmes() first.")
305
+ summ = prog["summary"]
306
+ fig, ax = _ax(ax, figsize=(2.6, 2.0))
307
+ x = np.arange(len(summ))
308
+ ax.bar(x, summ["stability"], width=0.6, color=PALETTE[0])
309
+ for thr, lab in ((prog["params"]["stability_threshold"], "stable"), (0.6, "do not interpret below")):
310
+ ax.axhline(thr, color=MUTED, linewidth=0.6)
311
+ ax.text(1.02, thr, lab, transform=ax.get_yaxis_transform(), color=INK_2, va="center", ha="left",
312
+ fontsize=mpl.rcParams["font.size"] - 1, clip_on=False)
313
+ ax.set_xticks(x, [str(i) for i in summ.index])
314
+ ax.set_xlim(-0.6, len(summ) - 0.4)
315
+ ax.set_ylim(0, 1.05)
316
+ ax.set_ylabel("bootstrap Jaccard")
317
+ ax.set_title("programme stability", color=INK)
318
+ return _finish(fig, save)
319
+
320
+
321
+ def association(table: pd.DataFrame, *, level=None, ax=None, save=None, title: str | None = None):
322
+ """Forest plot of clone-level programme effects from :func:`threadfin.tl.association_test`.
323
+
324
+ Categorical labels: Mantel-Haenszel odds ratios with 95% CIs (log scale)
325
+ for one ``level``; numeric labels: rank effects. Filled markers mark
326
+ FDR < 0.05.
327
+ """
328
+ tab = table.copy()
329
+ fig, ax = _ax(ax, figsize=(2.8, 0.22 * tab["programme"].nunique() + 0.9))
330
+ if "level" in tab.columns:
331
+ level = level if level is not None else tab.groupby("level")["n_clones_level"].first().idxmin()
332
+ tab = tab[tab["level"].astype(str) == str(level)]
333
+ y = np.arange(len(tab))[::-1]
334
+ est = tab["odds_ratio"].to_numpy(dtype=float)
335
+ lo = tab["ci_low"].to_numpy(dtype=float)
336
+ hi = tab["ci_high"].to_numpy(dtype=float)
337
+ ok = np.isfinite(est) & (est > 0)
338
+ ax.hlines(y[ok], np.where(np.isfinite(lo[ok]), lo[ok], est[ok]),
339
+ np.where(np.isfinite(hi[ok]), hi[ok], est[ok]), color=INK_2, linewidth=0.8)
340
+ sig = (tab["fdr"] < 0.05).to_numpy()
341
+ ax.scatter(est[ok & sig], y[ok & sig], color=PALETTE[0], s=18, zorder=3, edgecolors="white", linewidths=0.5)
342
+ ax.scatter(est[ok & ~sig], y[ok & ~sig], facecolor="white", edgecolor=PALETTE[0], s=18, zorder=3,
343
+ linewidths=0.8)
344
+ ax.set_xscale("log")
345
+ ax.axvline(1.0, color=MUTED, linewidth=0.6)
346
+ ax.set_xlabel(f"odds ratio (clones), '{level}'")
347
+ else:
348
+ y = np.arange(len(tab))[::-1]
349
+ eff = tab["rank_effect"].to_numpy(dtype=float)
350
+ sig = (tab["fdr"] < 0.05).to_numpy()
351
+ ax.scatter(eff[sig], y[sig], color=PALETTE[0], s=18, zorder=3)
352
+ ax.scatter(eff[~sig], y[~sig], facecolor="white", edgecolor=PALETTE[0], s=18, zorder=3, linewidths=0.8)
353
+ ax.axvline(0.0, color=MUTED, linewidth=0.6)
354
+ ax.set_xlabel("rank effect (programme vs other clones)")
355
+ ax.set_yticks(y, tab["programme"].astype(str))
356
+ ax.spines["left"].set_visible(False)
357
+ ax.tick_params(axis="y", length=0)
358
+ ax.set_title(title or (str(tab["label"].iloc[0]) if len(tab) else ""), color=INK)
359
+ return _finish(fig, save)
360
+
361
+
362
+ def memory(res: dict, *, ax=None, save=None):
363
+ """Clonal memory: how much a clone changes between snapshots, vs random clones.
364
+
365
+ Bars show the mean noise-corrected squared change of the same clone and of
366
+ random same-donor clones; the title gives the memory index with its 95% CI.
367
+ """
368
+ fig, ax = _ax(ax, figsize=(2.2, 2.0))
369
+ vals = [res["mean_change"], res["mean_change_random"]]
370
+ ax.bar([0, 1], vals, width=0.6, color=[PALETTE[0], OTHER])
371
+ ax.set_xticks([0, 1], ["same\nclone", "random\nclone"])
372
+ ax.set_ylabel("state change between snapshots")
373
+ ax.set_ylim(0, max(vals) * 1.25 if max(vals) > 0 else 1)
374
+ lo, hi = res["memory_index_ci"]
375
+ ax.set_title(f"memory index {res['memory_index']:.2f} [{lo:.2f}, {hi:.2f}]", color=INK)
376
+ return _finish(fig, save)
377
+
378
+
379
+ def label_effects(results: dict, *, ax=None, save=None):
380
+ """How much of the difference between clones each label explains.
381
+
382
+ ``results`` maps label names to :func:`threadfin.tl.profile_association`
383
+ results. Blue: share of clone-profile variance explained by the label;
384
+ grey: the same with labels shuffled among clones of the same donor.
385
+ """
386
+ labels = list(results)
387
+ if not labels:
388
+ raise ValueError("No label results to plot.")
389
+ fig, ax = _ax(ax, figsize=(3.4, 0.42 * len(labels) + 0.9))
390
+ y = np.arange(len(labels))[::-1].astype(float)
391
+ obs = np.array([100 * results[k]["r2"] for k in labels])
392
+ null = np.array([100 * results[k]["null_mean"] for k in labels])
393
+ ax.barh(y + 0.18, obs, height=0.34, color=PALETTE[0], label="observed")
394
+ ax.barh(y - 0.18, null, height=0.34, color=OTHER, label="labels shuffled among clones")
395
+ for yy, v, k in zip(y, obs, labels):
396
+ ax.text(v, yy + 0.18, f" p = {results[k]['p_value']:.2g}", va="center", color=INK,
397
+ fontsize=mpl.rcParams["font.size"] - 1)
398
+ ax.set_yticks(y, labels)
399
+ ax.tick_params(axis="y", length=0)
400
+ ax.set_xlim(0, max(obs.max(), null.max()) * 1.35)
401
+ ax.set_xlabel("difference between clones explained (%)")
402
+ ax.legend(loc="lower right", frameon=False, fontsize=mpl.rcParams["font.size"] - 1)
403
+ return _finish(fig, save)
404
+
405
+
406
+ def heritability(table: pd.DataFrame, *, highlight: dict | None = None, n_label: int = 12,
407
+ ax=None, save=None):
408
+ """Genes ranked by clonal ICC; optional gene sets highlighted (<= 3 sets)."""
409
+ fig, ax = _ax(ax, figsize=(3.0, 2.2))
410
+ tab = table.sort_values("icc", ascending=False)
411
+ rank = np.arange(1, len(tab) + 1)
412
+ ax.scatter(rank, tab["icc"], s=3, color=OTHER, linewidths=0, rasterized=True)
413
+ if highlight:
414
+ for (name, genes), col in zip(highlight.items(), PALETTE[:3]):
415
+ m = tab.index.isin(genes)
416
+ ax.scatter(rank[m], tab["icc"][m], s=12, color=col, edgecolors="white", linewidths=0.3, label=name)
417
+ ax.legend(loc="upper right", handletextpad=0.3)
418
+ for i, (gene, row) in enumerate(tab.head(n_label).iterrows()):
419
+ ax.text(rank[i] * 1.15, row["icc"], gene, fontsize=mpl.rcParams["font.size"] - 1.5, color=INK_2,
420
+ va="center", fontstyle="italic")
421
+ ax.set_xscale("log")
422
+ ax.set_xlabel("gene rank")
423
+ ax.set_ylabel("clonal ICC")
424
+ return _finish(fig, save)
425
+
426
+
427
+ def overview(adata, *, state_key: str | None = None, save=None):
428
+ """Four-panel summary of a :func:`threadfin.run` result."""
429
+ set_style()
430
+ fig = plt.figure(figsize=(7.2, 5.2))
431
+ gs = fig.add_gridspec(2, 3, width_ratios=[1.25, 1, 1], hspace=0.55, wspace=0.6)
432
+ sub = fig.add_subfigure(gs[:, 0])
433
+ clone_map(adata, fig=sub, ncols=2, facet=True)
434
+ sub.suptitle("a clonal programmes on the clone map", x=0.02, ha="left", color=INK, fontweight="bold")
435
+ ax_b = fig.add_subplot(gs[0, 1])
436
+ coherence(adata, ax=ax_b)
437
+ ax_c = fig.add_subplot(gs[0, 2])
438
+ stability(adata, ax=ax_c)
439
+ ax_d = fig.add_subplot(gs[1, 1:])
440
+ if state_key is not None:
441
+ programme_composition(adata, state_key, ax=ax_d)
442
+ ax_d.set_title("programme composition by cell state", color=INK)
443
+ else:
444
+ summ = adata.uns["threadfin"]["programmes"]["summary"]
445
+ ax_d.bar(range(len(summ)), summ["n_clones"], width=0.6, color=PALETTE[0])
446
+ ax_d.set_xticks(range(len(summ)), [str(i) for i in summ.index])
447
+ ax_d.set_ylabel("clones")
448
+ ax_d.set_title("programme sizes", color=INK)
449
+ for ax, lab, dx in ((ax_b, "b", -0.28), (ax_c, "c", -0.28), (ax_d, "d", -0.12)):
450
+ ax.text(dx, 1.12, lab, transform=ax.transAxes, fontweight="bold", color=INK,
451
+ fontsize=mpl.rcParams["font.size"] + 2)
452
+ return _finish(fig, save)
453
+
454
+
455
+ # --------------------------------------------------------------------------- cell-level panels (v3)
456
+
457
+
458
+ def cells(adata, color: str = "clone_cluster", basis: str = "X_umap", ax=None, palette: dict | None = None,
459
+ s: float = 10, title: str | None = None, save: str | None = None):
460
+ """Cells on an embedding coloured by an ``obs`` column (cells without a value in grey)."""
461
+ if basis not in adata.obsm:
462
+ raise KeyError(f"{basis!r} not in adata.obsm.")
463
+ if color not in adata.obs.columns:
464
+ raise KeyError(f"{color!r} not in adata.obs.")
465
+ fig, ax = _ax(ax, figsize=(7, 6))
466
+ xy = np.asarray(adata.obsm[basis])
467
+ values = adata.obs[color]
468
+ if isinstance(values.dtype, pd.CategoricalDtype) or values.dtype == object:
469
+ cats = pd.Categorical(values)
470
+ palette = palette or category_colors(cats.categories)
471
+ na = values.isna().to_numpy()
472
+ if na.any():
473
+ ax.scatter(xy[na, 0], xy[na, 1], s=s, color="lightgrey", alpha=0.3, label="no BCR", rasterized=True)
474
+ for cat in cats.categories:
475
+ m = np.asarray(cats == cat) & ~na
476
+ ax.scatter(xy[m, 0], xy[m, 1], s=s, color=palette.get(cat, OTHER), label=str(cat), alpha=0.8,
477
+ rasterized=True)
478
+ ax.legend(title=color, loc="center left", bbox_to_anchor=(1.0, 0.5), markerscale=2)
479
+ else:
480
+ cmap = mpl.colors.LinearSegmentedColormap.from_list("tf_blue", BLUE_RAMP)
481
+ sc_ = ax.scatter(xy[:, 0], xy[:, 1], s=s, c=pd.to_numeric(values, errors="coerce"), cmap=cmap,
482
+ alpha=0.8, rasterized=True)
483
+ plt.colorbar(sc_, ax=ax, label=color)
484
+ ax.set_xlabel("UMAP 1")
485
+ ax.set_ylabel("UMAP 2")
486
+ ax.set_title(title or f"Cells colored by {color}")
487
+ fig.tight_layout()
488
+ if save:
489
+ fig.savefig(save, dpi=300, bbox_inches="tight")
490
+ return fig, ax
491
+
492
+
493
+ def signature_heatmap(adata, signatures: dict, groupby: str = "clone_cluster", layer: str | None = None,
494
+ z_score: bool = True, ax=None, cmap: str = "viridis", save: str | None = None):
495
+ """Mean expression of gene signatures per group (z-scored across groups).
496
+
497
+ Only the signature genes are densified, so this is safe on large datasets.
498
+ """
499
+ obs_groups = adata.obs[groupby]
500
+ groups = list(pd.Categorical(obs_groups.dropna()).categories)
501
+ genes = sorted({g for gs_ in signatures.values() for g in gs_ if g in adata.var_names})
502
+ x = adata[:, genes].layers[layer] if layer else adata[:, genes].X
503
+ if hasattr(x, "toarray"):
504
+ x = x.toarray()
505
+ expr = pd.DataFrame(np.asarray(x), index=adata.obs_names, columns=genes)
506
+ mat = pd.DataFrame(index=groups, columns=list(signatures), dtype=float)
507
+ for g in groups:
508
+ idx = (obs_groups == g).to_numpy()
509
+ if idx.sum() == 0:
510
+ continue
511
+ sub = expr.iloc[idx]
512
+ for sig, gs_ in signatures.items():
513
+ present = [ge for ge in gs_ if ge in expr.columns]
514
+ if present:
515
+ mat.loc[g, sig] = float(sub[present].to_numpy().mean())
516
+ mat = mat.dropna(how="all")
517
+ if z_score:
518
+ mat = (mat - mat.mean()) / mat.std(ddof=0)
519
+ fig, ax = _ax(ax, figsize=(max(4, 0.9 * mat.shape[1]), max(3, 0.6 * mat.shape[0])))
520
+ im = ax.imshow(mat.to_numpy(dtype=float), aspect="auto", cmap=cmap)
521
+ ax.set_xticks(range(mat.shape[1]), mat.columns, rotation=45, ha="right")
522
+ ax.set_yticks(range(mat.shape[0]), mat.index)
523
+ vals = mat.to_numpy(dtype=float)
524
+ for i in range(mat.shape[0]):
525
+ for j in range(mat.shape[1]):
526
+ if np.isfinite(vals[i, j]):
527
+ ax.text(j, i, f"{vals[i, j]:.1f}", ha="center", va="center", fontsize=8,
528
+ color="white" if abs(vals[i, j]) > np.nanstd(vals) else "black")
529
+ plt.colorbar(im, ax=ax, label="z-scored mean expression" if z_score else "mean expression")
530
+ ax.set_xlabel("Gene signature")
531
+ ax.set_ylabel(groupby)
532
+ fig.tight_layout()
533
+ if save:
534
+ fig.savefig(save, dpi=300, bbox_inches="tight")
535
+ return fig, ax, mat