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 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