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.
Files changed (72) hide show
  1. {threadfin-4.6.0 → threadfin-4.6.2}/PKG-INFO +36 -13
  2. {threadfin-4.6.0 → threadfin-4.6.2}/README.md +34 -12
  3. {threadfin-4.6.0 → threadfin-4.6.2}/pyproject.toml +4 -2
  4. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_v4_core.py +58 -0
  5. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/__init__.py +1 -1
  6. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/api.py +122 -42
  7. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/core.py +5 -2
  8. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/dandelion.py +4 -4
  9. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin.egg-info/PKG-INFO +36 -13
  10. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin.egg-info/requires.txt +1 -0
  11. {threadfin-4.6.0 → threadfin-4.6.2}/LICENSE +0 -0
  12. {threadfin-4.6.0 → threadfin-4.6.2}/setup.cfg +0 -0
  13. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_api_reference.py +0 -0
  14. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_association_strata.py +0 -0
  15. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_bcrgraph_clones.py +0 -0
  16. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_bone_marrow_design.py +0 -0
  17. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_case_study_signatures.py +0 -0
  18. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_clone_state_sharing.py +0 -0
  19. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_clones_v3.py +0 -0
  20. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_dandelion_adapter.py +0 -0
  21. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_dandelion_seed.py +0 -0
  22. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_density.py +0 -0
  23. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_ebv_contig_matching.py +0 -0
  24. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_export.py +0 -0
  25. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_geneset_and_export.py +0 -0
  26. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_integrate.py +0 -0
  27. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_io.py +0 -0
  28. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_maptune.py +0 -0
  29. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_memory_reference.py +0 -0
  30. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_migration.py +0 -0
  31. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_parallel_and_robustness.py +0 -0
  32. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_phylo.py +0 -0
  33. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_profile_reproducibility.py +0 -0
  34. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_programs.py +0 -0
  35. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_read_paths.py +0 -0
  36. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_reclustering_presets.py +0 -0
  37. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_release_metadata.py +0 -0
  38. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_result_plots.py +0 -0
  39. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_sequence_v2.py +0 -0
  40. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_specificity.py +0 -0
  41. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_statistical_properties.py +0 -0
  42. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_threadfin.py +0 -0
  43. {threadfin-4.6.0 → threadfin-4.6.2}/tests/test_user_inputs.py +0 -0
  44. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/_dandelion_worker.py +0 -0
  45. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/_utils.py +0 -0
  46. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/bcrgraph.py +0 -0
  47. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/clones.py +0 -0
  48. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/density.py +0 -0
  49. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/dynamics.py +0 -0
  50. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/export.py +0 -0
  51. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/expression.py +0 -0
  52. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/heritability.py +0 -0
  53. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/integrate.py +0 -0
  54. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/io.py +0 -0
  55. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/maptune.py +0 -0
  56. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/metrics.py +0 -0
  57. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/migration.py +0 -0
  58. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/phylo.py +0 -0
  59. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/plotting.py +0 -0
  60. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/pp.py +0 -0
  61. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/profiles.py +0 -0
  62. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/programmes.py +0 -0
  63. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/programs.py +0 -0
  64. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/reclustering.py +0 -0
  65. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/sequence.py +0 -0
  66. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/simulate.py +0 -0
  67. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/specificity.py +0 -0
  68. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/stats.py +0 -0
  69. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin/tl.py +0 -0
  70. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin.egg-info/SOURCES.txt +0 -0
  71. {threadfin-4.6.0 → threadfin-4.6.2}/threadfin.egg-info/dependency_links.txt +0 -0
  72. {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.0
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
- * **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
161
- has clone ids and an embedding, so run it with
162
- `tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
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.89). Antigen-bait and dark-zone gates are also associated with clone profiles but were
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
- tf.tl.map_quality(features, xy) # score any clone map (profiles, coordinates)
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
- ## Citation
352
+ ## How to cite
332
353
 
333
- A manuscript describing Threadfin is in preparation. Until it is available, please cite this repository
334
- ([CITATION.cff](https://github.com/Reynold4k/Threadfin/blob/main/CITATION.cff)) and the tools Threadfin builds on: Dandelion (Suo *et al.*, *Nat.
335
- Biotechnol.* 2024) for clone definition, Scanpy (Wolf *et al.*, *Genome Biol.* 2018) and UMAP (McInnes
336
- *et al.*, *J. Open Source Softw.* 2018).
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
- * **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
107
- has clone ids and an embedding, so run it with
108
- `tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
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.89). Antigen-bait and dark-zone gates are also associated with clone profiles but were
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
- tf.tl.map_quality(features, xy) # score any clone map (profiles, coordinates)
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
- ## Citation
297
+ ## How to cite
278
298
 
279
- A manuscript describing Threadfin is in preparation. Until it is available, please cite this repository
280
- ([CITATION.cff](https://github.com/Reynold4k/Threadfin/blob/main/CITATION.cff)) and the tools Threadfin builds on: Dandelion (Suo *et al.*, *Nat.
281
- Biotechnol.* 2024) for clone definition, Scanpy (Wolf *et al.*, *Genome Biol.* 2018) and UMAP (McInnes
282
- *et al.*, *J. Open Source Softw.* 2018).
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.0"
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
- dandelion = ["sc-dandelion>=0.5.7,<1", "matplotlib>=3.7,<3.9; python_version < '3.13'"]
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.0"
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) -> "ThreadfinResult":
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
- Label tests are taken from ``adata.uns['threadfin']``, where a later call of the same test with the same
184
- label replaces the one :func:`run` made.
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
- tests = {k: th["associations"][k].copy() for k in labels("tests") if k in th.get("associations", {})}
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
- time_key = settings["time_key"]
211
- return cls(
212
- adata=adata, coherence=dict(th["coherence"]), programmes=programmes,
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 = ad.uns["threadfin"]["profiles"]["variance_components"]
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 = ad.uns.get("threadfin", {})
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
- clones = adata.uns["threadfin"]["profiles"]["clone_table"]
910
- result = ThreadfinResult(
911
- adata=adata, coherence=coherence, programmes=programmes, clones=clones,
912
- composition=composition, tests=tests, profile_tests=profile_tests, memory=memory, skipped=skipped,
913
- settings={"clone_key": clone_key, "donor_key": donor_key, "sample_key": sample_key,
914
- "strata_key": strata_key or sample_key,
915
- "state_key": state_key, "composition_weight": composition_weight, "time_key": time_key,
916
- "basis": basis,
917
- "representation": representation, "receptor": receptor, "clone_calling": clone_calling,
918
- "n_perm": int(n_perm), "n_boot": int(n_boot), "random_state": int(random_state)},
919
- )
920
- get_uns(adata)["run"] = h5ad_safe({
921
- "settings": {k: v for k, v in result.settings.items() if v is not None},
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
- sc.tl.leiden(clone_adata, resolution=resolution, random_state=cluster_random_state,
364
- flavor="leidenalg", directed=True, n_iterations=-1)
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 that is
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 that is, so the clones are the "
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.0
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
- * **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
161
- has clone ids and an embedding, so run it with
162
- `tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
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.89). Antigen-bait and dark-zone gates are also associated with clone profiles but were
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
- tf.tl.map_quality(features, xy) # score any clone map (profiles, coordinates)
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
- ## Citation
352
+ ## How to cite
332
353
 
333
- A manuscript describing Threadfin is in preparation. Until it is available, please cite this repository
334
- ([CITATION.cff](https://github.com/Reynold4k/Threadfin/blob/main/CITATION.cff)) and the tools Threadfin builds on: Dandelion (Suo *et al.*, *Nat.
335
- Biotechnol.* 2024) for clone definition, Scanpy (Wolf *et al.*, *Genome Biol.* 2018) and UMAP (McInnes
336
- *et al.*, *J. Open Source Softw.* 2018).
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
 
@@ -23,6 +23,7 @@ psutil>=5
23
23
 
24
24
  [dandelion]
25
25
  sc-dandelion<1,>=0.5.7
26
+ scanpy<1.13,>=1.10
26
27
 
27
28
  [dandelion:python_version < "3.13"]
28
29
  matplotlib<3.9,>=3.7
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