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/__init__.py
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
"""Threadfin: clone-level analysis of B-cell states from paired scRNA-seq + BCR-seq.
|
|
2
|
+
|
|
3
|
+
Quick start
|
|
4
|
+
-----------
|
|
5
|
+
>>> import threadfin as tf
|
|
6
|
+
>>> result = tf.run(adata, bcr="filtered_contig_annotations.csv",
|
|
7
|
+
... donor_key="donor", sample_key="sample")
|
|
8
|
+
>>> print(result.summary())
|
|
9
|
+
|
|
10
|
+
Namespaces
|
|
11
|
+
----------
|
|
12
|
+
``tf.run`` / ``tf.read_bcr`` one-call analysis and BCR reader
|
|
13
|
+
``tf.tl`` the individual analysis steps
|
|
14
|
+
``tf.pp`` preprocessing (embedding without IG genes)
|
|
15
|
+
``tf.pl`` figures
|
|
16
|
+
``tf.sim`` simulated data with known ground truth
|
|
17
|
+
|
|
18
|
+
The v3 functions (``clonotype_recluster``, ``joint_embedding``, ...) remain
|
|
19
|
+
importable for backward compatibility.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from . import export, phylo, plotting, pp, reclustering, simulate, tl
|
|
23
|
+
from .dandelion import define_clones_dandelion, read_contigs
|
|
24
|
+
from .api import ThreadfinResult, read_bcr, run
|
|
25
|
+
from .density import DensityResult, StateDensityModel
|
|
26
|
+
from .clones import define_clones
|
|
27
|
+
from .io import attach_bcr, build_clone_key, read_10x_vdj, read_airr
|
|
28
|
+
|
|
29
|
+
pl = plotting
|
|
30
|
+
sim = simulate
|
|
31
|
+
|
|
32
|
+
# v3 API, kept for backward compatibility
|
|
33
|
+
from . import clones, metrics, migration, programs, sequence, specificity # noqa: E402
|
|
34
|
+
from .bcrgraph import bcr_similarity_graph # noqa: E402
|
|
35
|
+
from .core import bcr_reclustering, clonal_pseudotime, clone_centroids, clonotype_recluster # noqa: E402
|
|
36
|
+
from .integrate import integration_diagnostics, joint_embedding # noqa: E402
|
|
37
|
+
from .migration import clone_distribution, expansion_index, migration_index, transition_index # noqa: E402
|
|
38
|
+
from .programs import community_markers, community_score # noqa: E402
|
|
39
|
+
from .reclustering import reclustering_presets # noqa: E402
|
|
40
|
+
from .specificity import annotate_specificity, specificity_enrichment # noqa: E402
|
|
41
|
+
|
|
42
|
+
__version__ = "4.5.0"
|
|
43
|
+
__all__ = [
|
|
44
|
+
"ThreadfinResult",
|
|
45
|
+
"DensityResult",
|
|
46
|
+
"StateDensityModel",
|
|
47
|
+
"attach_bcr",
|
|
48
|
+
"build_clone_key",
|
|
49
|
+
"define_clones",
|
|
50
|
+
"define_clones_dandelion",
|
|
51
|
+
"export",
|
|
52
|
+
"phylo",
|
|
53
|
+
"pl",
|
|
54
|
+
"pp",
|
|
55
|
+
"read_10x_vdj",
|
|
56
|
+
"read_airr",
|
|
57
|
+
"read_bcr",
|
|
58
|
+
"reclustering",
|
|
59
|
+
"reclustering_presets",
|
|
60
|
+
"run",
|
|
61
|
+
"sim",
|
|
62
|
+
"tl",
|
|
63
|
+
# v3 (legacy)
|
|
64
|
+
"annotate_specificity",
|
|
65
|
+
"bcr_reclustering",
|
|
66
|
+
"bcr_similarity_graph",
|
|
67
|
+
"clonal_pseudotime",
|
|
68
|
+
"clone_centroids",
|
|
69
|
+
"clone_distribution",
|
|
70
|
+
"clones",
|
|
71
|
+
"clonotype_recluster",
|
|
72
|
+
"community_markers",
|
|
73
|
+
"community_score",
|
|
74
|
+
"expansion_index",
|
|
75
|
+
"integration_diagnostics",
|
|
76
|
+
"joint_embedding",
|
|
77
|
+
"metrics",
|
|
78
|
+
"migration",
|
|
79
|
+
"migration_index",
|
|
80
|
+
"plotting",
|
|
81
|
+
"programs",
|
|
82
|
+
"sequence",
|
|
83
|
+
"specificity",
|
|
84
|
+
"specificity_enrichment",
|
|
85
|
+
"transition_index",
|
|
86
|
+
]
|
threadfin/_utils.py
ADDED
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
"""Internal helpers shared across Threadfin modules (not public API)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import numpy as np
|
|
6
|
+
import pandas as pd
|
|
7
|
+
import scipy.sparse as sp
|
|
8
|
+
|
|
9
|
+
UNS_KEY = "threadfin"
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def log(msg: str, verbose: bool = True) -> None:
|
|
13
|
+
"""Print a progress message with the package prefix."""
|
|
14
|
+
if verbose:
|
|
15
|
+
print(f"[threadfin] {msg}", flush=True)
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def ensure_actual(adata, verbose: bool = True):
|
|
19
|
+
"""Turn a view (``adata[mask]`` without ``.copy()``) into its own AnnData, in place.
|
|
20
|
+
|
|
21
|
+
Results written to a view are not kept, which used to surface later as a misleading "run clone_profiles
|
|
22
|
+
first". AnnData itself converts a view on its first change; this does it up front and says so.
|
|
23
|
+
"""
|
|
24
|
+
if getattr(adata, "is_view", False):
|
|
25
|
+
adata._init_as_actual(adata.copy())
|
|
26
|
+
log("adata was a view (a subset made without .copy()); it now holds its own data, so the results "
|
|
27
|
+
"can be stored in it", verbose)
|
|
28
|
+
return adata
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def get_uns(adata) -> dict:
|
|
32
|
+
"""The Threadfin results dict in ``adata.uns`` (created if absent)."""
|
|
33
|
+
return adata.uns.setdefault(UNS_KEY, {})
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def require_obs(adata, *cols: str, context: str | None = None) -> None:
|
|
37
|
+
"""Raise a helpful ``KeyError`` if any ``obs`` column is missing, naming the closest existing columns."""
|
|
38
|
+
import difflib
|
|
39
|
+
|
|
40
|
+
for col in cols:
|
|
41
|
+
if col is not None and col not in adata.obs.columns:
|
|
42
|
+
hint = f" (needed for {context})" if context else ""
|
|
43
|
+
names = [str(c) for c in adata.obs.columns]
|
|
44
|
+
close = difflib.get_close_matches(str(col), names, n=3, cutoff=0.6)
|
|
45
|
+
close += [c for c in names if c.lower() == str(col).lower() and c not in close]
|
|
46
|
+
suggestion = (f" Did you mean {', '.join(repr(c) for c in close)}?" if close
|
|
47
|
+
else f" Columns available: {', '.join(repr(c) for c in names[:12])}"
|
|
48
|
+
+ (" ..." if len(names) > 12 else "") + ".")
|
|
49
|
+
raise KeyError(f"'{col}' not found in adata.obs{hint}.{suggestion}")
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def require_complete_groups(adata, *cols: str, context: str | None = None) -> None:
|
|
53
|
+
"""Require grouping columns to have a non-empty label for every cell."""
|
|
54
|
+
require_obs(adata, *cols, context=context)
|
|
55
|
+
for col in cols:
|
|
56
|
+
if col is None:
|
|
57
|
+
continue
|
|
58
|
+
values = adata.obs[col]
|
|
59
|
+
blank = values.astype("string").str.strip().eq("").fillna(False)
|
|
60
|
+
bad = values.isna() | blank
|
|
61
|
+
if bad.any():
|
|
62
|
+
hint = f" for {context}" if context else ""
|
|
63
|
+
raise ValueError(
|
|
64
|
+
f"Grouping column '{col}' has {int(bad.sum())} missing or blank value(s){hint}. "
|
|
65
|
+
"Every cell needs a donor/sample/batch label; fill or remove those cells before analysis."
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def require_positive_int(value, name: str) -> None:
|
|
70
|
+
"""Require a positive integer, rejecting bools and truncating floats."""
|
|
71
|
+
if isinstance(value, (bool, np.bool_)) or not isinstance(value, (int, np.integer)) or value < 1:
|
|
72
|
+
raise ValueError(f"{name} must be a positive integer.")
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def get_basis(adata, basis: str, dtype=np.float64) -> np.ndarray:
|
|
76
|
+
"""Dense cell x feature matrix from ``obsm[basis]`` (or ``X`` / a layer).
|
|
77
|
+
|
|
78
|
+
``basis`` may be an ``obsm`` key, ``"X"``, or ``"layer:<name>"``.
|
|
79
|
+
"""
|
|
80
|
+
if basis == "X":
|
|
81
|
+
x = adata.X
|
|
82
|
+
elif basis.startswith("layer:"):
|
|
83
|
+
name = basis.split(":", 1)[1]
|
|
84
|
+
if name not in adata.layers:
|
|
85
|
+
raise KeyError(f"layer '{name}' not found in adata.layers.")
|
|
86
|
+
x = adata.layers[name]
|
|
87
|
+
else:
|
|
88
|
+
if basis not in adata.obsm:
|
|
89
|
+
raise KeyError(
|
|
90
|
+
f"'{basis}' not found in adata.obsm. Compute an embedding first "
|
|
91
|
+
"(e.g. threadfin.pp.prepare_embedding or sc.tl.pca)."
|
|
92
|
+
)
|
|
93
|
+
x = adata.obsm[basis]
|
|
94
|
+
if sp.issparse(x):
|
|
95
|
+
x = x.toarray()
|
|
96
|
+
x = np.asarray(x, dtype=dtype)
|
|
97
|
+
if x.ndim != 2:
|
|
98
|
+
raise ValueError(
|
|
99
|
+
f"'{basis}' must be a two-dimensional cell-by-feature matrix; got an array with {x.ndim} dimensions."
|
|
100
|
+
)
|
|
101
|
+
if x.shape[0] != adata.n_obs:
|
|
102
|
+
raise ValueError(
|
|
103
|
+
f"'{basis}' has {x.shape[0]} rows but adata has {adata.n_obs} cells. "
|
|
104
|
+
"Provide one embedding row per cell."
|
|
105
|
+
)
|
|
106
|
+
if x.shape[1] == 0:
|
|
107
|
+
raise ValueError(f"'{basis}' has no features. Compute or provide a non-empty embedding.")
|
|
108
|
+
if not np.isfinite(x).all():
|
|
109
|
+
bad = int((~np.isfinite(x).all(axis=1)).sum())
|
|
110
|
+
raise ValueError(
|
|
111
|
+
f"'{basis}' has NaN or infinite values in {bad:,} of {x.shape[0]:,} cells. Recompute the embedding, or "
|
|
112
|
+
f"drop those cells first: adata = adata[np.isfinite(adata.obsm['{basis}']).all(axis=1)].copy()")
|
|
113
|
+
return x
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def codes(values: pd.Series | np.ndarray) -> tuple[np.ndarray, pd.Index]:
|
|
117
|
+
"""Integer codes (-1 for missing) and the matching category index."""
|
|
118
|
+
cat = pd.Categorical(pd.Series(values).astype("object").where(pd.notna(values)))
|
|
119
|
+
return cat.codes.astype(np.int64), cat.categories
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def group_means(x: np.ndarray, group: np.ndarray, n_groups: int) -> tuple[np.ndarray, np.ndarray]:
|
|
123
|
+
"""Per-group means and sizes of rows of ``x`` (rows with group < 0 ignored)."""
|
|
124
|
+
ok = group >= 0
|
|
125
|
+
sums = np.zeros((n_groups, x.shape[1]))
|
|
126
|
+
np.add.at(sums, group[ok], x[ok])
|
|
127
|
+
n = np.bincount(group[ok], minlength=n_groups).astype(float)
|
|
128
|
+
with np.errstate(invalid="ignore", divide="ignore"):
|
|
129
|
+
means = sums / n[:, None]
|
|
130
|
+
return means, n
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def indicator(group: np.ndarray, n_groups: int, weights: np.ndarray | None = None) -> sp.csr_matrix:
|
|
134
|
+
"""Sparse ``(n_groups, n_rows)`` membership matrix (rows with group < 0 dropped)."""
|
|
135
|
+
ok = np.flatnonzero(group >= 0)
|
|
136
|
+
w = np.ones(ok.size) if weights is None else np.asarray(weights, dtype=float)[ok]
|
|
137
|
+
return sp.csr_matrix((w, (group[ok], ok)), shape=(n_groups, group.size))
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def permute_within(labels: np.ndarray, strata: np.ndarray | None, rng: np.random.Generator) -> np.ndarray:
|
|
141
|
+
"""Permute ``labels`` among entries sharing the same stratum.
|
|
142
|
+
|
|
143
|
+
Entries with a negative label (missing) keep their position, so the
|
|
144
|
+
permutation preserves exactly which cells/clones are labelled within
|
|
145
|
+
each stratum.
|
|
146
|
+
"""
|
|
147
|
+
out = labels.copy()
|
|
148
|
+
valid = labels >= 0 if np.issubdtype(labels.dtype, np.integer) else pd.notna(labels)
|
|
149
|
+
if strata is None:
|
|
150
|
+
idx = np.flatnonzero(valid)
|
|
151
|
+
out[idx] = labels[rng.permutation(idx)]
|
|
152
|
+
return out
|
|
153
|
+
strata = np.asarray(strata)
|
|
154
|
+
order = np.flatnonzero(valid)
|
|
155
|
+
s = strata[order]
|
|
156
|
+
for key in np.unique(s):
|
|
157
|
+
idx = order[s == key]
|
|
158
|
+
if idx.size > 1:
|
|
159
|
+
out[idx] = labels[rng.permutation(idx)]
|
|
160
|
+
return out
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def bh_fdr(p) -> np.ndarray:
|
|
164
|
+
"""Benjamini-Hochberg adjusted p-values (NaNs preserved)."""
|
|
165
|
+
p = np.asarray(p, dtype=float)
|
|
166
|
+
out = np.full_like(p, np.nan)
|
|
167
|
+
ok = np.isfinite(p)
|
|
168
|
+
m = int(ok.sum())
|
|
169
|
+
if m == 0:
|
|
170
|
+
return out
|
|
171
|
+
pv = p[ok]
|
|
172
|
+
order = np.argsort(pv)
|
|
173
|
+
ranked = pv[order] * m / np.arange(1, m + 1)
|
|
174
|
+
adj = np.minimum.accumulate(ranked[::-1])[::-1].clip(max=1.0)
|
|
175
|
+
res = np.empty(m)
|
|
176
|
+
res[order] = adj
|
|
177
|
+
out[ok] = res
|
|
178
|
+
return out
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
def perm_pvalue(observed: float, null: np.ndarray, alternative: str = "greater") -> float:
|
|
182
|
+
"""Permutation p-value with the +1 correction (Phipson & Smyth 2010)."""
|
|
183
|
+
null = np.asarray(null, dtype=float)
|
|
184
|
+
null = null[np.isfinite(null)]
|
|
185
|
+
if null.size == 0 or not np.isfinite(observed):
|
|
186
|
+
return float("nan")
|
|
187
|
+
if alternative == "greater":
|
|
188
|
+
k = int((null >= observed).sum())
|
|
189
|
+
elif alternative == "less":
|
|
190
|
+
k = int((null <= observed).sum())
|
|
191
|
+
elif alternative == "two-sided":
|
|
192
|
+
center = float(np.median(null))
|
|
193
|
+
k = int((np.abs(null - center) >= abs(observed - center)).sum())
|
|
194
|
+
else:
|
|
195
|
+
raise ValueError(f"unknown alternative {alternative!r}")
|
|
196
|
+
return (1 + k) / (null.size + 1)
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def modal(series: pd.Series):
|
|
200
|
+
"""Deterministic mode (ties broken by sort order); ``None`` if empty."""
|
|
201
|
+
s = series.dropna()
|
|
202
|
+
if s.empty:
|
|
203
|
+
return None
|
|
204
|
+
vc = s.astype(str).value_counts()
|
|
205
|
+
top = vc[vc == vc.iloc[0]].index
|
|
206
|
+
return sorted(top)[0]
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def stable_categorical(values, prefix: str) -> pd.Categorical:
|
|
210
|
+
"""Relabel integer cluster ids as ``<prefix>1..K`` ordered by size."""
|
|
211
|
+
s = pd.Series(values)
|
|
212
|
+
sizes = s.value_counts()
|
|
213
|
+
mapping = {lab: f"{prefix}{i + 1}" for i, lab in enumerate(sizes.index)}
|
|
214
|
+
cats = [mapping[lab] for lab in sizes.index]
|
|
215
|
+
return pd.Categorical(s.map(mapping), categories=cats)
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def h5ad_safe(obj):
|
|
219
|
+
"""A copy of ``obj`` that AnnData can write to h5ad, for storing results in ``adata.uns``.
|
|
220
|
+
|
|
221
|
+
AnnData cannot write tuples, lists of dicts, ragged lists, or DataFrame columns that hold lists,
|
|
222
|
+
``None`` among text, or a mix of numbers and text. These become lists, DataFrames and text; everything
|
|
223
|
+
else is returned unchanged.
|
|
224
|
+
"""
|
|
225
|
+
import numpy as np
|
|
226
|
+
import pandas as pd
|
|
227
|
+
|
|
228
|
+
def seq_text(v):
|
|
229
|
+
return ",".join(str(x) for x in v)
|
|
230
|
+
|
|
231
|
+
if isinstance(obj, dict):
|
|
232
|
+
return {k: h5ad_safe(v) for k, v in obj.items()}
|
|
233
|
+
if isinstance(obj, tuple):
|
|
234
|
+
obj = list(obj)
|
|
235
|
+
if isinstance(obj, list):
|
|
236
|
+
if obj and all(isinstance(v, dict) for v in obj):
|
|
237
|
+
return h5ad_safe(pd.DataFrame(obj))
|
|
238
|
+
if any(isinstance(v, (list, tuple, np.ndarray, dict)) for v in obj):
|
|
239
|
+
return [seq_text(v) if isinstance(v, (list, tuple, np.ndarray)) else str(v) for v in obj]
|
|
240
|
+
return obj
|
|
241
|
+
if isinstance(obj, pd.DataFrame):
|
|
242
|
+
out = obj.copy()
|
|
243
|
+
for col in out.columns:
|
|
244
|
+
s = out[col]
|
|
245
|
+
if s.dtype != object:
|
|
246
|
+
continue
|
|
247
|
+
if s.map(lambda v: isinstance(v, (list, tuple, np.ndarray))).any():
|
|
248
|
+
out[col] = s.map(lambda v: seq_text(v) if isinstance(v, (list, tuple, np.ndarray)) else
|
|
249
|
+
("" if v is None or (isinstance(v, float) and np.isnan(v)) else str(v)))
|
|
250
|
+
continue
|
|
251
|
+
kinds = {type(v) for v in s if v is not None and not (isinstance(v, float) and np.isnan(v))}
|
|
252
|
+
if kinds <= {bool, np.bool_} and s.notna().all():
|
|
253
|
+
out[col] = s.astype(bool)
|
|
254
|
+
elif kinds and kinds <= {int, float, np.integer, np.floating} | set(np.sctypeDict.values()) and \
|
|
255
|
+
all(isinstance(v, (int, float, np.number)) for v in s.dropna()):
|
|
256
|
+
out[col] = pd.to_numeric(s, errors="coerce")
|
|
257
|
+
elif s.isna().any() or len(kinds) > 1:
|
|
258
|
+
out[col] = s.map(lambda v: "" if v is None or (isinstance(v, float) and np.isnan(v)) else str(v))
|
|
259
|
+
return out
|
|
260
|
+
return obj
|