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/__init__.py +86 -0
- threadfin/_utils.py +260 -0
- threadfin/api.py +658 -0
- threadfin/bcrgraph.py +255 -0
- threadfin/clones.py +653 -0
- threadfin/core.py +531 -0
- threadfin/dandelion.py +458 -0
- threadfin/density.py +409 -0
- threadfin/dynamics.py +275 -0
- threadfin/export.py +215 -0
- threadfin/expression.py +121 -0
- threadfin/heritability.py +224 -0
- threadfin/integrate.py +350 -0
- threadfin/io.py +280 -0
- threadfin/maptune.py +743 -0
- threadfin/metrics.py +137 -0
- threadfin/migration.py +165 -0
- threadfin/phylo.py +834 -0
- threadfin/plotting.py +535 -0
- threadfin/pp.py +253 -0
- threadfin/profiles.py +603 -0
- threadfin/programmes.py +1028 -0
- threadfin/programs.py +133 -0
- threadfin/reclustering.py +68 -0
- threadfin/sequence.py +379 -0
- threadfin/simulate.py +206 -0
- threadfin/specificity.py +355 -0
- threadfin/stats.py +476 -0
- threadfin/tl.py +62 -0
- threadfin-4.5.0.dist-info/METADATA +288 -0
- threadfin-4.5.0.dist-info/RECORD +34 -0
- threadfin-4.5.0.dist-info/WHEEL +5 -0
- threadfin-4.5.0.dist-info/licenses/LICENSE +21 -0
- threadfin-4.5.0.dist-info/top_level.txt +1 -0
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
|