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.
- {threadfin-4.6.1 → threadfin-4.7.0}/LICENSE +1 -1
- {threadfin-4.6.1/threadfin.egg-info → threadfin-4.7.0}/PKG-INFO +72 -20
- {threadfin-4.6.1 → threadfin-4.7.0}/README.md +66 -17
- {threadfin-4.6.1 → threadfin-4.7.0}/pyproject.toml +16 -7
- threadfin-4.7.0/tests/test_dependency_api.py +40 -0
- threadfin-4.7.0/tests/test_neighbour_search.py +121 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_parallel_and_robustness.py +16 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_user_inputs.py +8 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_v4_core.py +115 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/__init__.py +5 -1
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/_utils.py +115 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/api.py +156 -49
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/core.py +12 -5
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/dandelion.py +39 -5
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/export.py +7 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/expression.py +4 -3
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/maptune.py +12 -4
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/plotting.py +43 -9
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/pp.py +12 -4
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/profiles.py +16 -4
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/programmes.py +7 -4
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/programs.py +12 -8
- {threadfin-4.6.1 → threadfin-4.7.0/threadfin.egg-info}/PKG-INFO +72 -20
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin.egg-info/SOURCES.txt +2 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin.egg-info/requires.txt +8 -1
- {threadfin-4.6.1 → threadfin-4.7.0}/setup.cfg +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_api_reference.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_association_strata.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_bcrgraph_clones.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_bone_marrow_design.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_case_study_signatures.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_clone_state_sharing.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_clones_v3.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_dandelion_adapter.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_dandelion_seed.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_density.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_ebv_contig_matching.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_export.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_geneset_and_export.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_integrate.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_io.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_maptune.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_memory_reference.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_migration.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_phylo.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_profile_reproducibility.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_programs.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_read_paths.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_reclustering_presets.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_release_metadata.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_result_plots.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_sequence_v2.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_specificity.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_statistical_properties.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/tests/test_threadfin.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/_dandelion_worker.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/bcrgraph.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/clones.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/density.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/dynamics.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/heritability.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/integrate.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/io.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/metrics.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/migration.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/phylo.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/reclustering.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/sequence.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/simulate.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/specificity.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/stats.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin/tl.py +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin.egg-info/dependency_links.txt +0 -0
- {threadfin-4.6.1 → threadfin-4.7.0}/threadfin.egg-info/top_level.txt +0 -0
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: threadfin
|
|
3
|
-
Version: 4.
|
|
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
|
|
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
|
|
119
|
+
import anndata as ad
|
|
100
120
|
import threadfin as tf
|
|
101
121
|
|
|
102
|
-
adata =
|
|
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
|
|
156
|
-
|
|
157
|
-
|
|
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
|
-
* **
|
|
161
|
-
|
|
162
|
-
`tf.
|
|
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.
|
|
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
|
-
|
|
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
|
-
##
|
|
381
|
+
## How to cite
|
|
332
382
|
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
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
|
|
62
|
+
import anndata as ad
|
|
46
63
|
import threadfin as tf
|
|
47
64
|
|
|
48
|
-
adata =
|
|
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
|
|
102
|
-
|
|
103
|
-
|
|
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
|
-
* **
|
|
107
|
-
|
|
108
|
-
`tf.
|
|
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.
|
|
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
|
-
|
|
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
|
-
##
|
|
324
|
+
## How to cite
|
|
278
325
|
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
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.
|
|
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
|
|
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
|
|
41
|
-
#
|
|
42
|
-
|
|
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
|
|
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
|
|
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"):
|