threadfin 4.6.2__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.2 → threadfin-4.7.0}/LICENSE +1 -1
  2. {threadfin-4.6.2/threadfin.egg-info → threadfin-4.7.0}/PKG-INFO +37 -8
  3. {threadfin-4.6.2 → threadfin-4.7.0}/README.md +32 -5
  4. {threadfin-4.6.2 → threadfin-4.7.0}/pyproject.toml +15 -8
  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.2 → threadfin-4.7.0}/tests/test_parallel_and_robustness.py +16 -0
  8. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_user_inputs.py +8 -0
  9. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_v4_core.py +57 -0
  10. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/__init__.py +5 -1
  11. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/_utils.py +115 -0
  12. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/api.py +38 -11
  13. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/core.py +8 -4
  14. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/dandelion.py +35 -1
  15. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/export.py +7 -0
  16. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/expression.py +4 -3
  17. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/maptune.py +12 -4
  18. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/plotting.py +43 -9
  19. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/pp.py +12 -4
  20. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/profiles.py +16 -4
  21. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/programmes.py +7 -4
  22. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/programs.py +12 -8
  23. {threadfin-4.6.2 → threadfin-4.7.0/threadfin.egg-info}/PKG-INFO +37 -8
  24. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin.egg-info/SOURCES.txt +2 -0
  25. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin.egg-info/requires.txt +7 -1
  26. {threadfin-4.6.2 → threadfin-4.7.0}/setup.cfg +0 -0
  27. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_api_reference.py +0 -0
  28. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_association_strata.py +0 -0
  29. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_bcrgraph_clones.py +0 -0
  30. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_bone_marrow_design.py +0 -0
  31. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_case_study_signatures.py +0 -0
  32. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_clone_state_sharing.py +0 -0
  33. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_clones_v3.py +0 -0
  34. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_dandelion_adapter.py +0 -0
  35. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_dandelion_seed.py +0 -0
  36. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_density.py +0 -0
  37. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_ebv_contig_matching.py +0 -0
  38. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_export.py +0 -0
  39. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_geneset_and_export.py +0 -0
  40. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_integrate.py +0 -0
  41. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_io.py +0 -0
  42. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_maptune.py +0 -0
  43. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_memory_reference.py +0 -0
  44. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_migration.py +0 -0
  45. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_phylo.py +0 -0
  46. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_profile_reproducibility.py +0 -0
  47. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_programs.py +0 -0
  48. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_read_paths.py +0 -0
  49. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_reclustering_presets.py +0 -0
  50. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_release_metadata.py +0 -0
  51. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_result_plots.py +0 -0
  52. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_sequence_v2.py +0 -0
  53. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_specificity.py +0 -0
  54. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_statistical_properties.py +0 -0
  55. {threadfin-4.6.2 → threadfin-4.7.0}/tests/test_threadfin.py +0 -0
  56. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/_dandelion_worker.py +0 -0
  57. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/bcrgraph.py +0 -0
  58. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/clones.py +0 -0
  59. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/density.py +0 -0
  60. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/dynamics.py +0 -0
  61. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/heritability.py +0 -0
  62. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/integrate.py +0 -0
  63. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/io.py +0 -0
  64. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/metrics.py +0 -0
  65. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/migration.py +0 -0
  66. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/phylo.py +0 -0
  67. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/reclustering.py +0 -0
  68. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/sequence.py +0 -0
  69. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/simulate.py +0 -0
  70. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/specificity.py +0 -0
  71. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/stats.py +0 -0
  72. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin/tl.py +0 -0
  73. {threadfin-4.6.2 → threadfin-4.7.0}/threadfin.egg-info/dependency_links.txt +0 -0
  74. {threadfin-4.6.2 → 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.2
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,13 +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"
42
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"
43
45
  Provides-Extra: seq
44
46
  Requires-Dist: parasail>=1.3; extra == "seq"
45
47
  Provides-Extra: data
@@ -88,9 +90,25 @@ Scanpy, Leiden, UMAP and Harmony are installed with it; a fresh `pip install "th
88
90
  depend on Python's string-hash seed, so Threadfin always calls them under seed 0, in a separate Python process
89
91
  when Python was not started with `PYTHONHASHSEED=0` (about 2 s more). Threadfin is validated with Dandelion 0.5.x;
90
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.
91
96
  The development version installs with
92
97
  `pip install "git+https://github.com/Reynold4k/Threadfin.git"`.
93
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
+
94
112
  ### 2. Run
95
113
 
96
114
  You need, for the same cells: raw gene counts in an [AnnData](https://anndata.readthedocs.io) object, the
@@ -98,10 +116,10 @@ contig-level receptor table (Cell Ranger's `filtered_contig_annotations.csv` or
98
116
  and sample of each cell.
99
117
 
100
118
  ```python
101
- import scanpy as sc
119
+ import anndata as ad
102
120
  import threadfin as tf
103
121
 
104
- 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
105
123
 
106
124
  result = tf.run(
107
125
  adata,
@@ -165,9 +183,12 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
165
183
  * **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
166
184
  * **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
167
185
  * **Large data**: `n_jobs=-1` uses every CPU core ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
168
- * **Identical results**: `n_jobs` never changes a result. The automatically chosen clone map can change with the
169
- number of BLAS threads, so keep `OMP_NUM_THREADS` the same between runs; every statistic agrees to about 1e-7
170
- 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
171
192
  programmes; sort them first (`adata = adata[adata.obs_names.sort_values()].copy()`) when results must not
172
193
  depend on the order.
173
194
  * **Saving and reloading**: `adata.write_h5ad(...)` keeps the record of the run, and
@@ -175,6 +196,8 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
175
196
  after further `tf.tl` calls on the same AnnData.
176
197
  * **Jupyter**: start the notebook with `%matplotlib inline`. With matplotlib older than 3.9 (which the Dandelion
177
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.
178
201
 
179
202
  ### Run time and memory
180
203
 
@@ -204,6 +227,12 @@ about an hour for a million simulated cells on 8 cores
204
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` |
205
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) |
206
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.
207
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
208
237
  it is rebuilt from a saved file with `ThreadfinResult.from_adata`; every step of Tutorial 2 can be followed on the
209
238
  public data of Tutorial 5. Results are unchanged.
@@ -33,9 +33,25 @@ Scanpy, Leiden, UMAP and Harmony are installed with it; a fresh `pip install "th
33
33
  depend on Python's string-hash seed, so Threadfin always calls them under seed 0, in a separate Python process
34
34
  when Python was not started with `PYTHONHASHSEED=0` (about 2 s more). Threadfin is validated with Dandelion 0.5.x;
35
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.
36
39
  The development version installs with
37
40
  `pip install "git+https://github.com/Reynold4k/Threadfin.git"`.
38
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
+
39
55
  ### 2. Run
40
56
 
41
57
  You need, for the same cells: raw gene counts in an [AnnData](https://anndata.readthedocs.io) object, the
@@ -43,10 +59,10 @@ contig-level receptor table (Cell Ranger's `filtered_contig_annotations.csv` or
43
59
  and sample of each cell.
44
60
 
45
61
  ```python
46
- import scanpy as sc
62
+ import anndata as ad
47
63
  import threadfin as tf
48
64
 
49
- 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
50
66
 
51
67
  result = tf.run(
52
68
  adata,
@@ -110,9 +126,12 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
110
126
  * **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
111
127
  * **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
112
128
  * **Large data**: `n_jobs=-1` uses every CPU core ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
113
- * **Identical results**: `n_jobs` never changes a result. The automatically chosen clone map can change with the
114
- number of BLAS threads, so keep `OMP_NUM_THREADS` the same between runs; every statistic agrees to about 1e-7
115
- 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
116
135
  programmes; sort them first (`adata = adata[adata.obs_names.sort_values()].copy()`) when results must not
117
136
  depend on the order.
118
137
  * **Saving and reloading**: `adata.write_h5ad(...)` keeps the record of the run, and
@@ -120,6 +139,8 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
120
139
  after further `tf.tl` calls on the same AnnData.
121
140
  * **Jupyter**: start the notebook with `%matplotlib inline`. With matplotlib older than 3.9 (which the Dandelion
122
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.
123
144
 
124
145
  ### Run time and memory
125
146
 
@@ -149,6 +170,12 @@ about an hour for a million simulated cells on 8 cores
149
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` |
150
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) |
151
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.
152
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
153
180
  it is rebuilt from a saved file with `ThreadfinResult.from_adata`; every step of Tutorial 2 can be followed on the
154
181
  public data of Tutorial 5. Results are unchanged.
@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "threadfin"
7
- version = "4.6.2"
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,12 +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
58
  # 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"]
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'"]
56
63
  seq = ["parasail>=1.3"] # faster CDR3 alignment for the legacy v3 functions
57
64
  data = ["mudata>=0.3", "awkward>=2"] # reading scirpy/MuData example data
58
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"):
@@ -19,6 +19,17 @@ def sim():
19
19
  # --------------------------------------------------------------------------- variance components
20
20
 
21
21
 
22
+ def _png(fig) -> bytes:
23
+ """The figure as PNG bytes (closed afterwards)."""
24
+ import io
25
+
26
+ import matplotlib.pyplot as plt
27
+
28
+ buf = io.BytesIO()
29
+ fig.savefig(buf, format="png", dpi=80)
30
+ plt.close(fig)
31
+ return buf.getvalue()
32
+
22
33
  def test_singletons_do_not_enter_variance_components():
23
34
  x = np.arange(10, dtype=float)[:, None]
24
35
  codes = np.array([0, 0, 1, 1, 2, 3, 4, 5, 6, 7]) # only clones 0 and 1 have 2 cells
@@ -342,6 +353,9 @@ def test_the_result_stays_the_runs_own_after_later_calls(tmp_path):
342
353
  n_perm=10, n_boot=6, verbose=False)
343
354
  assert result.programmes.shape[0] > 1 and result.memory is not None and "true_programme" in result.tests
344
355
  summary, methods = result.summary(), result.methods()
356
+ # the figure of a fresh run is the one drawn from adata, byte for byte
357
+ figure = _png(result.plot())
358
+ assert figure == _png(tf.pl.overview(ad, state_key="true_state", coherence_result=result.coherence))
345
359
  record = ad.uns["threadfin"]["run"]
346
360
  assert list(record["profile_tests"]) == ["true_programme"] and list(record["tests"]) == ["true_programme"]
347
361
  ad.write_h5ad(tmp_path / "run.h5ad")
@@ -365,11 +379,15 @@ def test_the_result_stays_the_runs_own_after_later_calls(tmp_path):
365
379
  ad.write_h5ad(tmp_path / "later.h5ad")
366
380
 
367
381
  assert result.summary() == summary and result.methods() == methods
382
+ # the later map and programmes are in adata now; the result still draws its own
383
+ assert _png(tf.pl.overview(ad, state_key="true_state", coherence_result=result.coherence)) != figure
384
+ assert _png(result.plot()) == figure
368
385
  for again in (tf.ThreadfinResult.from_adata(anndata.read_h5ad(tmp_path / "run.h5ad")),
369
386
  tf.ThreadfinResult.from_adata(anndata.read_h5ad(tmp_path / "later.h5ad")),
370
387
  tf.ThreadfinResult.from_adata(ad)):
371
388
  assert again.summary() == summary
372
389
  assert again.methods() == methods
390
+ assert _png(again.plot()) == figure
373
391
  assert again.coherence["icc"] == result.coherence["icc"]
374
392
  assert again.coherence["p_value"] == result.coherence["p_value"]
375
393
  assert again.programmes.index.astype(str).tolist() == result.programmes.index.astype(str).tolist()
@@ -385,6 +403,45 @@ def test_the_result_stays_the_runs_own_after_later_calls(tmp_path):
385
403
  assert again.memory["memory_index"] == result.memory["memory_index"]
386
404
 
387
405
 
406
+ def test_clone_calls_made_before_the_run_stay_in_the_saved_methods(tmp_path):
407
+ """Clones called with define_clones_dandelion before run() (the notebook's workflow): the Methods paragraph
408
+ names the clone calling, also after saving and reloading, whether run() recognises the clone ids of this
409
+ session or methods(clone_ids) is given them."""
410
+ import anndata
411
+
412
+ from threadfin import dandelion as tfd
413
+
414
+ ad = tf.sim.simulate_repertoire(n_clones=400, random_state=5)
415
+ ids = ad.obs["clone_id"].copy()
416
+ ids.attrs.update({"method": "dandelion", "dandelion_version": "0.5.7", "donor_key": "donor",
417
+ "use_light_chain": True, "require_heavy_chain": True, "check_contigs": False,
418
+ "identity": {"ig": 0.85, "tr-ab": 1.0, "tr-gd": 1.0}, "dandelion_hash_seed": 0})
419
+ kw = dict(donor_key="donor", sample_key="context", basis="X_pca", map_n_neighbors=15, map_min_dist=0.5,
420
+ n_perm=10, n_boot=6, verbose=False)
421
+ saved = tfd._RECENT_CLONE_CALLS[:]
422
+ try:
423
+ tfd._RECENT_CLONE_CALLS.clear()
424
+ tfd._remember_clone_calls(ids) # as define_clones_dandelion does
425
+ with warnings.catch_warnings():
426
+ warnings.simplefilter("ignore")
427
+ first = tf.run(ad.copy(), **kw)
428
+ methods = first.methods()
429
+ assert "Clones were called with Dandelion 0.5.7 (ref. 1) within each donor ('donor')" in methods
430
+ first.adata.write_h5ad(tmp_path / "first.h5ad")
431
+ assert tf.ThreadfinResult.from_adata(anndata.read_h5ad(tmp_path / "first.h5ad")).methods() == methods
432
+
433
+ tfd._RECENT_CLONE_CALLS.clear() # clone ids of another session: not recognised
434
+ with warnings.catch_warnings():
435
+ warnings.simplefilter("ignore")
436
+ second = tf.run(ad.copy(), **kw)
437
+ assert "Clone identities were taken from adata.obs['clone_id']" in second.methods()
438
+ assert second.methods(clone_ids=ids) == methods
439
+ second.adata.write_h5ad(tmp_path / "second.h5ad")
440
+ assert second.methods() == methods
441
+ assert tf.ThreadfinResult.from_adata(anndata.read_h5ad(tmp_path / "second.h5ad")).methods() == methods
442
+ finally:
443
+ tfd._RECENT_CLONE_CALLS[:] = saved
444
+
388
445
  def test_run_warns_once_about_a_sample_level_label(sim):
389
446
  """Both label tests check a label fixed within each sample; run() says so once, not once per test."""
390
447
  ad = sim.copy()
@@ -29,6 +29,10 @@ from .io import attach_bcr, build_clone_key, read_10x_vdj, read_airr
29
29
  pl = plotting
30
30
  sim = simulate
31
31
 
32
+ from ._utils import check_neighbour_stack as _check_neighbour_stack # noqa: E402
33
+
34
+ _check_neighbour_stack() # warns when scanpy cannot read the installed pynndescent's neighbour graphs
35
+
32
36
  # v3 API, kept for backward compatibility
33
37
  from . import clones, metrics, migration, programs, sequence, specificity # noqa: E402
34
38
  from .bcrgraph import bcr_similarity_graph # noqa: E402
@@ -39,7 +43,7 @@ from .programs import community_markers, community_score # noqa: E402
39
43
  from .reclustering import reclustering_presets # noqa: E402
40
44
  from .specificity import annotate_specificity, specificity_enrichment # noqa: E402
41
45
 
42
- __version__ = "4.6.2"
46
+ __version__ = "4.7.0"
43
47
  __all__ = [
44
48
  "ThreadfinResult",
45
49
  "DensityResult",