threadfin 4.6.0__tar.gz → 4.6.2__tar.gz
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-4.6.0 → threadfin-4.6.2}/PKG-INFO +36 -13
- {threadfin-4.6.0 → threadfin-4.6.2}/README.md +34 -12
- {threadfin-4.6.0 → threadfin-4.6.2}/pyproject.toml +4 -2
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_v4_core.py +58 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/__init__.py +1 -1
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/api.py +122 -42
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/core.py +5 -2
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/dandelion.py +4 -4
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin.egg-info/PKG-INFO +36 -13
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin.egg-info/requires.txt +1 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/LICENSE +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/setup.cfg +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_api_reference.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_association_strata.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_bcrgraph_clones.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_bone_marrow_design.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_case_study_signatures.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_clone_state_sharing.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_clones_v3.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_dandelion_adapter.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_dandelion_seed.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_density.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_ebv_contig_matching.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_export.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_geneset_and_export.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_integrate.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_io.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_maptune.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_memory_reference.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_migration.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_parallel_and_robustness.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_phylo.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_profile_reproducibility.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_programs.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_read_paths.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_reclustering_presets.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_release_metadata.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_result_plots.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_sequence_v2.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_specificity.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_statistical_properties.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_threadfin.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_user_inputs.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/_dandelion_worker.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/_utils.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/bcrgraph.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/clones.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/density.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/dynamics.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/export.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/expression.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/heritability.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/integrate.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/io.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/maptune.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/metrics.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/migration.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/phylo.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/plotting.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/pp.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/profiles.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/programmes.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/programs.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/reclustering.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/sequence.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/simulate.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/specificity.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/stats.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/tl.py +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin.egg-info/SOURCES.txt +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin.egg-info/dependency_links.txt +0 -0
- {threadfin-4.6.0 → threadfin-4.6.2}/threadfin.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: threadfin
|
|
3
|
-
Version: 4.6.
|
|
3
|
+
Version: 4.6.2
|
|
4
4
|
Summary: Relationships between B-cell clones from paired single-cell RNA and BCR sequencing: clone embeddings, clonal coherence, clonal programmes, clone-level tests and clonal memory
|
|
5
5
|
Author-email: Chen Satoshi <103236530+Reynold4k@users.noreply.github.com>
|
|
6
6
|
License: MIT
|
|
@@ -39,6 +39,7 @@ Requires-Dist: harmonypy<2,>=0.0.9; platform_system == "Windows"
|
|
|
39
39
|
Provides-Extra: dandelion
|
|
40
40
|
Requires-Dist: sc-dandelion<1,>=0.5.7; extra == "dandelion"
|
|
41
41
|
Requires-Dist: matplotlib<3.9,>=3.7; python_version < "3.13" and extra == "dandelion"
|
|
42
|
+
Requires-Dist: scanpy<1.13,>=1.10; extra == "dandelion"
|
|
42
43
|
Provides-Extra: seq
|
|
43
44
|
Requires-Dist: parasail>=1.3; extra == "seq"
|
|
44
45
|
Provides-Extra: data
|
|
@@ -67,6 +68,7 @@ Dynamic: license-file
|
|
|
67
68
|
<a href="https://www.python.org"><img src="https://img.shields.io/badge/python-3.10%20%E2%80%93%203.14-blue.svg" alt="Python 3.10 to 3.14"></a>
|
|
68
69
|
<a href="https://pypi.org/project/threadfin/"><img src="https://img.shields.io/pypi/v/threadfin.svg" alt="PyPI version"></a>
|
|
69
70
|
<a href="https://github.com/Reynold4k/Threadfin/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
|
|
71
|
+
<a href="https://doi.org/10.5281/zenodo.23824521"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.23824521.svg" alt="DOI 10.5281/zenodo.23824521"></a>
|
|
70
72
|
</p>
|
|
71
73
|
|
|
72
74
|
Threadfin takes paired single-cell RNA and receptor (BCR or TCR) sequencing and describes every clone by the
|
|
@@ -116,6 +118,17 @@ receptor genes, estimates one profile per clone with two or more cells, tests cl
|
|
|
116
118
|
clone map and looks for clonal programmes. On the 16 public datasets tested (884 to 206,000 cells) it took about 1
|
|
117
119
|
to 11 minutes with 8 cores ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
|
|
118
120
|
|
|
121
|
+
**No data at hand?** A simulated repertoire with a known answer already has clone ids and an embedding. Run it
|
|
122
|
+
instead of the call above, and step 3 works as written, in a minute or two
|
|
123
|
+
([Tutorial 1](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md)):
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
import threadfin as tf
|
|
127
|
+
|
|
128
|
+
adata = tf.sim.simulate_repertoire()
|
|
129
|
+
result = tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")
|
|
130
|
+
```
|
|
131
|
+
|
|
119
132
|
### 3. Read the results
|
|
120
133
|
|
|
121
134
|
```python
|
|
@@ -157,9 +170,11 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
|
|
|
157
170
|
either way. Random draws follow the order of the cells, so the same cells in another order can give different
|
|
158
171
|
programmes; sort them first (`adata = adata[adata.obs_names.sort_values()].copy()`) when results must not
|
|
159
172
|
depend on the order.
|
|
160
|
-
* **
|
|
161
|
-
|
|
162
|
-
`tf.
|
|
173
|
+
* **Saving and reloading**: `adata.write_h5ad(...)` keeps the record of the run, and
|
|
174
|
+
`tf.ThreadfinResult.from_adata(anndata.read_h5ad(...))` gives the run's result back, with the same summary, also
|
|
175
|
+
after further `tf.tl` calls on the same AnnData.
|
|
176
|
+
* **Jupyter**: start the notebook with `%matplotlib inline`. With matplotlib older than 3.9 (which the Dandelion
|
|
177
|
+
extra installs on Python 3.10–3.12), the first figure of a session otherwise appears one cell late, or not at all.
|
|
163
178
|
|
|
164
179
|
### Run time and memory
|
|
165
180
|
|
|
@@ -184,11 +199,14 @@ about an hour for a million simulated cells on 8 cores
|
|
|
184
199
|
| Tutorial | What it covers |
|
|
185
200
|
|---|---|
|
|
186
201
|
| [1 — Getting started](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md) | the whole analysis on simulated data in a minute, with every output explained |
|
|
187
|
-
| [2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results: quality control, several samples and donors, clone calling, T cells, troubleshooting |
|
|
202
|
+
| [2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results: quality control, several samples and donors, clone calling, T cells, troubleshooting; every step can be run on the public data of Tutorial 5 |
|
|
188
203
|
| [3 — The clone map](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md) | automatic and hand-set layouts, and how to check a map |
|
|
189
204
|
| [4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
|
|
190
205
|
| [5 — From GEO to results (notebook)](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) | a published dataset (GSE287123) end to end: download, hashtag demultiplexing, clones, embedding, Threadfin and interpretation; executed in a fresh environment before every release (about 6 minutes on 8 cores) |
|
|
191
206
|
|
|
207
|
+
New in 4.6.2: the result of `tf.run` stays the run's own after later `tf.tl` calls on the same AnnData, also when
|
|
208
|
+
it is rebuilt from a saved file with `ThreadfinResult.from_adata`; every step of Tutorial 2 can be followed on the
|
|
209
|
+
public data of Tutorial 5. Results are unchanged.
|
|
192
210
|
New in 4.6.0: `strata_key=` names the sampling unit within which the coherence test shuffles clone labels when it
|
|
193
211
|
is finer than the context (`sample_key`); `composition_weight="clones"` describes each programme by its average
|
|
194
212
|
clone; the summary states the excess of clonal coherence over shuffled labels, the strata used and the order of
|
|
@@ -268,7 +286,7 @@ manuscript — status, datasets, every analysis and a benchmark against related
|
|
|
268
286
|
* **Model-antigen germinal centres** (Merkenschlager *et al.*, *Nature* 2025): the main axis of variation
|
|
269
287
|
between clone profiles follows recent division in two cohorts whose sequencing libraries are crossed; a
|
|
270
288
|
library effect would push the two cohorts in opposite directions, and their division directions agree
|
|
271
|
-
(cosine similarity 0.
|
|
289
|
+
(cosine similarity 0.90). Antigen-bait and dark-zone gates are also associated with clone profiles but were
|
|
272
290
|
each sequenced in their own library.
|
|
273
291
|
|
|
274
292
|
## A clone embedding that holds together
|
|
@@ -285,9 +303,12 @@ layout is chosen to stay connected, a connected map is not evidence of a continu
|
|
|
285
303
|
is judged from the programmes, their stability and the tests, which use the profiles.
|
|
286
304
|
|
|
287
305
|
```python
|
|
288
|
-
tf.tl.embed_clones(adata) # automatic (default)
|
|
306
|
+
tf.tl.embed_clones(adata) # automatic (default), after tf.run or tf.tl.clone_profiles
|
|
289
307
|
tf.tl.embed_clones(adata, n_neighbors=30, min_dist=0.3) # by hand
|
|
290
|
-
|
|
308
|
+
|
|
309
|
+
prof = adata.uns["threadfin"]["profiles"] # the clone profiles and the map drawn last
|
|
310
|
+
xy = prof["clone_table"][["x", "y"]].dropna()
|
|
311
|
+
tf.tl.map_quality(prof["features"].loc[xy.index], xy.to_numpy()) # score any clone map: profiles, coordinates
|
|
291
312
|
```
|
|
292
313
|
|
|
293
314
|
## How it works
|
|
@@ -328,12 +349,14 @@ The full description, with references, is in [Methods](https://github.com/Reynol
|
|
|
328
349
|
| [Technical validation](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/README.md) | the tutorials on 16 public datasets, sensitivity to clone calling and embedding, power, a million cells, T cells |
|
|
329
350
|
| [Figure gallery](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/tutorial_path/figures/README.md) | every figure Threadfin draws, for each of the 16 public datasets of the technical validation |
|
|
330
351
|
|
|
331
|
-
##
|
|
352
|
+
## How to cite
|
|
332
353
|
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
354
|
+
Please cite Threadfin as in [CITATION.cff](https://github.com/Reynold4k/Threadfin/blob/main/CITATION.cff) (on
|
|
355
|
+
GitHub: "Cite this repository"), with its Zenodo DOI
|
|
356
|
+
[10.5281/zenodo.23824521](https://doi.org/10.5281/zenodo.23824521), which leads to the latest version;
|
|
357
|
+
`result.methods()` names the version you used. A manuscript is in preparation. Please also cite the tools
|
|
358
|
+
Threadfin builds on: Dandelion (Suo *et al.*, *Nat. Biotechnol.* 2024) for clone definition, Scanpy (Wolf
|
|
359
|
+
*et al.*, *Genome Biol.* 2018) and UMAP (McInnes *et al.*, *J. Open Source Softw.* 2018).
|
|
337
360
|
|
|
338
361
|
## How Threadfin compares with related tools
|
|
339
362
|
|
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
<a href="https://www.python.org"><img src="https://img.shields.io/badge/python-3.10%20%E2%80%93%203.14-blue.svg" alt="Python 3.10 to 3.14"></a>
|
|
14
14
|
<a href="https://pypi.org/project/threadfin/"><img src="https://img.shields.io/pypi/v/threadfin.svg" alt="PyPI version"></a>
|
|
15
15
|
<a href="https://github.com/Reynold4k/Threadfin/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
|
|
16
|
+
<a href="https://doi.org/10.5281/zenodo.23824521"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.23824521.svg" alt="DOI 10.5281/zenodo.23824521"></a>
|
|
16
17
|
</p>
|
|
17
18
|
|
|
18
19
|
Threadfin takes paired single-cell RNA and receptor (BCR or TCR) sequencing and describes every clone by the
|
|
@@ -62,6 +63,17 @@ receptor genes, estimates one profile per clone with two or more cells, tests cl
|
|
|
62
63
|
clone map and looks for clonal programmes. On the 16 public datasets tested (884 to 206,000 cells) it took about 1
|
|
63
64
|
to 11 minutes with 8 cores ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
|
|
64
65
|
|
|
66
|
+
**No data at hand?** A simulated repertoire with a known answer already has clone ids and an embedding. Run it
|
|
67
|
+
instead of the call above, and step 3 works as written, in a minute or two
|
|
68
|
+
([Tutorial 1](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md)):
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
import threadfin as tf
|
|
72
|
+
|
|
73
|
+
adata = tf.sim.simulate_repertoire()
|
|
74
|
+
result = tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")
|
|
75
|
+
```
|
|
76
|
+
|
|
65
77
|
### 3. Read the results
|
|
66
78
|
|
|
67
79
|
```python
|
|
@@ -103,9 +115,11 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
|
|
|
103
115
|
either way. Random draws follow the order of the cells, so the same cells in another order can give different
|
|
104
116
|
programmes; sort them first (`adata = adata[adata.obs_names.sort_values()].copy()`) when results must not
|
|
105
117
|
depend on the order.
|
|
106
|
-
* **
|
|
107
|
-
|
|
108
|
-
`tf.
|
|
118
|
+
* **Saving and reloading**: `adata.write_h5ad(...)` keeps the record of the run, and
|
|
119
|
+
`tf.ThreadfinResult.from_adata(anndata.read_h5ad(...))` gives the run's result back, with the same summary, also
|
|
120
|
+
after further `tf.tl` calls on the same AnnData.
|
|
121
|
+
* **Jupyter**: start the notebook with `%matplotlib inline`. With matplotlib older than 3.9 (which the Dandelion
|
|
122
|
+
extra installs on Python 3.10–3.12), the first figure of a session otherwise appears one cell late, or not at all.
|
|
109
123
|
|
|
110
124
|
### Run time and memory
|
|
111
125
|
|
|
@@ -130,11 +144,14 @@ about an hour for a million simulated cells on 8 cores
|
|
|
130
144
|
| Tutorial | What it covers |
|
|
131
145
|
|---|---|
|
|
132
146
|
| [1 — Getting started](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md) | the whole analysis on simulated data in a minute, with every output explained |
|
|
133
|
-
| [2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results: quality control, several samples and donors, clone calling, T cells, troubleshooting |
|
|
147
|
+
| [2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results: quality control, several samples and donors, clone calling, T cells, troubleshooting; every step can be run on the public data of Tutorial 5 |
|
|
134
148
|
| [3 — The clone map](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md) | automatic and hand-set layouts, and how to check a map |
|
|
135
149
|
| [4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
|
|
136
150
|
| [5 — From GEO to results (notebook)](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) | a published dataset (GSE287123) end to end: download, hashtag demultiplexing, clones, embedding, Threadfin and interpretation; executed in a fresh environment before every release (about 6 minutes on 8 cores) |
|
|
137
151
|
|
|
152
|
+
New in 4.6.2: the result of `tf.run` stays the run's own after later `tf.tl` calls on the same AnnData, also when
|
|
153
|
+
it is rebuilt from a saved file with `ThreadfinResult.from_adata`; every step of Tutorial 2 can be followed on the
|
|
154
|
+
public data of Tutorial 5. Results are unchanged.
|
|
138
155
|
New in 4.6.0: `strata_key=` names the sampling unit within which the coherence test shuffles clone labels when it
|
|
139
156
|
is finer than the context (`sample_key`); `composition_weight="clones"` describes each programme by its average
|
|
140
157
|
clone; the summary states the excess of clonal coherence over shuffled labels, the strata used and the order of
|
|
@@ -214,7 +231,7 @@ manuscript — status, datasets, every analysis and a benchmark against related
|
|
|
214
231
|
* **Model-antigen germinal centres** (Merkenschlager *et al.*, *Nature* 2025): the main axis of variation
|
|
215
232
|
between clone profiles follows recent division in two cohorts whose sequencing libraries are crossed; a
|
|
216
233
|
library effect would push the two cohorts in opposite directions, and their division directions agree
|
|
217
|
-
(cosine similarity 0.
|
|
234
|
+
(cosine similarity 0.90). Antigen-bait and dark-zone gates are also associated with clone profiles but were
|
|
218
235
|
each sequenced in their own library.
|
|
219
236
|
|
|
220
237
|
## A clone embedding that holds together
|
|
@@ -231,9 +248,12 @@ layout is chosen to stay connected, a connected map is not evidence of a continu
|
|
|
231
248
|
is judged from the programmes, their stability and the tests, which use the profiles.
|
|
232
249
|
|
|
233
250
|
```python
|
|
234
|
-
tf.tl.embed_clones(adata) # automatic (default)
|
|
251
|
+
tf.tl.embed_clones(adata) # automatic (default), after tf.run or tf.tl.clone_profiles
|
|
235
252
|
tf.tl.embed_clones(adata, n_neighbors=30, min_dist=0.3) # by hand
|
|
236
|
-
|
|
253
|
+
|
|
254
|
+
prof = adata.uns["threadfin"]["profiles"] # the clone profiles and the map drawn last
|
|
255
|
+
xy = prof["clone_table"][["x", "y"]].dropna()
|
|
256
|
+
tf.tl.map_quality(prof["features"].loc[xy.index], xy.to_numpy()) # score any clone map: profiles, coordinates
|
|
237
257
|
```
|
|
238
258
|
|
|
239
259
|
## How it works
|
|
@@ -274,12 +294,14 @@ The full description, with references, is in [Methods](https://github.com/Reynol
|
|
|
274
294
|
| [Technical validation](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/README.md) | the tutorials on 16 public datasets, sensitivity to clone calling and embedding, power, a million cells, T cells |
|
|
275
295
|
| [Figure gallery](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/tutorial_path/figures/README.md) | every figure Threadfin draws, for each of the 16 public datasets of the technical validation |
|
|
276
296
|
|
|
277
|
-
##
|
|
297
|
+
## How to cite
|
|
278
298
|
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
299
|
+
Please cite Threadfin as in [CITATION.cff](https://github.com/Reynold4k/Threadfin/blob/main/CITATION.cff) (on
|
|
300
|
+
GitHub: "Cite this repository"), with its Zenodo DOI
|
|
301
|
+
[10.5281/zenodo.23824521](https://doi.org/10.5281/zenodo.23824521), which leads to the latest version;
|
|
302
|
+
`result.methods()` names the version you used. A manuscript is in preparation. Please also cite the tools
|
|
303
|
+
Threadfin builds on: Dandelion (Suo *et al.*, *Nat. Biotechnol.* 2024) for clone definition, Scanpy (Wolf
|
|
304
|
+
*et al.*, *Genome Biol.* 2018) and UMAP (McInnes *et al.*, *J. Open Source Softw.* 2018).
|
|
283
305
|
|
|
284
306
|
## How Threadfin compares with related tools
|
|
285
307
|
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "threadfin"
|
|
7
|
-
version = "4.6.
|
|
7
|
+
version = "4.6.2"
|
|
8
8
|
description = "Relationships between B-cell clones from paired single-cell RNA and BCR sequencing: clone embeddings, clonal coherence, clonal programmes, clone-level tests and clonal memory"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.10"
|
|
@@ -50,7 +50,9 @@ dependencies = [
|
|
|
50
50
|
# matplotlib 3.9. Up to Python 3.12 the extra keeps the validated matplotlib < 3.9; matplotlib < 3.9 has no wheels
|
|
51
51
|
# for Python 3.13+, where importing threadfin restores get_cmap for Dandelion (clone calls verified identical).
|
|
52
52
|
# sc-dandelion 1.0 (2026-10-25) calls clones differently and is not yet validated, hence < 1.
|
|
53
|
-
|
|
53
|
+
# scanpy 1.13.0 (2026-11-13, Python 3.13+) removed scanpy.plotting._tools, which sc-dandelion 0.5.7 imports, hence
|
|
54
|
+
# scanpy < 1.13 with this extra; without it, Threadfin itself works with scanpy 1.13.
|
|
55
|
+
dandelion = ["sc-dandelion>=0.5.7,<1", "matplotlib>=3.7,<3.9; python_version < '3.13'", "scanpy>=1.10,<1.13"]
|
|
54
56
|
seq = ["parasail>=1.3"] # faster CDR3 alignment for the legacy v3 functions
|
|
55
57
|
data = ["mudata>=0.3", "awkward>=2"] # reading scirpy/MuData example data
|
|
56
58
|
test = ["pytest>=7", "pytest-cov>=4"]
|
|
@@ -327,6 +327,64 @@ def test_a_run_without_programmes_leaves_none_from_an_earlier_run(sim):
|
|
|
327
327
|
assert tf.ThreadfinResult.from_adata(ad).summary() == second.summary()
|
|
328
328
|
|
|
329
329
|
|
|
330
|
+
def test_the_result_stays_the_runs_own_after_later_calls(tmp_path):
|
|
331
|
+
"""Later calls of tl functions replace entries of uns['threadfin'] that run() wrote (a label test of the same
|
|
332
|
+
label, coherence, memory, the clone map, programmes). The result, in memory and rebuilt from the saved file
|
|
333
|
+
before or after those calls, keeps the run's tables, summary and Methods paragraph."""
|
|
334
|
+
import anndata
|
|
335
|
+
|
|
336
|
+
ad = tf.sim.simulate_repertoire(n_clones=1200, clone_size_exponent=1.9, n_timepoints=2, memory=0.8,
|
|
337
|
+
random_state=3)
|
|
338
|
+
with warnings.catch_warnings():
|
|
339
|
+
warnings.simplefilter("ignore")
|
|
340
|
+
result = tf.run(ad, donor_key="donor", sample_key="context", basis="X_pca", state_key="true_state",
|
|
341
|
+
test=["true_programme"], time_key="timepoint", map_n_neighbors=15, map_min_dist=0.5,
|
|
342
|
+
n_perm=10, n_boot=6, verbose=False)
|
|
343
|
+
assert result.programmes.shape[0] > 1 and result.memory is not None and "true_programme" in result.tests
|
|
344
|
+
summary, methods = result.summary(), result.methods()
|
|
345
|
+
record = ad.uns["threadfin"]["run"]
|
|
346
|
+
assert list(record["profile_tests"]) == ["true_programme"] and list(record["tests"]) == ["true_programme"]
|
|
347
|
+
ad.write_h5ad(tmp_path / "run.h5ad")
|
|
348
|
+
# a file of Threadfin 4.6.0 or 4.6.1 has no copy of the results: its entries are read as they are
|
|
349
|
+
old = ad.copy()
|
|
350
|
+
del old.uns["threadfin"]["run"]["results"]
|
|
351
|
+
assert tf.ThreadfinResult.from_adata(old).summary() == summary
|
|
352
|
+
assert tf.ThreadfinResult.from_adata(old).methods() == methods
|
|
353
|
+
|
|
354
|
+
with warnings.catch_warnings():
|
|
355
|
+
warnings.simplefilter("ignore")
|
|
356
|
+
tf.tl.profile_association(ad, "true_programme", how="fraction:G0", n_perm=50, verbose=False)
|
|
357
|
+
tf.tl.association_test(ad, "true_programme", size_strata=False, n_perm=50, verbose=False)
|
|
358
|
+
tf.tl.clonal_coherence(ad, strata_key="donor", n_perm=5, verbose=False)
|
|
359
|
+
tf.tl.clonal_memory(ad, "timepoint", reference="all", noise="pooled", n_null=20, n_boot=20, verbose=False)
|
|
360
|
+
tf.tl.embed_clones(ad, n_neighbors=10, min_dist=0.05, verbose=False)
|
|
361
|
+
tf.tl.find_programmes(ad, resolution=1.0, n_boot=0, stability_threshold=0.5, verbose=False)
|
|
362
|
+
th = ad.uns["threadfin"]
|
|
363
|
+
assert th["profile_associations"]["true_programme"]["r2"] != result.profile_tests["true_programme"]["r2"]
|
|
364
|
+
assert th["coherence"]["n_perm"] == 5 and th["programmes"]["params"]["stability_threshold"] == 0.5
|
|
365
|
+
ad.write_h5ad(tmp_path / "later.h5ad")
|
|
366
|
+
|
|
367
|
+
assert result.summary() == summary and result.methods() == methods
|
|
368
|
+
for again in (tf.ThreadfinResult.from_adata(anndata.read_h5ad(tmp_path / "run.h5ad")),
|
|
369
|
+
tf.ThreadfinResult.from_adata(anndata.read_h5ad(tmp_path / "later.h5ad")),
|
|
370
|
+
tf.ThreadfinResult.from_adata(ad)):
|
|
371
|
+
assert again.summary() == summary
|
|
372
|
+
assert again.methods() == methods
|
|
373
|
+
assert again.coherence["icc"] == result.coherence["icc"]
|
|
374
|
+
assert again.coherence["p_value"] == result.coherence["p_value"]
|
|
375
|
+
assert again.programmes.index.astype(str).tolist() == result.programmes.index.astype(str).tolist()
|
|
376
|
+
assert np.allclose(again.programmes.to_numpy(float), result.programmes.to_numpy(float))
|
|
377
|
+
assert np.allclose(again.composition.to_numpy(float), result.composition.to_numpy(float))
|
|
378
|
+
assert again.clones.index.equals(result.clones.index)
|
|
379
|
+
assert np.allclose(again.clones[["n_cells", "reliability", "x", "y"]].to_numpy(float),
|
|
380
|
+
result.clones[["n_cells", "reliability", "x", "y"]].to_numpy(float))
|
|
381
|
+
assert again.clones["clone_programme"].astype(object).equals(result.clones["clone_programme"].astype(object))
|
|
382
|
+
assert again.profile_tests["true_programme"]["r2"] == result.profile_tests["true_programme"]["r2"]
|
|
383
|
+
assert np.allclose(again.tests["true_programme"]["pvalue"], result.tests["true_programme"]["pvalue"])
|
|
384
|
+
assert again.tests["true_programme"].attrs["size_bins"] is not None
|
|
385
|
+
assert again.memory["memory_index"] == result.memory["memory_index"]
|
|
386
|
+
|
|
387
|
+
|
|
330
388
|
def test_run_warns_once_about_a_sample_level_label(sim):
|
|
331
389
|
"""Both label tests check a label fixed within each sample; run() says so once, not once per test."""
|
|
332
390
|
ad = sim.copy()
|
|
@@ -39,7 +39,7 @@ from .programs import community_markers, community_score # noqa: E402
|
|
|
39
39
|
from .reclustering import reclustering_presets # noqa: E402
|
|
40
40
|
from .specificity import annotate_specificity, specificity_enrichment # noqa: E402
|
|
41
41
|
|
|
42
|
-
__version__ = "4.6.
|
|
42
|
+
__version__ = "4.6.2"
|
|
43
43
|
__all__ = [
|
|
44
44
|
"ThreadfinResult",
|
|
45
45
|
"DensityResult",
|
|
@@ -24,6 +24,7 @@ Every step is also available on its own in :mod:`threadfin.tl`.
|
|
|
24
24
|
|
|
25
25
|
from __future__ import annotations
|
|
26
26
|
|
|
27
|
+
import copy
|
|
27
28
|
import re
|
|
28
29
|
import warnings
|
|
29
30
|
from dataclasses import dataclass, field
|
|
@@ -150,12 +151,43 @@ def _odds(v: float) -> str:
|
|
|
150
151
|
return "> 100" if v > 100 else "< 0.01" if v < 0.01 else f"{v:.2f}"
|
|
151
152
|
|
|
152
153
|
|
|
154
|
+
def _no_programmes() -> pd.DataFrame:
|
|
155
|
+
"""The programme table of a run that made no programmes."""
|
|
156
|
+
return pd.DataFrame(columns=["n_clones", "n_cells", "mean_reliability", "mean_confidence", "stability"])
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def _report_entries(adata, programmes: pd.DataFrame) -> dict:
|
|
160
|
+
"""The entries of ``adata.uns['threadfin']`` that :meth:`ThreadfinResult.summary` and
|
|
161
|
+
:meth:`ThreadfinResult.methods` read, as :func:`run` leaves them: variance components and settings of the
|
|
162
|
+
profiles, the clone-map settings, the programme settings and split tests, and the embedding settings. Later
|
|
163
|
+
calls of :mod:`threadfin.tl` functions replace the entries themselves."""
|
|
164
|
+
th = adata.uns["threadfin"]
|
|
165
|
+
prof = th["profiles"]
|
|
166
|
+
out = {"profiles": {
|
|
167
|
+
"variance_components": prof["variance_components"],
|
|
168
|
+
"params": {k: v for k, v in prof["params"].items() if k not in ("input_sha256", "feature_rng_state")},
|
|
169
|
+
}}
|
|
170
|
+
if prof.get("map_params") is not None:
|
|
171
|
+
out["profiles"]["map_params"] = {k: v for k, v in prof["map_params"].items() if k not in ("attempts", "tuning")}
|
|
172
|
+
if not programmes.empty and th.get("programmes") is not None:
|
|
173
|
+
out["programmes"] = {k: th["programmes"][k] for k in ("params", "split_tests")}
|
|
174
|
+
if th.get("prepare_embedding") is not None:
|
|
175
|
+
out["prepare_embedding"] = th["prepare_embedding"]
|
|
176
|
+
return out
|
|
177
|
+
|
|
178
|
+
|
|
153
179
|
# --------------------------------------------------------------------------- result object
|
|
154
180
|
|
|
155
181
|
|
|
156
182
|
@dataclass
|
|
157
183
|
class ThreadfinResult:
|
|
158
|
-
"""Everything :func:`run` computed. Print :meth:`summary` for a readable report.
|
|
184
|
+
"""Everything :func:`run` computed. Print :meth:`summary` for a readable report.
|
|
185
|
+
|
|
186
|
+
The result keeps what the run produced. Later calls of :mod:`threadfin.tl` functions on the same AnnData (for
|
|
187
|
+
example :func:`threadfin.tl.profile_association` with another ``how=``) store their own results in ``adata``
|
|
188
|
+
and change neither the tables of the result nor its :meth:`summary` and :meth:`methods`. :meth:`plot` draws
|
|
189
|
+
the clone map and the programmes stored in ``adata``. :meth:`from_adata` rebuilds the result after saving.
|
|
190
|
+
"""
|
|
159
191
|
|
|
160
192
|
adata: object = field(repr=False)
|
|
161
193
|
coherence: dict = field(repr=False)
|
|
@@ -168,6 +200,9 @@ class ThreadfinResult:
|
|
|
168
200
|
settings: dict = field(default_factory=dict, repr=False)
|
|
169
201
|
#: analyses that were requested but could not be run on these data, with the reason
|
|
170
202
|
skipped: dict = field(default_factory=dict, repr=False)
|
|
203
|
+
#: the record of the run, as written to ``adata.uns['threadfin']['run']``: settings, package versions and a
|
|
204
|
+
#: copy of everything the run reported, from which :meth:`summary` and :meth:`methods` are written
|
|
205
|
+
record: dict = field(default_factory=dict, repr=False)
|
|
171
206
|
|
|
172
207
|
def __repr__(self) -> str:
|
|
173
208
|
n_prog = self.programmes.shape[0]
|
|
@@ -175,13 +210,25 @@ class ThreadfinResult:
|
|
|
175
210
|
return (f"ThreadfinResult(clonal ICC={self.coherence['icc']:.3f}, "
|
|
176
211
|
f"p={self.coherence['p_value']:.3g}, programmes={n_prog}, clones in programmes={n_cl})")
|
|
177
212
|
|
|
213
|
+
def _uns(self) -> dict:
|
|
214
|
+
"""The entries of ``adata.uns['threadfin']`` that :meth:`summary` and :meth:`methods` read: as :func:`run`
|
|
215
|
+
left them (Threadfin 4.6.2 and later), else as they are now."""
|
|
216
|
+
saved = (self.record or {}).get("results", {}).get("uns")
|
|
217
|
+
return saved if saved is not None else self.adata.uns.get("threadfin", {})
|
|
218
|
+
|
|
178
219
|
@classmethod
|
|
179
|
-
def from_adata(cls, adata) ->
|
|
220
|
+
def from_adata(cls, adata) -> ThreadfinResult:
|
|
180
221
|
"""The result of :func:`run`, rebuilt from the AnnData it wrote to (for example after
|
|
181
222
|
``write_h5ad`` and ``read_h5ad``), so that :meth:`summary`, :meth:`methods` and :meth:`plot` work again.
|
|
182
223
|
|
|
183
|
-
|
|
184
|
-
|
|
224
|
+
:func:`run` keeps a copy of everything it reported in ``adata.uns['threadfin']['run']``. The rebuilt
|
|
225
|
+
result is therefore the run's own, also after later calls of :mod:`threadfin.tl` functions on the same
|
|
226
|
+
AnnData: its tables are those of the run, and :meth:`summary` and :meth:`methods` give the text they gave
|
|
227
|
+
right after the run. :meth:`plot` draws the clone map and the programmes stored in ``adata``.
|
|
228
|
+
|
|
229
|
+
Files written by Threadfin 4.6.0 and 4.6.1 hold no such copy. Their results are read from the entries of
|
|
230
|
+
``adata.uns['threadfin']``, where a later call of a :mod:`threadfin.tl` function (for example the same
|
|
231
|
+
label test with the same label) replaces the one :func:`run` made.
|
|
185
232
|
"""
|
|
186
233
|
from .programmes import programme_composition
|
|
187
234
|
|
|
@@ -194,34 +241,47 @@ class ThreadfinResult:
|
|
|
194
241
|
settings = {k: None for k in keys}
|
|
195
242
|
settings.update(dict(record.get("settings", {})))
|
|
196
243
|
skipped = {str(k): str(v) for k, v in dict(record.get("skipped", {})).items()}
|
|
197
|
-
prog = th.get("programmes", {}).get("summary")
|
|
198
|
-
found = "clonal programmes" not in skipped # the recorded run made programmes
|
|
199
|
-
programmes = (prog.copy() if found and isinstance(prog, pd.DataFrame) and "clone_programme" in adata.obs
|
|
200
|
-
else pd.DataFrame(columns=["n_clones", "n_cells", "mean_reliability", "mean_confidence",
|
|
201
|
-
"stability"]))
|
|
202
|
-
composition = None
|
|
203
|
-
if settings["state_key"] and not programmes.empty:
|
|
204
|
-
composition = programme_composition(adata, settings["state_key"],
|
|
205
|
-
weight=settings.get("composition_weight") or "cells")
|
|
206
244
|
labels = lambda key: [str(x) for x in np.atleast_1d(record.get(key, []))] # noqa: E731
|
|
207
|
-
|
|
245
|
+
saved = record.get("results")
|
|
246
|
+
if saved is not None:
|
|
247
|
+
# Threadfin 4.6.2 and later: the run's own copy; the label lists keep the order in which it reported
|
|
248
|
+
prog = saved.get("programmes")
|
|
249
|
+
programmes = prog.copy() if isinstance(prog, pd.DataFrame) else _no_programmes()
|
|
250
|
+
comp = saved.get("composition")
|
|
251
|
+
composition = comp.copy() if isinstance(comp, pd.DataFrame) else None
|
|
252
|
+
coherence, clones = dict(saved["coherence"]), saved["clones"].copy()
|
|
253
|
+
profile_tests = {k: dict(saved["profile_tests"][k]) for k in labels("profile_tests")
|
|
254
|
+
if k in saved.get("profile_tests", {})}
|
|
255
|
+
tests = {k: saved["tests"][k].copy() for k in labels("tests") if k in saved.get("tests", {})}
|
|
256
|
+
memory = dict(saved["memory"]) if "memory" in saved else None
|
|
257
|
+
else:
|
|
258
|
+
# Threadfin 4.6.0 and 4.6.1: the entries as they are now
|
|
259
|
+
prog = th.get("programmes", {}).get("summary")
|
|
260
|
+
found = "clonal programmes" not in skipped # the recorded run made programmes
|
|
261
|
+
programmes = (prog.copy() if found and isinstance(prog, pd.DataFrame) and "clone_programme" in adata.obs
|
|
262
|
+
else _no_programmes())
|
|
263
|
+
composition = None
|
|
264
|
+
if settings["state_key"] and not programmes.empty:
|
|
265
|
+
composition = programme_composition(adata, settings["state_key"],
|
|
266
|
+
weight=settings.get("composition_weight") or "cells")
|
|
267
|
+
coherence, clones = dict(th["coherence"]), th["profiles"]["clone_table"]
|
|
268
|
+
profile_tests = {k: dict(th["profile_associations"][k]) for k in labels("profile_tests")
|
|
269
|
+
if k in th.get("profile_associations", {})}
|
|
270
|
+
tests = {k: th["associations"][k].copy() for k in labels("tests") if k in th.get("associations", {})}
|
|
271
|
+
time_key = settings["time_key"]
|
|
272
|
+
memory = dict(th["memory"][time_key]) if time_key and time_key in th.get("memory", {}) else None
|
|
208
273
|
for k, tab in tests.items(): # DataFrame attributes are not written to h5ad
|
|
209
274
|
tab.attrs.update(dict(record.get("test_attrs", {}).get(k, {})))
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
clones=th["profiles"]["clone_table"], composition=composition,
|
|
214
|
-
tests=tests,
|
|
215
|
-
profile_tests={k: dict(th["profile_associations"][k]) for k in labels("profile_tests")
|
|
216
|
-
if k in th.get("profile_associations", {})},
|
|
217
|
-
memory=(dict(th["memory"][time_key]) if time_key and time_key in th.get("memory", {}) else None),
|
|
218
|
-
settings=settings, skipped=skipped)
|
|
275
|
+
return cls(adata=adata, coherence=coherence, programmes=programmes, clones=clones, composition=composition,
|
|
276
|
+
tests=tests, profile_tests=profile_tests, memory=memory, settings=settings, skipped=skipped,
|
|
277
|
+
record=dict(record))
|
|
219
278
|
|
|
220
279
|
def summary(self) -> str:
|
|
221
280
|
"""Plain-language summary of the results."""
|
|
222
281
|
from .programmes import get_programmes
|
|
223
282
|
|
|
224
283
|
ad, coh = self.adata, self.coherence
|
|
284
|
+
uns = self._uns()
|
|
225
285
|
clone_key = self.settings["clone_key"]
|
|
226
286
|
clones = ad.obs[clone_key].dropna()
|
|
227
287
|
sizes = clones.value_counts()
|
|
@@ -242,7 +302,7 @@ class ThreadfinResult:
|
|
|
242
302
|
if coh["p_value"] >= 0.05:
|
|
243
303
|
lines.append(" Clone identity is not significantly more informative than shuffled labels here, so the "
|
|
244
304
|
"programmes below are descriptive.")
|
|
245
|
-
prof_vc =
|
|
305
|
+
prof_vc = uns["profiles"]["variance_components"]
|
|
246
306
|
from .profiles import VarianceComponents
|
|
247
307
|
|
|
248
308
|
vc = VarianceComponents(np.asarray(prof_vc["sigma2"]), np.asarray(prof_vc["tau2"]),
|
|
@@ -264,12 +324,12 @@ class ThreadfinResult:
|
|
|
264
324
|
lines.append(" No programmes: " + self.skipped.get(
|
|
265
325
|
"clonal programmes", "not enough profiled clones to define programmes in this dataset."))
|
|
266
326
|
elif prog.shape[0] == 1:
|
|
267
|
-
tests = get_programmes(ad).get("split_tests", pd.DataFrame())
|
|
327
|
+
tests = (uns.get("programmes") or get_programmes(ad)).get("split_tests", pd.DataFrame())
|
|
268
328
|
p_root = f" (split test p = {tests['pvalue'].iloc[0]:.2g})" if not tests.empty else ""
|
|
269
329
|
lines.append(f" No distinct programmes: no split of the {int(prog['n_clones'].sum()):,} profiled clones "
|
|
270
330
|
f"into separate groups was significant{p_root}.")
|
|
271
331
|
else:
|
|
272
|
-
params = get_programmes(ad)["params"]
|
|
332
|
+
params = (uns.get("programmes") or get_programmes(ad))["params"]
|
|
273
333
|
n_stable = int((prog["stability"] >= params["stability_threshold"]).sum())
|
|
274
334
|
verb = "is" if n_stable == 1 else "are"
|
|
275
335
|
lines.append(f" {prog.shape[0]} programmes from {int(prog['n_clones'].sum()):,} profiled clones "
|
|
@@ -392,7 +452,7 @@ class ThreadfinResult:
|
|
|
392
452
|
|
|
393
453
|
from . import __version__
|
|
394
454
|
|
|
395
|
-
recorded = dict((self.adata.uns.get("threadfin", {}).get("run") or {}).get("versions") or {})
|
|
455
|
+
recorded = dict((self.record or self.adata.uns.get("threadfin", {}).get("run") or {}).get("versions") or {})
|
|
396
456
|
|
|
397
457
|
def ver(dist):
|
|
398
458
|
if dist in recorded:
|
|
@@ -406,7 +466,7 @@ class ThreadfinResult:
|
|
|
406
466
|
return f"{int(x):,}"
|
|
407
467
|
|
|
408
468
|
ad, st = self.adata, self.settings
|
|
409
|
-
uns =
|
|
469
|
+
uns = self._uns()
|
|
410
470
|
refs = {"threadfin": "Threadfin (https://github.com/Reynold4k/Threadfin)"}
|
|
411
471
|
text = [f"Clonal analyses used Threadfin {recorded.get('threadfin', __version__)} "
|
|
412
472
|
f"(Python {recorded.get('python', platform.python_version())}, "
|
|
@@ -715,7 +775,10 @@ def run(
|
|
|
715
775
|
``obsm['X_pca']`` (replaced by the PCA of the selected genes),
|
|
716
776
|
``var['highly_variable']`` (replaced), ``var['threadfin_receptor_gene']``
|
|
717
777
|
and ``layers['log_norm']`` (normalised, log-transformed counts);
|
|
718
|
-
* ``uns['threadfin']``: every result and the settings that made it
|
|
778
|
+
* ``uns['threadfin']``: every result and the settings that made it, and in
|
|
779
|
+
``uns['threadfin']['run']`` the record of this run with a copy of what it
|
|
780
|
+
reported, from which :meth:`ThreadfinResult.from_adata` rebuilds the
|
|
781
|
+
result after saving.
|
|
719
782
|
|
|
720
783
|
Examples
|
|
721
784
|
--------
|
|
@@ -906,22 +969,39 @@ def run(
|
|
|
906
969
|
skipped[f"clonal memory over '{time_key}'"] = str(e)
|
|
907
970
|
log(f"clonal memory over '{time_key}' skipped: {e}", verbose)
|
|
908
971
|
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
972
|
+
# the run's own copy of the clone table: tl.embed_clones changes the stored table in place
|
|
973
|
+
clones = adata.uns["threadfin"]["profiles"]["clone_table"].copy()
|
|
974
|
+
settings = {"clone_key": clone_key, "donor_key": donor_key, "sample_key": sample_key,
|
|
975
|
+
"strata_key": strata_key or sample_key,
|
|
976
|
+
"state_key": state_key, "composition_weight": composition_weight, "time_key": time_key,
|
|
977
|
+
"basis": basis,
|
|
978
|
+
"representation": representation, "receptor": receptor, "clone_calling": clone_calling,
|
|
979
|
+
"n_perm": int(n_perm), "n_boot": int(n_boot), "random_state": int(random_state)}
|
|
980
|
+
# What this run reported, kept apart from the entries of uns['threadfin'] that later calls of tl functions
|
|
981
|
+
# replace (a label test of the same label, clonal_coherence, find_programmes ...), so that
|
|
982
|
+
# ThreadfinResult.from_adata rebuilds this run's result. The keys before "results" are those of 4.6.0, which
|
|
983
|
+
# earlier versions read.
|
|
984
|
+
results = {"coherence": coherence, "clones": clones, "profile_tests": profile_tests, "tests": tests,
|
|
985
|
+
"uns": _report_entries(adata, programmes)}
|
|
986
|
+
if not programmes.empty:
|
|
987
|
+
results["programmes"] = programmes
|
|
988
|
+
if composition is not None: # h5ad needs text labels; states can be numbers
|
|
989
|
+
results["composition"] = composition.set_axis(composition.index.astype(str), axis=0).set_axis(
|
|
990
|
+
composition.columns.astype(str), axis=1)
|
|
991
|
+
if memory is not None:
|
|
992
|
+
results["memory"] = memory
|
|
993
|
+
record = h5ad_safe({
|
|
994
|
+
"settings": {k: v for k, v in settings.items() if v is not None},
|
|
922
995
|
"skipped": dict(skipped), "profile_tests": list(profile_tests), "tests": list(tests),
|
|
923
996
|
"test_attrs": {k: {a: v for a, v in t.attrs.items() if v is not None} for k, t in tests.items()},
|
|
924
997
|
"versions": _versions(),
|
|
998
|
+
"results": results,
|
|
925
999
|
})
|
|
1000
|
+
get_uns(adata)["run"] = record
|
|
1001
|
+
result = ThreadfinResult(
|
|
1002
|
+
adata=adata, coherence=coherence, programmes=programmes, clones=clones,
|
|
1003
|
+
composition=composition, tests=tests, profile_tests=profile_tests, memory=memory, skipped=skipped,
|
|
1004
|
+
settings=settings, record=copy.deepcopy(record),
|
|
1005
|
+
)
|
|
926
1006
|
log("done. print(result.summary()) for a readable report.", verbose)
|
|
927
1007
|
return result
|
|
@@ -360,8 +360,11 @@ def clonotype_recluster(
|
|
|
360
360
|
clone_adata = AnnData(clone_xy)
|
|
361
361
|
sc.pp.neighbors(clone_adata, n_neighbors=graph_k, use_rep="X",
|
|
362
362
|
metric="euclidean", random_state=cluster_random_state)
|
|
363
|
-
|
|
364
|
-
|
|
363
|
+
with warnings.catch_warnings(): # the historical recipe needs leidenalg; scanpy recommends igraph
|
|
364
|
+
warnings.filterwarnings("ignore", message="(In the future, the default backend for leiden|The `igraph` "
|
|
365
|
+
"implementation of leiden)")
|
|
366
|
+
sc.tl.leiden(clone_adata, resolution=resolution, random_state=cluster_random_state,
|
|
367
|
+
flavor="leidenalg", directed=True, n_iterations=-1)
|
|
365
368
|
labels = clone_adata.obs["leiden"].astype(str).to_numpy()
|
|
366
369
|
else:
|
|
367
370
|
labels = _leiden_on_distances(
|
|
@@ -456,8 +456,8 @@ def define_clones_dandelion(
|
|
|
456
456
|
Python string-hash seed under which Dandelion calls the clones. Dandelion's grouping iterates over Python
|
|
457
457
|
sets, so the clones it calls depend on this seed (see the module notes). ``0`` (default) gives the same
|
|
458
458
|
clones in every Python session, those of Threadfin's documentation and validation records: if this
|
|
459
|
-
session was not started with ``PYTHONHASHSEED=0``, Dandelion runs in a separate Python process
|
|
460
|
-
(about 2 s more per call, to start Python and import Dandelion; the contigs pass through a private
|
|
459
|
+
session was not started with ``PYTHONHASHSEED=0``, Dandelion runs in a separate Python process started
|
|
460
|
+
with it (about 2 s more per call, to start Python and import Dandelion; the contigs pass through a private
|
|
461
461
|
temporary file). Another integer calls the clones under that seed, always in a separate process, to see
|
|
462
462
|
how much they depend on it. ``None`` runs Dandelion in this session whatever its seed, as Threadfin 4.5.3
|
|
463
463
|
and earlier did; clone ids are then reproducible only between sessions started with the same
|
|
@@ -549,8 +549,8 @@ def define_clones_dandelion(
|
|
|
549
549
|
late = (" (setting PYTHONHASHSEED in a running session has no effect)"
|
|
550
550
|
if os.environ.get("PYTHONHASHSEED") == "0" else "")
|
|
551
551
|
log("Dandelion's clone calls depend on Python's string-hash seed, and this session was not started with "
|
|
552
|
-
f"PYTHONHASHSEED=0{late}: Dandelion runs in a separate Python process
|
|
553
|
-
"same in every session")
|
|
552
|
+
f"PYTHONHASHSEED=0{late}: Dandelion runs in a separate Python process started with "
|
|
553
|
+
"PYTHONHASHSEED=0, so the clones are the same in every session")
|
|
554
554
|
elif verbose:
|
|
555
555
|
log(f"Dandelion runs in a separate Python process started with PYTHONHASHSEED={hash_seed} "
|
|
556
556
|
f"(hash_seed={hash_seed})")
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: threadfin
|
|
3
|
-
Version: 4.6.
|
|
3
|
+
Version: 4.6.2
|
|
4
4
|
Summary: Relationships between B-cell clones from paired single-cell RNA and BCR sequencing: clone embeddings, clonal coherence, clonal programmes, clone-level tests and clonal memory
|
|
5
5
|
Author-email: Chen Satoshi <103236530+Reynold4k@users.noreply.github.com>
|
|
6
6
|
License: MIT
|
|
@@ -39,6 +39,7 @@ Requires-Dist: harmonypy<2,>=0.0.9; platform_system == "Windows"
|
|
|
39
39
|
Provides-Extra: dandelion
|
|
40
40
|
Requires-Dist: sc-dandelion<1,>=0.5.7; extra == "dandelion"
|
|
41
41
|
Requires-Dist: matplotlib<3.9,>=3.7; python_version < "3.13" and extra == "dandelion"
|
|
42
|
+
Requires-Dist: scanpy<1.13,>=1.10; extra == "dandelion"
|
|
42
43
|
Provides-Extra: seq
|
|
43
44
|
Requires-Dist: parasail>=1.3; extra == "seq"
|
|
44
45
|
Provides-Extra: data
|
|
@@ -67,6 +68,7 @@ Dynamic: license-file
|
|
|
67
68
|
<a href="https://www.python.org"><img src="https://img.shields.io/badge/python-3.10%20%E2%80%93%203.14-blue.svg" alt="Python 3.10 to 3.14"></a>
|
|
68
69
|
<a href="https://pypi.org/project/threadfin/"><img src="https://img.shields.io/pypi/v/threadfin.svg" alt="PyPI version"></a>
|
|
69
70
|
<a href="https://github.com/Reynold4k/Threadfin/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
|
|
71
|
+
<a href="https://doi.org/10.5281/zenodo.23824521"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.23824521.svg" alt="DOI 10.5281/zenodo.23824521"></a>
|
|
70
72
|
</p>
|
|
71
73
|
|
|
72
74
|
Threadfin takes paired single-cell RNA and receptor (BCR or TCR) sequencing and describes every clone by the
|
|
@@ -116,6 +118,17 @@ receptor genes, estimates one profile per clone with two or more cells, tests cl
|
|
|
116
118
|
clone map and looks for clonal programmes. On the 16 public datasets tested (884 to 206,000 cells) it took about 1
|
|
117
119
|
to 11 minutes with 8 cores ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
|
|
118
120
|
|
|
121
|
+
**No data at hand?** A simulated repertoire with a known answer already has clone ids and an embedding. Run it
|
|
122
|
+
instead of the call above, and step 3 works as written, in a minute or two
|
|
123
|
+
([Tutorial 1](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md)):
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
import threadfin as tf
|
|
127
|
+
|
|
128
|
+
adata = tf.sim.simulate_repertoire()
|
|
129
|
+
result = tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")
|
|
130
|
+
```
|
|
131
|
+
|
|
119
132
|
### 3. Read the results
|
|
120
133
|
|
|
121
134
|
```python
|
|
@@ -157,9 +170,11 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
|
|
|
157
170
|
either way. Random draws follow the order of the cells, so the same cells in another order can give different
|
|
158
171
|
programmes; sort them first (`adata = adata[adata.obs_names.sort_values()].copy()`) when results must not
|
|
159
172
|
depend on the order.
|
|
160
|
-
* **
|
|
161
|
-
|
|
162
|
-
`tf.
|
|
173
|
+
* **Saving and reloading**: `adata.write_h5ad(...)` keeps the record of the run, and
|
|
174
|
+
`tf.ThreadfinResult.from_adata(anndata.read_h5ad(...))` gives the run's result back, with the same summary, also
|
|
175
|
+
after further `tf.tl` calls on the same AnnData.
|
|
176
|
+
* **Jupyter**: start the notebook with `%matplotlib inline`. With matplotlib older than 3.9 (which the Dandelion
|
|
177
|
+
extra installs on Python 3.10–3.12), the first figure of a session otherwise appears one cell late, or not at all.
|
|
163
178
|
|
|
164
179
|
### Run time and memory
|
|
165
180
|
|
|
@@ -184,11 +199,14 @@ about an hour for a million simulated cells on 8 cores
|
|
|
184
199
|
| Tutorial | What it covers |
|
|
185
200
|
|---|---|
|
|
186
201
|
| [1 — Getting started](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md) | the whole analysis on simulated data in a minute, with every output explained |
|
|
187
|
-
| [2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results: quality control, several samples and donors, clone calling, T cells, troubleshooting |
|
|
202
|
+
| [2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results: quality control, several samples and donors, clone calling, T cells, troubleshooting; every step can be run on the public data of Tutorial 5 |
|
|
188
203
|
| [3 — The clone map](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md) | automatic and hand-set layouts, and how to check a map |
|
|
189
204
|
| [4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
|
|
190
205
|
| [5 — From GEO to results (notebook)](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) | a published dataset (GSE287123) end to end: download, hashtag demultiplexing, clones, embedding, Threadfin and interpretation; executed in a fresh environment before every release (about 6 minutes on 8 cores) |
|
|
191
206
|
|
|
207
|
+
New in 4.6.2: the result of `tf.run` stays the run's own after later `tf.tl` calls on the same AnnData, also when
|
|
208
|
+
it is rebuilt from a saved file with `ThreadfinResult.from_adata`; every step of Tutorial 2 can be followed on the
|
|
209
|
+
public data of Tutorial 5. Results are unchanged.
|
|
192
210
|
New in 4.6.0: `strata_key=` names the sampling unit within which the coherence test shuffles clone labels when it
|
|
193
211
|
is finer than the context (`sample_key`); `composition_weight="clones"` describes each programme by its average
|
|
194
212
|
clone; the summary states the excess of clonal coherence over shuffled labels, the strata used and the order of
|
|
@@ -268,7 +286,7 @@ manuscript — status, datasets, every analysis and a benchmark against related
|
|
|
268
286
|
* **Model-antigen germinal centres** (Merkenschlager *et al.*, *Nature* 2025): the main axis of variation
|
|
269
287
|
between clone profiles follows recent division in two cohorts whose sequencing libraries are crossed; a
|
|
270
288
|
library effect would push the two cohorts in opposite directions, and their division directions agree
|
|
271
|
-
(cosine similarity 0.
|
|
289
|
+
(cosine similarity 0.90). Antigen-bait and dark-zone gates are also associated with clone profiles but were
|
|
272
290
|
each sequenced in their own library.
|
|
273
291
|
|
|
274
292
|
## A clone embedding that holds together
|
|
@@ -285,9 +303,12 @@ layout is chosen to stay connected, a connected map is not evidence of a continu
|
|
|
285
303
|
is judged from the programmes, their stability and the tests, which use the profiles.
|
|
286
304
|
|
|
287
305
|
```python
|
|
288
|
-
tf.tl.embed_clones(adata) # automatic (default)
|
|
306
|
+
tf.tl.embed_clones(adata) # automatic (default), after tf.run or tf.tl.clone_profiles
|
|
289
307
|
tf.tl.embed_clones(adata, n_neighbors=30, min_dist=0.3) # by hand
|
|
290
|
-
|
|
308
|
+
|
|
309
|
+
prof = adata.uns["threadfin"]["profiles"] # the clone profiles and the map drawn last
|
|
310
|
+
xy = prof["clone_table"][["x", "y"]].dropna()
|
|
311
|
+
tf.tl.map_quality(prof["features"].loc[xy.index], xy.to_numpy()) # score any clone map: profiles, coordinates
|
|
291
312
|
```
|
|
292
313
|
|
|
293
314
|
## How it works
|
|
@@ -328,12 +349,14 @@ The full description, with references, is in [Methods](https://github.com/Reynol
|
|
|
328
349
|
| [Technical validation](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/README.md) | the tutorials on 16 public datasets, sensitivity to clone calling and embedding, power, a million cells, T cells |
|
|
329
350
|
| [Figure gallery](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/tutorial_path/figures/README.md) | every figure Threadfin draws, for each of the 16 public datasets of the technical validation |
|
|
330
351
|
|
|
331
|
-
##
|
|
352
|
+
## How to cite
|
|
332
353
|
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
354
|
+
Please cite Threadfin as in [CITATION.cff](https://github.com/Reynold4k/Threadfin/blob/main/CITATION.cff) (on
|
|
355
|
+
GitHub: "Cite this repository"), with its Zenodo DOI
|
|
356
|
+
[10.5281/zenodo.23824521](https://doi.org/10.5281/zenodo.23824521), which leads to the latest version;
|
|
357
|
+
`result.methods()` names the version you used. A manuscript is in preparation. Please also cite the tools
|
|
358
|
+
Threadfin builds on: Dandelion (Suo *et al.*, *Nat. Biotechnol.* 2024) for clone definition, Scanpy (Wolf
|
|
359
|
+
*et al.*, *Genome Biol.* 2018) and UMAP (McInnes *et al.*, *J. Open Source Softw.* 2018).
|
|
337
360
|
|
|
338
361
|
## How Threadfin compares with related tools
|
|
339
362
|
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|