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