threadfin 4.6.1__tar.gz → 4.7.0__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 (74) hide show
  1. {threadfin-4.6.1 → threadfin-4.7.0}/LICENSE +1 -1
  2. {threadfin-4.6.1/threadfin.egg-info → threadfin-4.7.0}/PKG-INFO +72 -20
  3. {threadfin-4.6.1 → threadfin-4.7.0}/README.md +66 -17
  4. {threadfin-4.6.1 → threadfin-4.7.0}/pyproject.toml +16 -7
  5. threadfin-4.7.0/tests/test_dependency_api.py +40 -0
  6. threadfin-4.7.0/tests/test_neighbour_search.py +121 -0
  7. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_parallel_and_robustness.py +16 -0
  8. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_user_inputs.py +8 -0
  9. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_v4_core.py +115 -0
  10. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/__init__.py +5 -1
  11. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/_utils.py +115 -0
  12. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/api.py +156 -49
  13. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/core.py +12 -5
  14. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/dandelion.py +39 -5
  15. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/export.py +7 -0
  16. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/expression.py +4 -3
  17. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/maptune.py +12 -4
  18. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/plotting.py +43 -9
  19. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/pp.py +12 -4
  20. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/profiles.py +16 -4
  21. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/programmes.py +7 -4
  22. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/programs.py +12 -8
  23. {threadfin-4.6.1 → threadfin-4.7.0/threadfin.egg-info}/PKG-INFO +72 -20
  24. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin.egg-info/SOURCES.txt +2 -0
  25. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin.egg-info/requires.txt +8 -1
  26. {threadfin-4.6.1 → threadfin-4.7.0}/setup.cfg +0 -0
  27. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_api_reference.py +0 -0
  28. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_association_strata.py +0 -0
  29. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_bcrgraph_clones.py +0 -0
  30. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_bone_marrow_design.py +0 -0
  31. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_case_study_signatures.py +0 -0
  32. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_clone_state_sharing.py +0 -0
  33. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_clones_v3.py +0 -0
  34. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_dandelion_adapter.py +0 -0
  35. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_dandelion_seed.py +0 -0
  36. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_density.py +0 -0
  37. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_ebv_contig_matching.py +0 -0
  38. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_export.py +0 -0
  39. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_geneset_and_export.py +0 -0
  40. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_integrate.py +0 -0
  41. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_io.py +0 -0
  42. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_maptune.py +0 -0
  43. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_memory_reference.py +0 -0
  44. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_migration.py +0 -0
  45. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_phylo.py +0 -0
  46. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_profile_reproducibility.py +0 -0
  47. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_programs.py +0 -0
  48. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_read_paths.py +0 -0
  49. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_reclustering_presets.py +0 -0
  50. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_release_metadata.py +0 -0
  51. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_result_plots.py +0 -0
  52. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_sequence_v2.py +0 -0
  53. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_specificity.py +0 -0
  54. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_statistical_properties.py +0 -0
  55. {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_threadfin.py +0 -0
  56. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/_dandelion_worker.py +0 -0
  57. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/bcrgraph.py +0 -0
  58. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/clones.py +0 -0
  59. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/density.py +0 -0
  60. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/dynamics.py +0 -0
  61. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/heritability.py +0 -0
  62. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/integrate.py +0 -0
  63. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/io.py +0 -0
  64. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/metrics.py +0 -0
  65. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/migration.py +0 -0
  66. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/phylo.py +0 -0
  67. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/reclustering.py +0 -0
  68. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/sequence.py +0 -0
  69. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/simulate.py +0 -0
  70. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/specificity.py +0 -0
  71. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/stats.py +0 -0
  72. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/tl.py +0 -0
  73. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin.egg-info/dependency_links.txt +0 -0
  74. {threadfin-4.6.1 → threadfin-4.7.0}/threadfin.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 Chen Satoshi (Reynold4k)
3
+ Copyright (c) 2026 Chen Zhu (Reynold4k)
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -1,8 +1,8 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: threadfin
3
- Version: 4.6.1
3
+ Version: 4.7.0
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
- Author-email: Chen Satoshi <103236530+Reynold4k@users.noreply.github.com>
5
+ Author-email: Chen Zhu <103236530+Reynold4k@users.noreply.github.com>
6
6
  License: MIT
7
7
  Project-URL: Homepage, https://github.com/Reynold4k/Threadfin
8
8
  Project-URL: Repository, https://github.com/Reynold4k/Threadfin
@@ -33,12 +33,15 @@ Requires-Dist: matplotlib>=3.7
33
33
  Requires-Dist: igraph>=0.10
34
34
  Requires-Dist: leidenalg>=0.10
35
35
  Requires-Dist: umap-learn>=0.5.5
36
- Requires-Dist: pynndescent<0.7,>=0.5.8
36
+ Requires-Dist: pynndescent<0.7,>=0.5.8; python_version < "3.12"
37
+ Requires-Dist: pynndescent>=0.5.8; python_version >= "3.12"
37
38
  Requires-Dist: harmonypy>=0.0.9; platform_system != "Windows"
38
39
  Requires-Dist: harmonypy<2,>=0.0.9; platform_system == "Windows"
39
40
  Provides-Extra: dandelion
40
41
  Requires-Dist: sc-dandelion<1,>=0.5.7; extra == "dandelion"
41
42
  Requires-Dist: matplotlib<3.9,>=3.7; python_version < "3.13" and extra == "dandelion"
43
+ Requires-Dist: scanpy<1.13,>=1.10; extra == "dandelion"
44
+ Requires-Dist: pynndescent<0.7,>=0.5.8; python_version < "3.13" and extra == "dandelion"
42
45
  Provides-Extra: seq
43
46
  Requires-Dist: parasail>=1.3; extra == "seq"
44
47
  Provides-Extra: data
@@ -67,6 +70,7 @@ Dynamic: license-file
67
70
  <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
71
  <a href="https://pypi.org/project/threadfin/"><img src="https://img.shields.io/pypi/v/threadfin.svg" alt="PyPI version"></a>
69
72
  <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>
73
+ <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
74
  </p>
71
75
 
72
76
  Threadfin takes paired single-cell RNA and receptor (BCR or TCR) sequencing and describes every clone by the
@@ -86,9 +90,25 @@ Scanpy, Leiden, UMAP and Harmony are installed with it; a fresh `pip install "th
86
90
  depend on Python's string-hash seed, so Threadfin always calls them under seed 0, in a separate Python process
87
91
  when Python was not started with `PYTHONHASHSEED=0` (about 2 s more). Threadfin is validated with Dandelion 0.5.x;
88
92
  Dandelion 1.0 (October 2026) calls clones differently, so the extra installs `sc-dandelion<1`.
93
+ On Python 3.13 and 3.14 the extra installs matplotlib 3.9 or later, with which `import dandelion` before
94
+ `import threadfin` fails with `cannot import name 'get_cmap' from 'matplotlib.cm'`: import Threadfin first, which
95
+ restores that function, or let Threadfin call Dandelion.
89
96
  The development version installs with
90
97
  `pip install "git+https://github.com/Reynold4k/Threadfin.git"`.
91
98
 
99
+ Threadfin installs with the newest Scanpy, UMAP and pynndescent: on Python 3.12 and later, pip installs
100
+ pynndescent 0.7 and umap-learn 0.6. Where Scanpy cannot read pynndescent 0.7 (before Scanpy 1.12.5, which needs
101
+ Python 3.12), pip keeps pynndescent 0.6 and umap-learn 0.5: on Python 3.10 and 3.11, and with the Dandelion extra on
102
+ Python 3.12, which keeps matplotlib below 3.9 for Dandelion 0.5.7 and with it Scanpy at 1.11. The Dandelion extra
103
+ also keeps Scanpy below 1.13, which removed a module that Dandelion 0.5.7 imports. Threadfin uses approximate
104
+ neighbours only above 50,000 cells or 4,096 profiled clones; there, pynndescent 0.6 and 0.7 give slightly different
105
+ profiles, programmes and clone maps, and the same coherence and clonal memory. On smaller data, umap-learn 0.6 can
106
+ choose other clone-map settings than 0.5 (on one of nine validation data sets), with every other result the same
107
+ ([how much](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md)). On Python 3.10, pip installs
108
+ SciPy 1.15, with which UMAP starts from a mirrored layout: the clone maps of the tutorials differ slightly, and every
109
+ other result is the same. The published results are reproduced exactly with the validated versions (Python 3.11):
110
+ `pip install -r https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/tutorials/requirements-lock.txt`.
111
+
92
112
  ### 2. Run
93
113
 
94
114
  You need, for the same cells: raw gene counts in an [AnnData](https://anndata.readthedocs.io) object, the
@@ -96,10 +116,10 @@ contig-level receptor table (Cell Ranger's `filtered_contig_annotations.csv` or
96
116
  and sample of each cell.
97
117
 
98
118
  ```python
99
- import scanpy as sc
119
+ import anndata as ad
100
120
  import threadfin as tf
101
121
 
102
- adata = sc.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
122
+ adata = ad.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
103
123
 
104
124
  result = tf.run(
105
125
  adata,
@@ -116,6 +136,17 @@ receptor genes, estimates one profile per clone with two or more cells, tests cl
116
136
  clone map and looks for clonal programmes. On the 16 public datasets tested (884 to 206,000 cells) it took about 1
117
137
  to 11 minutes with 8 cores ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
118
138
 
139
+ **No data at hand?** A simulated repertoire with a known answer already has clone ids and an embedding. Run it
140
+ instead of the call above, and step 3 works as written, in a minute or two
141
+ ([Tutorial 1](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md)):
142
+
143
+ ```python
144
+ import threadfin as tf
145
+
146
+ adata = tf.sim.simulate_repertoire()
147
+ result = tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")
148
+ ```
149
+
119
150
  ### 3. Read the results
120
151
 
121
152
  ```python
@@ -152,14 +183,21 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
152
183
  * **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
153
184
  * **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
154
185
  * **Large data**: `n_jobs=-1` uses every CPU core ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
155
- * **Identical results**: `n_jobs` never changes a result. The automatically chosen clone map can change with the
156
- number of BLAS threads, so keep `OMP_NUM_THREADS` the same between runs; every statistic agrees to about 1e-7
157
- either way. Random draws follow the order of the cells, so the same cells in another order can give different
186
+ * **Identical results**: `n_jobs` never changes a result. The number of BLAS threads (`OMP_NUM_THREADS`) changes the
187
+ expression embedding that Threadfin builds when no `basis` is given at floating-point precision: the clonal ICC,
188
+ clonal memory and the variance explained by each label then agree to 1e-6 with the same P values, but programme
189
+ stabilities can change in the second decimal and the automatically chosen clone map can change, so keep the
190
+ thread count the same between runs that must match ([details](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md#blas-threads)).
191
+ Random draws follow the order of the cells, so the same cells in another order can give different
158
192
  programmes; sort them first (`adata = adata[adata.obs_names.sort_values()].copy()`) when results must not
159
193
  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).
194
+ * **Saving and reloading**: `adata.write_h5ad(...)` keeps the record of the run, and
195
+ `tf.ThreadfinResult.from_adata(anndata.read_h5ad(...))` gives the run's result back, with the same summary, also
196
+ after further `tf.tl` calls on the same AnnData.
197
+ * **Jupyter**: start the notebook with `%matplotlib inline`. With matplotlib older than 3.9 (which the Dandelion
198
+ extra installs on Python 3.10–3.12), the first figure of a session otherwise appears one cell late, or not at all.
199
+ Without ipywidgets, the first clone map of a session prints `TqdmWarning: IProgress not found`: umap-learn imports
200
+ a progress bar that Threadfin never shows, so the notice can be ignored, and `pip install ipywidgets` removes it.
163
201
 
164
202
  ### Run time and memory
165
203
 
@@ -184,11 +222,20 @@ about an hour for a million simulated cells on 8 cores
184
222
  | Tutorial | What it covers |
185
223
  |---|---|
186
224
  | [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 |
225
+ | [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
226
  | [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
227
  | [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
228
  | [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
229
 
230
+ New in 4.7.0: Threadfin installs with pynndescent 0.7 and umap-learn 0.6 on Python 3.12 and later; above 50,000
231
+ cells, profiles and programmes differ slightly from those with pynndescent 0.6 (coherence and clonal memory do not),
232
+ and the lock file reproduces the published numbers. With the Dandelion extra on Python 3.14, `n_jobs` no longer
233
+ fails when Dandelion was imported in the same session. `result.plot()` draws the run's own figure after later
234
+ `tf.tl` calls, and Threadfin's Scanpy calls give no deprecation warnings with Scanpy 1.13. The Methods paragraph
235
+ names the pynndescent and umap-learn versions.
236
+ 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
237
+ it is rebuilt from a saved file with `ThreadfinResult.from_adata`; every step of Tutorial 2 can be followed on the
238
+ public data of Tutorial 5. Results are unchanged.
192
239
  New in 4.6.0: `strata_key=` names the sampling unit within which the coherence test shuffles clone labels when it
193
240
  is finer than the context (`sample_key`); `composition_weight="clones"` describes each programme by its average
194
241
  clone; the summary states the excess of clonal coherence over shuffled labels, the strata used and the order of
@@ -268,7 +315,7 @@ manuscript — status, datasets, every analysis and a benchmark against related
268
315
  * **Model-antigen germinal centres** (Merkenschlager *et al.*, *Nature* 2025): the main axis of variation
269
316
  between clone profiles follows recent division in two cohorts whose sequencing libraries are crossed; a
270
317
  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
318
+ (cosine similarity 0.90). Antigen-bait and dark-zone gates are also associated with clone profiles but were
272
319
  each sequenced in their own library.
273
320
 
274
321
  ## A clone embedding that holds together
@@ -285,9 +332,12 @@ layout is chosen to stay connected, a connected map is not evidence of a continu
285
332
  is judged from the programmes, their stability and the tests, which use the profiles.
286
333
 
287
334
  ```python
288
- tf.tl.embed_clones(adata) # automatic (default)
335
+ tf.tl.embed_clones(adata) # automatic (default), after tf.run or tf.tl.clone_profiles
289
336
  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)
337
+
338
+ prof = adata.uns["threadfin"]["profiles"] # the clone profiles and the map drawn last
339
+ xy = prof["clone_table"][["x", "y"]].dropna()
340
+ tf.tl.map_quality(prof["features"].loc[xy.index], xy.to_numpy()) # score any clone map: profiles, coordinates
291
341
  ```
292
342
 
293
343
  ## How it works
@@ -328,12 +378,14 @@ The full description, with references, is in [Methods](https://github.com/Reynol
328
378
  | [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
379
  | [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
380
 
331
- ## Citation
381
+ ## How to cite
332
382
 
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).
383
+ Please cite Threadfin as in [CITATION.cff](https://github.com/Reynold4k/Threadfin/blob/main/CITATION.cff) (on
384
+ GitHub: "Cite this repository"), with its Zenodo DOI
385
+ [10.5281/zenodo.23824521](https://doi.org/10.5281/zenodo.23824521), which leads to the latest version;
386
+ `result.methods()` names the version you used. A manuscript is in preparation. Please also cite the tools
387
+ Threadfin builds on: Dandelion (Suo *et al.*, *Nat. Biotechnol.* 2024) for clone definition, Scanpy (Wolf
388
+ *et al.*, *Genome Biol.* 2018) and UMAP (McInnes *et al.*, *J. Open Source Softw.* 2018).
337
389
 
338
390
  ## How Threadfin compares with related tools
339
391
 
@@ -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
@@ -32,9 +33,25 @@ Scanpy, Leiden, UMAP and Harmony are installed with it; a fresh `pip install "th
32
33
  depend on Python's string-hash seed, so Threadfin always calls them under seed 0, in a separate Python process
33
34
  when Python was not started with `PYTHONHASHSEED=0` (about 2 s more). Threadfin is validated with Dandelion 0.5.x;
34
35
  Dandelion 1.0 (October 2026) calls clones differently, so the extra installs `sc-dandelion<1`.
36
+ On Python 3.13 and 3.14 the extra installs matplotlib 3.9 or later, with which `import dandelion` before
37
+ `import threadfin` fails with `cannot import name 'get_cmap' from 'matplotlib.cm'`: import Threadfin first, which
38
+ restores that function, or let Threadfin call Dandelion.
35
39
  The development version installs with
36
40
  `pip install "git+https://github.com/Reynold4k/Threadfin.git"`.
37
41
 
42
+ Threadfin installs with the newest Scanpy, UMAP and pynndescent: on Python 3.12 and later, pip installs
43
+ pynndescent 0.7 and umap-learn 0.6. Where Scanpy cannot read pynndescent 0.7 (before Scanpy 1.12.5, which needs
44
+ Python 3.12), pip keeps pynndescent 0.6 and umap-learn 0.5: on Python 3.10 and 3.11, and with the Dandelion extra on
45
+ Python 3.12, which keeps matplotlib below 3.9 for Dandelion 0.5.7 and with it Scanpy at 1.11. The Dandelion extra
46
+ also keeps Scanpy below 1.13, which removed a module that Dandelion 0.5.7 imports. Threadfin uses approximate
47
+ neighbours only above 50,000 cells or 4,096 profiled clones; there, pynndescent 0.6 and 0.7 give slightly different
48
+ profiles, programmes and clone maps, and the same coherence and clonal memory. On smaller data, umap-learn 0.6 can
49
+ choose other clone-map settings than 0.5 (on one of nine validation data sets), with every other result the same
50
+ ([how much](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md)). On Python 3.10, pip installs
51
+ SciPy 1.15, with which UMAP starts from a mirrored layout: the clone maps of the tutorials differ slightly, and every
52
+ other result is the same. The published results are reproduced exactly with the validated versions (Python 3.11):
53
+ `pip install -r https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/tutorials/requirements-lock.txt`.
54
+
38
55
  ### 2. Run
39
56
 
40
57
  You need, for the same cells: raw gene counts in an [AnnData](https://anndata.readthedocs.io) object, the
@@ -42,10 +59,10 @@ contig-level receptor table (Cell Ranger's `filtered_contig_annotations.csv` or
42
59
  and sample of each cell.
43
60
 
44
61
  ```python
45
- import scanpy as sc
62
+ import anndata as ad
46
63
  import threadfin as tf
47
64
 
48
- adata = sc.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
65
+ adata = ad.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
49
66
 
50
67
  result = tf.run(
51
68
  adata,
@@ -62,6 +79,17 @@ receptor genes, estimates one profile per clone with two or more cells, tests cl
62
79
  clone map and looks for clonal programmes. On the 16 public datasets tested (884 to 206,000 cells) it took about 1
63
80
  to 11 minutes with 8 cores ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
64
81
 
82
+ **No data at hand?** A simulated repertoire with a known answer already has clone ids and an embedding. Run it
83
+ instead of the call above, and step 3 works as written, in a minute or two
84
+ ([Tutorial 1](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md)):
85
+
86
+ ```python
87
+ import threadfin as tf
88
+
89
+ adata = tf.sim.simulate_repertoire()
90
+ result = tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")
91
+ ```
92
+
65
93
  ### 3. Read the results
66
94
 
67
95
  ```python
@@ -98,14 +126,21 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
98
126
  * **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
99
127
  * **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
100
128
  * **Large data**: `n_jobs=-1` uses every CPU core ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
101
- * **Identical results**: `n_jobs` never changes a result. The automatically chosen clone map can change with the
102
- number of BLAS threads, so keep `OMP_NUM_THREADS` the same between runs; every statistic agrees to about 1e-7
103
- either way. Random draws follow the order of the cells, so the same cells in another order can give different
129
+ * **Identical results**: `n_jobs` never changes a result. The number of BLAS threads (`OMP_NUM_THREADS`) changes the
130
+ expression embedding that Threadfin builds when no `basis` is given at floating-point precision: the clonal ICC,
131
+ clonal memory and the variance explained by each label then agree to 1e-6 with the same P values, but programme
132
+ stabilities can change in the second decimal and the automatically chosen clone map can change, so keep the
133
+ thread count the same between runs that must match ([details](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md#blas-threads)).
134
+ Random draws follow the order of the cells, so the same cells in another order can give different
104
135
  programmes; sort them first (`adata = adata[adata.obs_names.sort_values()].copy()`) when results must not
105
136
  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).
137
+ * **Saving and reloading**: `adata.write_h5ad(...)` keeps the record of the run, and
138
+ `tf.ThreadfinResult.from_adata(anndata.read_h5ad(...))` gives the run's result back, with the same summary, also
139
+ after further `tf.tl` calls on the same AnnData.
140
+ * **Jupyter**: start the notebook with `%matplotlib inline`. With matplotlib older than 3.9 (which the Dandelion
141
+ extra installs on Python 3.10–3.12), the first figure of a session otherwise appears one cell late, or not at all.
142
+ Without ipywidgets, the first clone map of a session prints `TqdmWarning: IProgress not found`: umap-learn imports
143
+ a progress bar that Threadfin never shows, so the notice can be ignored, and `pip install ipywidgets` removes it.
109
144
 
110
145
  ### Run time and memory
111
146
 
@@ -130,11 +165,20 @@ about an hour for a million simulated cells on 8 cores
130
165
  | Tutorial | What it covers |
131
166
  |---|---|
132
167
  | [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 |
168
+ | [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
169
  | [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
170
  | [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
171
  | [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
172
 
173
+ New in 4.7.0: Threadfin installs with pynndescent 0.7 and umap-learn 0.6 on Python 3.12 and later; above 50,000
174
+ cells, profiles and programmes differ slightly from those with pynndescent 0.6 (coherence and clonal memory do not),
175
+ and the lock file reproduces the published numbers. With the Dandelion extra on Python 3.14, `n_jobs` no longer
176
+ fails when Dandelion was imported in the same session. `result.plot()` draws the run's own figure after later
177
+ `tf.tl` calls, and Threadfin's Scanpy calls give no deprecation warnings with Scanpy 1.13. The Methods paragraph
178
+ names the pynndescent and umap-learn versions.
179
+ 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
180
+ it is rebuilt from a saved file with `ThreadfinResult.from_adata`; every step of Tutorial 2 can be followed on the
181
+ public data of Tutorial 5. Results are unchanged.
138
182
  New in 4.6.0: `strata_key=` names the sampling unit within which the coherence test shuffles clone labels when it
139
183
  is finer than the context (`sample_key`); `composition_weight="clones"` describes each programme by its average
140
184
  clone; the summary states the excess of clonal coherence over shuffled labels, the strata used and the order of
@@ -214,7 +258,7 @@ manuscript — status, datasets, every analysis and a benchmark against related
214
258
  * **Model-antigen germinal centres** (Merkenschlager *et al.*, *Nature* 2025): the main axis of variation
215
259
  between clone profiles follows recent division in two cohorts whose sequencing libraries are crossed; a
216
260
  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
261
+ (cosine similarity 0.90). Antigen-bait and dark-zone gates are also associated with clone profiles but were
218
262
  each sequenced in their own library.
219
263
 
220
264
  ## A clone embedding that holds together
@@ -231,9 +275,12 @@ layout is chosen to stay connected, a connected map is not evidence of a continu
231
275
  is judged from the programmes, their stability and the tests, which use the profiles.
232
276
 
233
277
  ```python
234
- tf.tl.embed_clones(adata) # automatic (default)
278
+ tf.tl.embed_clones(adata) # automatic (default), after tf.run or tf.tl.clone_profiles
235
279
  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)
280
+
281
+ prof = adata.uns["threadfin"]["profiles"] # the clone profiles and the map drawn last
282
+ xy = prof["clone_table"][["x", "y"]].dropna()
283
+ tf.tl.map_quality(prof["features"].loc[xy.index], xy.to_numpy()) # score any clone map: profiles, coordinates
237
284
  ```
238
285
 
239
286
  ## How it works
@@ -274,12 +321,14 @@ The full description, with references, is in [Methods](https://github.com/Reynol
274
321
  | [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
322
  | [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
323
 
277
- ## Citation
324
+ ## How to cite
278
325
 
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).
326
+ Please cite Threadfin as in [CITATION.cff](https://github.com/Reynold4k/Threadfin/blob/main/CITATION.cff) (on
327
+ GitHub: "Cite this repository"), with its Zenodo DOI
328
+ [10.5281/zenodo.23824521](https://doi.org/10.5281/zenodo.23824521), which leads to the latest version;
329
+ `result.methods()` names the version you used. A manuscript is in preparation. Please also cite the tools
330
+ Threadfin builds on: Dandelion (Suo *et al.*, *Nat. Biotechnol.* 2024) for clone definition, Scanpy (Wolf
331
+ *et al.*, *Genome Biol.* 2018) and UMAP (McInnes *et al.*, *J. Open Source Softw.* 2018).
283
332
 
284
333
  ## How Threadfin compares with related tools
285
334
 
@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "threadfin"
7
- version = "4.6.1"
7
+ version = "4.7.0"
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"
11
11
  license = { text = "MIT" }
12
12
  authors = [
13
- { name = "Chen Satoshi", email = "103236530+Reynold4k@users.noreply.github.com" },
13
+ { name = "Chen Zhu", email = "103236530+Reynold4k@users.noreply.github.com" },
14
14
  ]
15
15
  keywords = ["single-cell", "scRNA-seq", "BCR", "VDJ", "B cell", "clone", "clonal lineage",
16
16
  "germinal center", "immunology", "repertoire"]
@@ -37,9 +37,13 @@ dependencies = [
37
37
  "igraph>=0.10",
38
38
  "leidenalg>=0.10",
39
39
  "umap-learn>=0.5.5", # older releases import pkg_resources, absent from new environments
40
- # likewise; 0.7 (2026-10-27) returns sparse arrays that scanpy's neighbour search cannot read, and finds
41
- # different approximate neighbours, so new installations would no longer reproduce the validated results
42
- "pynndescent>=0.5.8,<0.7",
40
+ # likewise. pynndescent 0.7 returns sparse arrays that scanpy's neighbour search reads only from scanpy 1.12.5
41
+ # on, which needs Python >= 3.12; on Python 3.10 and 3.11 scanpy stays at 1.11, and so pynndescent below 0.7
42
+ # (and umap-learn below 0.6, which needs pynndescent >= 0.7). Above 50,000 cells, or 4,096 clones on the clone
43
+ # map, 0.6 and 0.7 find different approximate neighbours: docs/COMPATIBILITY.md gives the differences, and
44
+ # docs/tutorials/requirements-lock.txt the validated versions
45
+ "pynndescent>=0.5.8,<0.7; python_version < '3.12'",
46
+ "pynndescent>=0.5.8; python_version >= '3.12'",
43
47
  "harmonypy>=0.0.9; platform_system != 'Windows'",
44
48
  # harmonypy 2.x ships no Windows wheels and does not compile with MSVC; 0.2 and earlier are pure Python
45
49
  "harmonypy>=0.0.9,<2; platform_system == 'Windows'",
@@ -47,10 +51,15 @@ dependencies = [
47
51
 
48
52
  [project.optional-dependencies]
49
53
  # clone definition with Dandelion; sc-dandelion 0.5.7 imports nxviz, which uses matplotlib.cm.get_cmap, removed in
50
- # matplotlib 3.9. Up to Python 3.12 the extra keeps the validated matplotlib < 3.9; matplotlib < 3.9 has no wheels
54
+ # matplotlib 3.9. Up to Python 3.12 the extra keeps the validated matplotlib < 3.9, with which scanpy stays at 1.11
55
+ # (scanpy 1.12 needs matplotlib >= 3.9), so pynndescent stays below 0.7 there too; matplotlib < 3.9 has no wheels
51
56
  # for Python 3.13+, where importing threadfin restores get_cmap for Dandelion (clone calls verified identical).
52
57
  # 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'"]
58
+ # scanpy 1.13.0 (2026-11-13, Python 3.13+) removed scanpy.plotting._tools, which sc-dandelion 0.5.7 imports, hence
59
+ # scanpy < 1.13 with this extra (on Python 3.13+ scanpy 1.12, which reads pynndescent 0.7); without it, Threadfin
60
+ # itself works with scanpy 1.13.
61
+ dandelion = ["sc-dandelion>=0.5.7,<1", "matplotlib>=3.7,<3.9; python_version < '3.13'", "scanpy>=1.10,<1.13",
62
+ "pynndescent>=0.5.8,<0.7; python_version < '3.13'"]
54
63
  seq = ["parasail>=1.3"] # faster CDR3 alignment for the legacy v3 functions
55
64
  data = ["mudata>=0.3", "awkward>=2"] # reading scirpy/MuData example data
56
65
  test = ["pytest>=7", "pytest-cov>=4"]
@@ -0,0 +1,40 @@
1
+ """Threadfin's calls of scanpy use the argument names of the installed scanpy.
2
+
3
+ scanpy 1.13 renamed several arguments (inplace=False to out=True, batch_key to batch, layer to use, score_name to
4
+ out, use_rep to use) and warns about the old names, which scanpy 1.10-1.12 need; it also reworded its Leiden
5
+ warning, which the earlier v3 function silences.
6
+ """
7
+
8
+ import os
9
+ import warnings
10
+
11
+ import numpy as np
12
+ import pandas as pd
13
+ from anndata import AnnData
14
+
15
+ import threadfin as tf
16
+ from threadfin import programs
17
+
18
+
19
+ def test_scanpy_is_called_without_deprecated_arguments():
20
+ rng = np.random.default_rng(0)
21
+ obs = pd.DataFrame({"batch": np.repeat(["a", "b"], 150), "clone_cluster": np.tile(["A", "B"], 150)},
22
+ index=[f"c{i}" for i in range(300)])
23
+ counts = rng.poisson(rng.gamma(1.0, 1.0, size=(3, 120))[rng.integers(0, 3, 300)]).astype(np.float32)
24
+ adata = AnnData(counts, obs=obs, var=pd.DataFrame(index=[f"G{i}" for i in range(120)]))
25
+ sim = tf.sim.simulate_repertoire(n_clones=200, random_state=1)
26
+ with warnings.catch_warnings(record=True) as caught:
27
+ warnings.simplefilter("always")
28
+ tf.pp.prepare_embedding(adata, batch_key="batch", n_top_genes=60, n_comps=5, verbose=False)
29
+ tf.pp.FrozenExpressionModel.fit(AnnData(counts.copy(), var=adata.var.copy()), n_top_genes=50, n_comps=5)
30
+ programs.community_markers(adata, n_genes=5, layer="log_norm")
31
+ programs.community_score(adata, {"prog": ["G1", "G2", "G3"]})
32
+ tf.clonotype_recluster(sim, basis="X_pca", embedding_mode="distance_profiles", cluster_on="embedding",
33
+ n_neighbors=10, umap_n_neighbors=15, random_state=0, cluster_random_state=0,
34
+ copy=True)
35
+ package = os.path.dirname(tf.__file__)
36
+ ours = [f"{os.path.basename(w.filename)}:{w.lineno} {w.message}" for w in caught
37
+ if issubclass(w.category, (FutureWarning, DeprecationWarning)) and w.filename.startswith(package)]
38
+ assert not ours, ours
39
+ assert not [w for w in caught if "implementation of leiden" in str(w.message)
40
+ or "implementations of leiden" in str(w.message)]
@@ -0,0 +1,121 @@
1
+ """The two steps that use approximate neighbour search, with whichever pynndescent and umap-learn are installed.
2
+
3
+ Above 50,000 cells the smoothing of clone profiles finds each cell's neighbours with pynndescent, and UMAP lays out
4
+ 4,096 or more clones with pynndescent too; below that both searches are exact. pyproject.toml allows pynndescent
5
+ 0.6 (with umap-learn 0.5) on Python 3.10-3.11 and pynndescent 0.7 (with umap-learn 0.6) from Python 3.12, so the
6
+ test matrix runs these paths with both. scanpy reads pynndescent 0.7 only from 1.12.5, which import threadfin checks.
7
+ """
8
+
9
+ import warnings
10
+
11
+ import numpy as np
12
+ import pytest
13
+
14
+ from threadfin import _utils
15
+ from threadfin.maptune import layout_clone_map
16
+ from threadfin.profiles import neighbour_average
17
+
18
+
19
+ @pytest.mark.parametrize("scanpy, pynndescent, flagged", [
20
+ ("1.11.5", "0.7.0", True), ("1.12.4", "0.7.0", True), ("1.12.5", "0.7.0", False), ("1.13.0", "0.7.0", False),
21
+ ("1.11.5", "0.6.0", False), ("1.10.0", "0.5.8", False), ("1.12.4", "0.8.1", True), ("1.11.5", "0.7.0rc1", True),
22
+ (None, "0.7.0", False), ("1.11.5", None, False), ("not a version", "0.7.0", False),
23
+ ])
24
+ def test_scanpy_that_cannot_read_pynndescent_07_is_flagged(scanpy, pynndescent, flagged):
25
+ problem = _utils.neighbour_stack_problem(scanpy, pynndescent)
26
+ assert (problem is not None) == flagged
27
+ if flagged:
28
+ assert "pip install \"pynndescent<0.7\"" in problem and "getnnz" in problem
29
+
30
+
31
+ def test_the_import_check_warns_once_and_names_the_fix(monkeypatch):
32
+ versions = {"scanpy": "1.11.5", "pynndescent": "0.7.0"}
33
+ monkeypatch.setattr(_utils, "_installed_version", versions.get)
34
+ with pytest.warns(UserWarning, match="scanpy 1.12.5 or later"):
35
+ assert _utils.check_neighbour_stack() is not None
36
+ versions["pynndescent"] = "0.6.0"
37
+ with warnings.catch_warnings():
38
+ warnings.simplefilter("error")
39
+ assert _utils.check_neighbour_stack() is None
40
+
41
+
42
+ def test_smoothing_above_50000_cells_averages_the_approximate_neighbours(monkeypatch):
43
+ import pynndescent
44
+ from sklearn.neighbors import NearestNeighbors
45
+
46
+ graphs = []
47
+ original = pynndescent.NNDescent
48
+
49
+ class Spy(original):
50
+ @property
51
+ def neighbor_graph(self):
52
+ graph = super().neighbor_graph
53
+ graphs.append(graph[0])
54
+ return graph
55
+
56
+ monkeypatch.setattr(pynndescent, "NNDescent", Spy)
57
+ rng = np.random.default_rng(0)
58
+ centres = rng.normal(0, 10, size=(20, 5))
59
+ x = centres[rng.integers(0, 20, 50_001)] + rng.normal(size=(50_001, 5))
60
+ out = neighbour_average(x, 5)
61
+ assert len(graphs) == 1, "more than 50,000 cells: the neighbours come from pynndescent"
62
+ idx = graphs[0]
63
+ np.testing.assert_allclose(out, x[idx].mean(axis=1), atol=1e-12)
64
+ exact = NearestNeighbors(n_neighbors=5).fit(x).kneighbors(x, return_distance=False)
65
+ recall = np.mean([len(set(a) & set(b)) / 5 for a, b in zip(idx, exact)])
66
+ assert recall > 0.9, recall
67
+
68
+
69
+ def test_clone_map_of_more_than_4096_clones():
70
+ from sklearn.neighbors import NearestNeighbors
71
+
72
+ rng = np.random.default_rng(1)
73
+ centres = rng.normal(0, 8, size=(3, 8))
74
+ group = rng.integers(0, 3, 4_200)
75
+ features = centres[group] + rng.normal(size=(4_200, 8))
76
+ xy, quality, setting, attempts = layout_clone_map(features, n_neighbors=15, min_dist=0.5)
77
+ assert xy.shape == (4_200, 2) and np.isfinite(xy).all()
78
+ assert setting == (15, 0.5, 1.0, 0) and len(attempts) == 1 and set(quality) >= {"coherence", "local_fidelity"}
79
+ # three well-separated groups of clones stay apart on the map
80
+ near = NearestNeighbors(n_neighbors=11).fit(xy).kneighbors(xy, return_distance=False)[:, 1:]
81
+ assert (group[near] == group[:, None]).mean() > 0.95
82
+
83
+
84
+ def test_cells_with_too_few_approximate_neighbours_get_exact_ones(monkeypatch):
85
+ """pynndescent pads the neighbour row of a cell for which it found fewer than k neighbours with -1."""
86
+ import pynndescent
87
+ from sklearn.neighbors import NearestNeighbors
88
+
89
+ rng = np.random.default_rng(2)
90
+ x = rng.normal(size=(50_001, 3))
91
+ exact = NearestNeighbors(n_neighbors=4).fit(x).kneighbors(x, return_distance=False)
92
+ padded = exact.copy()
93
+ padded[[0, 7, 50_000], 2:] = -1
94
+
95
+ class Padded:
96
+ def __init__(self, data, n_neighbors, random_state=None, **kw):
97
+ assert data.shape == x.shape and n_neighbors == 4
98
+
99
+ @property
100
+ def neighbor_graph(self):
101
+ return padded.copy(), np.zeros(padded.shape)
102
+
103
+ monkeypatch.setattr(pynndescent, "NNDescent", Padded)
104
+ np.testing.assert_allclose(neighbour_average(x, 4), x[exact].mean(axis=1), atol=1e-12)
105
+
106
+
107
+ def test_umap_keeps_the_layout_pipeline_the_clone_map_was_validated_with():
108
+ """umap-learn 0.6 warns that a later release will switch to a new layout pipeline; Threadfin keeps the 0.5 one."""
109
+ import inspect
110
+
111
+ import umap
112
+
113
+ opts = _utils.umap_layout_options()
114
+ assert opts == ({"compatibility_layout": True} if "compatibility_layout" in inspect.signature(umap.UMAP).parameters
115
+ else {})
116
+ rng = np.random.default_rng(3)
117
+ with warnings.catch_warnings(record=True) as caught:
118
+ warnings.simplefilter("always")
119
+ xy, *_ = layout_clone_map(rng.normal(size=(300, 6)), n_neighbors=10, min_dist=0.5)
120
+ assert np.isfinite(xy).all()
121
+ assert not [w for w in caught if "compatibility_layout" in str(w.message)]
@@ -101,3 +101,19 @@ def test_parallel_bootstrap_gives_the_same_programmes():
101
101
  two = tf.tl.find_programmes(adata, n_boot=6, n_jobs=2, verbose=False)
102
102
  pd.testing.assert_frame_equal(one, two)
103
103
  assert labels_one.equals(adata.obs["clone_programme"].astype(str))
104
+
105
+
106
+ def test_worker_processes_survive_a_lowered_pickle_protocol(monkeypatch):
107
+ """sc-dandelion 0.5.x sets pickle.HIGHEST_PROTOCOL = 4 when it is imported. From Python 3.14 the default protocol
108
+ is 5, and joblib's hand-over of arrays above 1 MB to the worker processes of the clone-map search and of the
109
+ programme bootstrap failed ("pickle protocol must be <= 4")."""
110
+ import pickle
111
+
112
+ from joblib import delayed
113
+
114
+ from threadfin._utils import parallel
115
+
116
+ monkeypatch.setattr(pickle, "HIGHEST_PROTOCOL", 4)
117
+ big = np.arange(300_000, dtype=np.int64) # 2.4 MB: memory-mapped for the workers
118
+ assert parallel(2)(delayed(np.sum)(big) for _ in range(2)) == [big.sum()] * 2
119
+ assert pickle.HIGHEST_PROTOCOL >= pickle.DEFAULT_PROTOCOL
@@ -70,6 +70,14 @@ def test_prepare_embedding_rejects_negative_counts_with_fix():
70
70
  tf.pp.prepare_embedding(adata, verbose=False)
71
71
 
72
72
 
73
+ def test_prepare_embedding_explains_an_empty_x():
74
+ """anndata 0.13 keeps X among the layers (key None): deleting every layer also deletes X."""
75
+ counts = np.random.default_rng(0).poisson(2.0, size=(6, 3)).astype(np.float32)
76
+ adata = AnnData(X=None, obs=_adata().obs, var=pd.DataFrame(index=["g0", "g1", "g2"]), layers={"counts": counts})
77
+ with pytest.raises(ValueError, match="adata.X is empty.*counts_layer="):
78
+ tf.pp.prepare_embedding(adata, verbose=False)
79
+
80
+
73
81
  @pytest.mark.parametrize("n_comps", [0, -1, 1.5, True])
74
82
  def test_prepare_embedding_requires_positive_integer_n_comps(n_comps):
75
83
  with pytest.raises(ValueError, match="n_comps must be a positive integer"):