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/metrics.py
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
"""Evaluation metrics for clonotype--transcriptional-state integration."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import numpy as np
|
|
6
|
+
import pandas as pd
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def state_concordance(
|
|
10
|
+
adata,
|
|
11
|
+
cluster_key: str = "clone_cluster",
|
|
12
|
+
state_key: str = "leiden",
|
|
13
|
+
) -> dict:
|
|
14
|
+
"""Agreement between clone clusters and transcriptional cell states.
|
|
15
|
+
|
|
16
|
+
Parameters
|
|
17
|
+
----------
|
|
18
|
+
adata
|
|
19
|
+
AnnData with both ``obs[cluster_key]`` and ``obs[state_key]``.
|
|
20
|
+
cluster_key
|
|
21
|
+
Clone cluster labels (from :func:`threadfin.clonotype_recluster`).
|
|
22
|
+
state_key
|
|
23
|
+
Reference transcriptional state labels (e.g. Leiden cell clusters or
|
|
24
|
+
curated cell-type annotations).
|
|
25
|
+
|
|
26
|
+
Returns
|
|
27
|
+
-------
|
|
28
|
+
dict with ``nmi`` (normalized mutual information), ``ari`` (adjusted Rand
|
|
29
|
+
index) and ``n_cells_used``.
|
|
30
|
+
"""
|
|
31
|
+
from sklearn.metrics import adjusted_rand_score, normalized_mutual_info_score
|
|
32
|
+
|
|
33
|
+
obs = adata.obs[[cluster_key, state_key]].dropna()
|
|
34
|
+
if len(obs) == 0:
|
|
35
|
+
raise ValueError("No cells with both labels present.")
|
|
36
|
+
ari = adjusted_rand_score(obs[state_key], obs[cluster_key])
|
|
37
|
+
nmi = normalized_mutual_info_score(obs[state_key], obs[cluster_key])
|
|
38
|
+
return {"nmi": float(nmi), "ari": float(ari), "n_cells_used": int(len(obs))}
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def clone_state_purity(
|
|
42
|
+
adata,
|
|
43
|
+
clone_key: str = "clone_id",
|
|
44
|
+
state_key: str = "leiden",
|
|
45
|
+
min_clone_size: int = 3,
|
|
46
|
+
) -> pd.DataFrame:
|
|
47
|
+
"""Per-clone transcriptional-state purity.
|
|
48
|
+
|
|
49
|
+
For every clone with at least ``min_clone_size`` cells, computes the
|
|
50
|
+
fraction of cells in the clone's dominant state and the Shannon entropy
|
|
51
|
+
of the state distribution (0 = all cells in one state).
|
|
52
|
+
|
|
53
|
+
Returns
|
|
54
|
+
-------
|
|
55
|
+
DataFrame indexed by clone id with columns ``n_cells``,
|
|
56
|
+
``dominant_state``, ``purity``, ``entropy``.
|
|
57
|
+
"""
|
|
58
|
+
obs = adata.obs[[clone_key, state_key]].dropna()
|
|
59
|
+
rows = []
|
|
60
|
+
for clone, grp in obs.groupby(clone_key, observed=True):
|
|
61
|
+
if len(grp) < min_clone_size:
|
|
62
|
+
continue
|
|
63
|
+
freq = grp[state_key].value_counts(normalize=True)
|
|
64
|
+
entropy = float(-(freq * np.log2(freq + 1e-12)).sum())
|
|
65
|
+
rows.append(
|
|
66
|
+
{
|
|
67
|
+
clone_key: clone,
|
|
68
|
+
"n_cells": int(len(grp)),
|
|
69
|
+
"dominant_state": freq.index[0],
|
|
70
|
+
"purity": float(freq.iloc[0]),
|
|
71
|
+
"entropy": entropy,
|
|
72
|
+
}
|
|
73
|
+
)
|
|
74
|
+
if not rows:
|
|
75
|
+
raise ValueError("No clones pass min_clone_size.")
|
|
76
|
+
return pd.DataFrame(rows).set_index(clone_key)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def clone_cluster_summary(adata, cluster_key: str = "clone_cluster") -> pd.DataFrame:
|
|
80
|
+
"""Cell and clone counts per clone cluster."""
|
|
81
|
+
clone_map = adata.uns.get("threadfin", {}).get("clone_map")
|
|
82
|
+
if clone_map is None:
|
|
83
|
+
raise ValueError("Run threadfin.clonotype_recluster() first.")
|
|
84
|
+
out = (
|
|
85
|
+
clone_map.groupby(cluster_key, observed=True)
|
|
86
|
+
.agg(n_clones=(cluster_key, "size"), n_cells=("n_cells", "sum"))
|
|
87
|
+
.sort_values("n_cells", ascending=False)
|
|
88
|
+
)
|
|
89
|
+
return out
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def state_enrichment(
|
|
93
|
+
adata,
|
|
94
|
+
cluster_key: str = "clone_cluster",
|
|
95
|
+
state_key: str = "state",
|
|
96
|
+
) -> pd.DataFrame:
|
|
97
|
+
"""Fisher-exact enrichment of transcriptional states in clone clusters.
|
|
98
|
+
|
|
99
|
+
For every (clone cluster, state) pair, tests whether cells of that state
|
|
100
|
+
are over-represented in the cluster. This legacy calculation treats cells
|
|
101
|
+
as independent and reuses expression-derived labels. Interpret it as a
|
|
102
|
+
descriptive enrichment, not independent biological validation; use
|
|
103
|
+
threadfin.tl.association_test for clone-level stratified comparisons.
|
|
104
|
+
|
|
105
|
+
Returns
|
|
106
|
+
-------
|
|
107
|
+
DataFrame with one row per (cluster, state) pair: ``n_cells``,
|
|
108
|
+
``odds_ratio``, ``pvalue`` and BH-adjusted ``fdr``, sorted by p-value.
|
|
109
|
+
"""
|
|
110
|
+
from scipy.stats import fisher_exact
|
|
111
|
+
|
|
112
|
+
obs = adata.obs[[cluster_key, state_key]].dropna()
|
|
113
|
+
clusters = pd.Categorical(obs[cluster_key]).categories
|
|
114
|
+
states = pd.Categorical(obs[state_key]).categories
|
|
115
|
+
|
|
116
|
+
rows = []
|
|
117
|
+
n = len(obs)
|
|
118
|
+
for cl in clusters:
|
|
119
|
+
in_cl = (obs[cluster_key] == cl).to_numpy()
|
|
120
|
+
n_cl = int(in_cl.sum())
|
|
121
|
+
for st in states:
|
|
122
|
+
in_st = (obs[state_key] == st).to_numpy()
|
|
123
|
+
a = int((in_cl & in_st).sum())
|
|
124
|
+
b = n_cl - a
|
|
125
|
+
c = int(in_st.sum()) - a
|
|
126
|
+
d = n - a - b - c
|
|
127
|
+
odds, p = fisher_exact([[a, b], [c, d]], alternative="greater")
|
|
128
|
+
rows.append({cluster_key: cl, state_key: st, "n_cells": a,
|
|
129
|
+
"odds_ratio": float(odds), "pvalue": float(p)})
|
|
130
|
+
|
|
131
|
+
out = pd.DataFrame(rows).sort_values("pvalue").reset_index(drop=True)
|
|
132
|
+
# Benjamini-Hochberg FDR
|
|
133
|
+
m = len(out)
|
|
134
|
+
ranks = np.arange(1, m + 1)
|
|
135
|
+
fdr = out["pvalue"] * m / ranks
|
|
136
|
+
out["fdr"] = np.minimum.accumulate(fdr.to_numpy()[::-1])[::-1].clip(max=1.0)
|
|
137
|
+
return out
|
threadfin/migration.py
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
"""STARTRAC-style clonal dynamics indices: migration, transition, expansion.
|
|
2
|
+
|
|
3
|
+
Legacy clone-sharing summaries inspired by the STARTRAC indices (Zhang et al.,
|
|
4
|
+
*Nature* 2018, doi:10.1038/s41586-018-0694-x) for paired scRNA-seq +
|
|
5
|
+
scBCR-seq data: pairwise group migration (STARTRAC-migr), state transition
|
|
6
|
+
(STARTRAC-tran) and per-group clonal expansion (STARTRAC-expa).
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import numpy as np
|
|
12
|
+
import pandas as pd
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def _require_columns(adata, cols) -> None:
|
|
16
|
+
for col in cols:
|
|
17
|
+
if col not in adata.obs.columns:
|
|
18
|
+
raise KeyError(f"'{col}' not found in adata.obs.")
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def clone_distribution(
|
|
22
|
+
adata,
|
|
23
|
+
*,
|
|
24
|
+
clone_key: str = "clone_id",
|
|
25
|
+
group_key: str,
|
|
26
|
+
min_clone_size: int = 2,
|
|
27
|
+
) -> pd.DataFrame:
|
|
28
|
+
"""Clones x groups matrix of within-clone cell fractions.
|
|
29
|
+
|
|
30
|
+
Each row is a clone; entry ``p[c, g]`` is the fraction of clone ``c``'s
|
|
31
|
+
cells found in group ``g``, so every row sums to 1. Cells with a missing
|
|
32
|
+
``clone_key`` or ``group_key`` value are excluded. Clones with fewer than
|
|
33
|
+
``min_clone_size`` cells are dropped: fractions estimated from one or two
|
|
34
|
+
cells are dominated by sampling noise and would otherwise inflate the
|
|
35
|
+
downstream migration/transition indices.
|
|
36
|
+
|
|
37
|
+
Returns
|
|
38
|
+
-------
|
|
39
|
+
DataFrame with index = ``clone_key`` values, columns = ``group_key``
|
|
40
|
+
values, values = within-clone fractions (rows sum to 1).
|
|
41
|
+
"""
|
|
42
|
+
_require_columns(adata, (clone_key, group_key))
|
|
43
|
+
|
|
44
|
+
df = adata.obs[[clone_key, group_key]].dropna()
|
|
45
|
+
sizes = df.groupby(clone_key, observed=True).size()
|
|
46
|
+
keep = sizes[sizes >= min_clone_size].index
|
|
47
|
+
df = df[df[clone_key].isin(keep)]
|
|
48
|
+
|
|
49
|
+
counts = pd.crosstab(df[clone_key], df[group_key])
|
|
50
|
+
dist = counts.div(counts.sum(axis=1), axis=0).astype(float)
|
|
51
|
+
dist.index.name = clone_key
|
|
52
|
+
dist.columns.name = group_key
|
|
53
|
+
return dist
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _pairwise_index(adata, clone_key: str, split_key: str, min_clone_size: int) -> pd.DataFrame:
|
|
57
|
+
dist = clone_distribution(
|
|
58
|
+
adata, clone_key=clone_key, group_key=split_key, min_clone_size=min_clone_size
|
|
59
|
+
)
|
|
60
|
+
return dist.T.dot(dist)
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def migration_index(
|
|
64
|
+
adata,
|
|
65
|
+
*,
|
|
66
|
+
clone_key: str = "clone_id",
|
|
67
|
+
group_key: str,
|
|
68
|
+
min_clone_size: int = 2,
|
|
69
|
+
) -> pd.DataFrame:
|
|
70
|
+
"""Pairwise group migration index (STARTRAC-migr analogue).
|
|
71
|
+
|
|
72
|
+
.. math::
|
|
73
|
+
|
|
74
|
+
\\mathrm{migr}(g_1, g_2) = \\sum_c p_{c,g_1} \\cdot p_{c,g_2}
|
|
75
|
+
|
|
76
|
+
where ``p[c, g]`` is the fraction of clone ``c``'s cells in group ``g``
|
|
77
|
+
(see :func:`clone_distribution`). Clone-balanced overlap analogue of the STARTRAC-migr
|
|
78
|
+
index (Zhang et al., *Nature* 2018) at clone level.
|
|
79
|
+
|
|
80
|
+
Every retained clone has total weight one regardless of size. The sum
|
|
81
|
+
increases with the number of retained clones, and is not a movement
|
|
82
|
+
probability. It is sensitive to ``min_clone_size`` and uneven cell sampling
|
|
83
|
+
between groups; compare values only within one dataset, not across
|
|
84
|
+
cohorts.
|
|
85
|
+
|
|
86
|
+
Returns
|
|
87
|
+
-------
|
|
88
|
+
Symmetric square DataFrame (rows and columns = ``group_key`` values);
|
|
89
|
+
the diagonal is ``sum_c p[c, g]**2``, the within-group clone
|
|
90
|
+
concentration.
|
|
91
|
+
"""
|
|
92
|
+
return _pairwise_index(adata, clone_key, group_key, min_clone_size)
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def transition_index(
|
|
96
|
+
adata,
|
|
97
|
+
*,
|
|
98
|
+
clone_key: str = "clone_id",
|
|
99
|
+
state_key: str,
|
|
100
|
+
min_clone_size: int = 2,
|
|
101
|
+
) -> pd.DataFrame:
|
|
102
|
+
"""Pairwise state transition index (STARTRAC-tran analogue).
|
|
103
|
+
|
|
104
|
+
Same formula as :func:`migration_index` applied to cell states instead of
|
|
105
|
+
groups:
|
|
106
|
+
|
|
107
|
+
.. math::
|
|
108
|
+
|
|
109
|
+
\\mathrm{tran}(s_1, s_2) = \\sum_c p_{c,s_1} \\cdot p_{c,s_2}
|
|
110
|
+
|
|
111
|
+
where ``p[c, s]`` is the fraction of clone ``c``'s cells in state ``s``.
|
|
112
|
+
High off-diagonal values indicate clones spanning both states (STARTRAC,
|
|
113
|
+
Zhang et al., *Nature* 2018). The same caveats apply: the index mixes
|
|
114
|
+
the number of retained clones with their state overlap and is sensitive
|
|
115
|
+
to ``min_clone_size``; it does not infer direction or transition rates.
|
|
116
|
+
|
|
117
|
+
Returns
|
|
118
|
+
-------
|
|
119
|
+
Symmetric square DataFrame (rows and columns = ``state_key`` values).
|
|
120
|
+
"""
|
|
121
|
+
return _pairwise_index(adata, clone_key, state_key, min_clone_size)
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def expansion_index(
|
|
125
|
+
adata,
|
|
126
|
+
*,
|
|
127
|
+
clone_key: str = "clone_id",
|
|
128
|
+
group_key: str,
|
|
129
|
+
) -> pd.Series:
|
|
130
|
+
"""Per-group clonal expansion index (STARTRAC-expa analogue).
|
|
131
|
+
|
|
132
|
+
.. math::
|
|
133
|
+
|
|
134
|
+
\\mathrm{expa}(g) = 1 - \\frac{H_g}{\\log n_g}
|
|
135
|
+
|
|
136
|
+
where ``H_g`` is the Shannon entropy (natural log) of the clone-size
|
|
137
|
+
distribution within group ``g`` and ``n_g`` is the number of distinct
|
|
138
|
+
clones in ``g`` (STARTRAC, Zhang et al., *Nature* 2018). Ranges from 0
|
|
139
|
+
(all clones equal size, no expansion) towards 1 (one clone dominates).
|
|
140
|
+
Groups with a single clone are defined as 0 (the normalized entropy is
|
|
141
|
+
undefined for ``n_g == 1``). Cells missing ``clone_key`` or ``group_key``
|
|
142
|
+
are excluded; no minimum clone size is applied, matching the original
|
|
143
|
+
definition.
|
|
144
|
+
|
|
145
|
+
Returns
|
|
146
|
+
-------
|
|
147
|
+
Series indexed by ``group_key`` values, name ``"expansion_index"``.
|
|
148
|
+
"""
|
|
149
|
+
_require_columns(adata, (clone_key, group_key))
|
|
150
|
+
|
|
151
|
+
df = adata.obs[[clone_key, group_key]].dropna()
|
|
152
|
+
out: dict = {}
|
|
153
|
+
for group, sub in df.groupby(group_key, observed=True):
|
|
154
|
+
sizes = sub.groupby(clone_key, observed=True).size().to_numpy(dtype=float)
|
|
155
|
+
n_clones = len(sizes)
|
|
156
|
+
if n_clones <= 1:
|
|
157
|
+
out[group] = 0.0
|
|
158
|
+
continue
|
|
159
|
+
p = sizes / sizes.sum()
|
|
160
|
+
h = float(-(p * np.log(p)).sum())
|
|
161
|
+
out[group] = 1.0 - h / np.log(n_clones)
|
|
162
|
+
|
|
163
|
+
s = pd.Series(out, name="expansion_index", dtype=float)
|
|
164
|
+
s.index.name = group_key
|
|
165
|
+
return s
|