threadfin 4.5.1__tar.gz → 4.5.3__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 (64) hide show
  1. {threadfin-4.5.1/threadfin.egg-info → threadfin-4.5.3}/PKG-INFO +19 -13
  2. {threadfin-4.5.1 → threadfin-4.5.3}/README.md +17 -11
  3. {threadfin-4.5.1 → threadfin-4.5.3}/pyproject.toml +6 -3
  4. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_user_inputs.py +45 -0
  5. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/__init__.py +1 -1
  6. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/api.py +26 -8
  7. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/programmes.py +7 -5
  8. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/stats.py +18 -0
  9. {threadfin-4.5.1 → threadfin-4.5.3/threadfin.egg-info}/PKG-INFO +19 -13
  10. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin.egg-info/requires.txt +1 -1
  11. {threadfin-4.5.1 → threadfin-4.5.3}/LICENSE +0 -0
  12. {threadfin-4.5.1 → threadfin-4.5.3}/setup.cfg +0 -0
  13. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_api_reference.py +0 -0
  14. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_bcrgraph_clones.py +0 -0
  15. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_bone_marrow_design.py +0 -0
  16. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_case_study_signatures.py +0 -0
  17. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_clone_state_sharing.py +0 -0
  18. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_clones_v3.py +0 -0
  19. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_dandelion_adapter.py +0 -0
  20. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_density.py +0 -0
  21. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_ebv_contig_matching.py +0 -0
  22. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_export.py +0 -0
  23. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_integrate.py +0 -0
  24. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_io.py +0 -0
  25. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_maptune.py +0 -0
  26. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_migration.py +0 -0
  27. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_parallel_and_robustness.py +0 -0
  28. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_phylo.py +0 -0
  29. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_profile_reproducibility.py +0 -0
  30. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_programs.py +0 -0
  31. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_reclustering_presets.py +0 -0
  32. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_release_metadata.py +0 -0
  33. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_sequence_v2.py +0 -0
  34. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_specificity.py +0 -0
  35. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_threadfin.py +0 -0
  36. {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_v4_core.py +0 -0
  37. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/_utils.py +0 -0
  38. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/bcrgraph.py +0 -0
  39. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/clones.py +0 -0
  40. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/core.py +0 -0
  41. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/dandelion.py +0 -0
  42. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/density.py +0 -0
  43. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/dynamics.py +0 -0
  44. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/export.py +0 -0
  45. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/expression.py +0 -0
  46. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/heritability.py +0 -0
  47. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/integrate.py +0 -0
  48. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/io.py +0 -0
  49. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/maptune.py +0 -0
  50. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/metrics.py +0 -0
  51. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/migration.py +0 -0
  52. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/phylo.py +0 -0
  53. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/plotting.py +0 -0
  54. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/pp.py +0 -0
  55. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/profiles.py +0 -0
  56. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/programs.py +0 -0
  57. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/reclustering.py +0 -0
  58. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/sequence.py +0 -0
  59. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/simulate.py +0 -0
  60. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/specificity.py +0 -0
  61. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/tl.py +0 -0
  62. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin.egg-info/SOURCES.txt +0 -0
  63. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin.egg-info/dependency_links.txt +0 -0
  64. {threadfin-4.5.1 → threadfin-4.5.3}/threadfin.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: threadfin
3
- Version: 4.5.1
3
+ Version: 4.5.3
4
4
  Summary: Relationships between B-cell clones from paired single-cell RNA and BCR sequencing: clone embeddings, clonal coherence, clonal programmes, clone-level tests and clonal memory
5
5
  Author-email: Chen Satoshi <103236530+Reynold4k@users.noreply.github.com>
6
6
  License: MIT
@@ -33,7 +33,7 @@ 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.5.8
36
+ Requires-Dist: pynndescent<0.7,>=0.5.8
37
37
  Requires-Dist: harmonypy>=0.0.9; platform_system != "Windows"
38
38
  Requires-Dist: harmonypy<2,>=0.0.9; platform_system == "Windows"
39
39
  Provides-Extra: dandelion
@@ -66,7 +66,7 @@ Dynamic: license-file
66
66
  <a href="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml"><img src="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
67
67
  <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
68
  <a href="https://pypi.org/project/threadfin/"><img src="https://img.shields.io/pypi/v/threadfin.svg" alt="PyPI version"></a>
69
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
69
+ <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>
70
70
  </p>
71
71
 
72
72
  Threadfin takes paired single-cell RNA and receptor (BCR or TCR) sequencing and describes every clone by the
@@ -78,12 +78,13 @@ distribution of its cells' transcriptional states, so that clones, not cells, ca
78
78
 
79
79
  ```bash
80
80
  pip install threadfin # Python 3.10–3.14 on Linux, macOS or Windows; no GPU or R needed
81
- pip install "threadfin[dandelion]" # also installs Dandelion (0.5.x), to call clones from BCR or TCR contigs
81
+ pip install "threadfin[dandelion]" # also installs Dandelion (0.5.x), to call clones from BCR or TCR contigs; Python 3.10–3.12
82
82
  ```
83
83
 
84
84
  Scanpy, Leiden, UMAP and Harmony are installed with it. Dandelion's clone calls depend on Python's hash seed:
85
85
  start Python with `PYTHONHASHSEED=0` when clone ids must be identical run after run. Threadfin is validated with
86
- Dandelion 0.5.x; Dandelion 1.0 (October 2026) calls clones differently, so the extra installs `sc-dandelion<1`. The development version
86
+ Dandelion 0.5.x; Dandelion 1.0 (October 2026) calls clones differently, so the extra installs `sc-dandelion<1`,
87
+ with matplotlib < 3.9 (which Dandelion 0.5 needs, and which has no packages for Python 3.13 or later). The development version
87
88
  installs with `pip install "git+https://github.com/Reynold4k/Threadfin.git"`.
88
89
 
89
90
  ### 2. Run
@@ -109,16 +110,17 @@ result = tf.run(
109
110
  ```
110
111
 
111
112
  `tf.run` calls clones within each donor (Dandelion, paired chains), builds an expression embedding without the
112
- receptor genes, estimates one profile per clone, tests clonal coherence, lays out the clone map and looks for
113
- clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to 15 minutes with 8 cores.
113
+ receptor genes, estimates one profile per clone with two or more cells, tests clonal coherence, lays out the
114
+ clone map and looks for clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to
115
+ 15 minutes with 8 cores.
114
116
 
115
117
  ### 3. Read the results
116
118
 
117
119
  ```python
118
120
  print(result.summary()) # plain-language report
119
- result.plot("threadfin_overview.pdf") # clone map, coherence, stability, composition
121
+ result.plot("threadfin_overview.pdf") # clone map, coherence, stability, programme sizes or composition
120
122
  print(result.methods()) # a Methods paragraph with the settings and versions used
121
- result.clones.to_csv("clones.csv") # one row per clone: size, reliability, programme, map position
123
+ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, reliability, programme, map position
122
124
  ```
123
125
 
124
126
  <p align="center">
@@ -157,7 +159,9 @@ result.clones.to_csv("clones.csv") # one row per clone: size, reliability,
157
159
  | [4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
158
160
  | [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) |
159
161
 
160
- 4.5.1 pins Dandelion below 1.0 and fixes T-cell contig files passed as a path. New in 4.5.0: T cells, scirpy input, `result.methods()` and gene-level summaries of the clone landscape
162
+ 4.5.2 lists labels that are fixed within each donor (age, sex) as not testable instead of reporting p = 1, and
163
+ reads raw counts from a layer (`counts_layer=`); 4.5.1 pins Dandelion below 1.0. New in 4.5.0: T cells, scirpy
164
+ input, `result.methods()` and gene-level summaries of the clone landscape
161
165
  ([changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md)).
162
166
 
163
167
  ---
@@ -184,9 +188,11 @@ state* need the clone as the unit of representation and of statistical inference
184
188
  repertoires sampled *in vivo* make this difficult, and Threadfin addresses each:
185
189
 
186
190
  * **Most clones are captured as one or a few cells.** Profiles are shrunk according to the number of cells
187
- sampled, and each clone carries a reliability score. No clone is discarded for being small.
191
+ sampled, and every clone with two or more cells carries a reliability score: none is discarded for being
192
+ small.
188
193
  * **Clone membership is confounded with donor, sample, tissue and sorting gate.** Each clone is described
189
- relative to the cells sampled with it, and every test shuffles labels within the sampling design.
194
+ relative to the cells sampled with it, and every permutation test shuffles labels within the sampling
195
+ design.
190
196
  * **Treating cells as independent inflates significance.** Tests use clones, not cells, as replicates.
191
197
 
192
198
  ## What Threadfin answers
@@ -293,7 +299,7 @@ error rate when samples differ, where per-clone graph scores and cell-level test
293
299
  measured clone annotations Threadfin is comparable to clone2vec and to a simple mean of the cells'
294
300
  coordinates, and better than Clonotrace at its default and than Benisse; in simulation, clone2vec groups clones by their
295
301
  planted programme and tells mixed from in-between clones more accurately. Threadfin needs a fraction of the
296
- others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 300 to 2,400
302
+ others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 290 to 2,400
297
303
  times) and finished every run without help; a million cells take about an hour on 8 cores
298
304
  ([scalability](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/scalability/README.md)).
299
305
  The benchmark reports every result, including those where Threadfin is not the best.
@@ -12,7 +12,7 @@
12
12
  <a href="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml"><img src="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
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
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
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
16
  </p>
17
17
 
18
18
  Threadfin takes paired single-cell RNA and receptor (BCR or TCR) sequencing and describes every clone by the
@@ -24,12 +24,13 @@ distribution of its cells' transcriptional states, so that clones, not cells, ca
24
24
 
25
25
  ```bash
26
26
  pip install threadfin # Python 3.10–3.14 on Linux, macOS or Windows; no GPU or R needed
27
- pip install "threadfin[dandelion]" # also installs Dandelion (0.5.x), to call clones from BCR or TCR contigs
27
+ pip install "threadfin[dandelion]" # also installs Dandelion (0.5.x), to call clones from BCR or TCR contigs; Python 3.10–3.12
28
28
  ```
29
29
 
30
30
  Scanpy, Leiden, UMAP and Harmony are installed with it. Dandelion's clone calls depend on Python's hash seed:
31
31
  start Python with `PYTHONHASHSEED=0` when clone ids must be identical run after run. Threadfin is validated with
32
- Dandelion 0.5.x; Dandelion 1.0 (October 2026) calls clones differently, so the extra installs `sc-dandelion<1`. The development version
32
+ Dandelion 0.5.x; Dandelion 1.0 (October 2026) calls clones differently, so the extra installs `sc-dandelion<1`,
33
+ with matplotlib < 3.9 (which Dandelion 0.5 needs, and which has no packages for Python 3.13 or later). The development version
33
34
  installs with `pip install "git+https://github.com/Reynold4k/Threadfin.git"`.
34
35
 
35
36
  ### 2. Run
@@ -55,16 +56,17 @@ result = tf.run(
55
56
  ```
56
57
 
57
58
  `tf.run` calls clones within each donor (Dandelion, paired chains), builds an expression embedding without the
58
- receptor genes, estimates one profile per clone, tests clonal coherence, lays out the clone map and looks for
59
- clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to 15 minutes with 8 cores.
59
+ receptor genes, estimates one profile per clone with two or more cells, tests clonal coherence, lays out the
60
+ clone map and looks for clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to
61
+ 15 minutes with 8 cores.
60
62
 
61
63
  ### 3. Read the results
62
64
 
63
65
  ```python
64
66
  print(result.summary()) # plain-language report
65
- result.plot("threadfin_overview.pdf") # clone map, coherence, stability, composition
67
+ result.plot("threadfin_overview.pdf") # clone map, coherence, stability, programme sizes or composition
66
68
  print(result.methods()) # a Methods paragraph with the settings and versions used
67
- result.clones.to_csv("clones.csv") # one row per clone: size, reliability, programme, map position
69
+ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, reliability, programme, map position
68
70
  ```
69
71
 
70
72
  <p align="center">
@@ -103,7 +105,9 @@ result.clones.to_csv("clones.csv") # one row per clone: size, reliability,
103
105
  | [4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
104
106
  | [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) |
105
107
 
106
- 4.5.1 pins Dandelion below 1.0 and fixes T-cell contig files passed as a path. New in 4.5.0: T cells, scirpy input, `result.methods()` and gene-level summaries of the clone landscape
108
+ 4.5.2 lists labels that are fixed within each donor (age, sex) as not testable instead of reporting p = 1, and
109
+ reads raw counts from a layer (`counts_layer=`); 4.5.1 pins Dandelion below 1.0. New in 4.5.0: T cells, scirpy
110
+ input, `result.methods()` and gene-level summaries of the clone landscape
107
111
  ([changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md)).
108
112
 
109
113
  ---
@@ -130,9 +134,11 @@ state* need the clone as the unit of representation and of statistical inference
130
134
  repertoires sampled *in vivo* make this difficult, and Threadfin addresses each:
131
135
 
132
136
  * **Most clones are captured as one or a few cells.** Profiles are shrunk according to the number of cells
133
- sampled, and each clone carries a reliability score. No clone is discarded for being small.
137
+ sampled, and every clone with two or more cells carries a reliability score: none is discarded for being
138
+ small.
134
139
  * **Clone membership is confounded with donor, sample, tissue and sorting gate.** Each clone is described
135
- relative to the cells sampled with it, and every test shuffles labels within the sampling design.
140
+ relative to the cells sampled with it, and every permutation test shuffles labels within the sampling
141
+ design.
136
142
  * **Treating cells as independent inflates significance.** Tests use clones, not cells, as replicates.
137
143
 
138
144
  ## What Threadfin answers
@@ -239,7 +245,7 @@ error rate when samples differ, where per-clone graph scores and cell-level test
239
245
  measured clone annotations Threadfin is comparable to clone2vec and to a simple mean of the cells'
240
246
  coordinates, and better than Clonotrace at its default and than Benisse; in simulation, clone2vec groups clones by their
241
247
  planted programme and tells mixed from in-between clones more accurately. Threadfin needs a fraction of the
242
- others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 300 to 2,400
248
+ others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 290 to 2,400
243
249
  times) and finished every run without help; a million cells take about an hour on 8 cores
244
250
  ([scalability](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/scalability/README.md)).
245
251
  The benchmark reports every result, including those where Threadfin is not the best.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "threadfin"
7
- version = "4.5.1"
7
+ version = "4.5.3"
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"
@@ -37,14 +37,17 @@ 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
- "pynndescent>=0.5.8", # likewise
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",
41
43
  "harmonypy>=0.0.9; platform_system != 'Windows'",
42
44
  # harmonypy 2.x ships no Windows wheels and does not compile with MSVC; 0.2 and earlier are pure Python
43
45
  "harmonypy>=0.0.9,<2; platform_system == 'Windows'",
44
46
  ]
45
47
 
46
48
  [project.optional-dependencies]
47
- # clone definition with Dandelion; sc-dandelion 0.5.7 uses matplotlib.cm.get_cmap, removed in matplotlib 3.9.
49
+ # clone definition with Dandelion; sc-dandelion 0.5.7 imports nxviz, which uses matplotlib.cm.get_cmap, removed in
50
+ # matplotlib 3.9. matplotlib < 3.9 has wheels only for Python <= 3.12, so the extra needs Python 3.10-3.12.
48
51
  # sc-dandelion 1.0 (2026-10-25) calls clones differently and is not yet validated, hence < 1.
49
52
  dandelion = ["sc-dandelion>=0.5.7,<1", "matplotlib>=3.7,<3.9"]
50
53
  seq = ["parasail>=1.3"] # faster CDR3 alignment for the legacy v3 functions
@@ -199,3 +199,48 @@ def test_overview_is_drawn_when_no_programmes_were_found():
199
199
  res = tf.run(adata, basis="X_pca", donor_key="donor", sample_key="context", n_perm=10, n_boot=3, verbose=False)
200
200
  assert res.programmes.empty
201
201
  assert res.plot() is not None
202
+
203
+
204
+ def test_run_builds_the_embedding_from_a_counts_layer(synthetic):
205
+ """Scanpy's usual layout - normalised values in X, raw counts in a layer - works with counts_layer=."""
206
+ import warnings
207
+
208
+ import scanpy as sc
209
+
210
+ adata, bcr, _ = synthetic
211
+ adata.obs["clone_id"] = bcr["clone_id"].reindex(adata.obs_names).to_numpy()
212
+ kw = dict(n_perm=10, n_boot=5, map_n_neighbors=15, map_min_dist=0.5, verbose=False)
213
+ raw, layered = adata.copy(), adata.copy()
214
+ layered.layers["counts"] = layered.X.copy()
215
+ sc.pp.normalize_total(layered)
216
+ sc.pp.log1p(layered)
217
+ with warnings.catch_warnings():
218
+ warnings.simplefilter("ignore")
219
+ tf.run(raw, **kw)
220
+ tf.run(layered, counts_layer="counts", **kw)
221
+ np.testing.assert_allclose(layered.obsm["X_threadfin"], raw.obsm["X_threadfin"])
222
+ with pytest.raises(KeyError, match="counts_layer 'raw' is not in adata.layers"):
223
+ tf.run(adata.copy(), counts_layer="raw", **kw)
224
+
225
+
226
+ def test_a_label_fixed_within_each_donor_is_reported_as_untestable():
227
+ """Shuffling within donors cannot test a donor's age or sex: the run says so instead of reporting p = 1, and
228
+ the summary numbers its sections in the order they appear."""
229
+ import warnings
230
+
231
+ adata = tf.sim.simulate_repertoire(n_clones=1500, n_timepoints=2, random_state=2)
232
+ donors = sorted(adata.obs["donor"].astype(str).unique())
233
+ age = {d: ("old", "young")[i % 2] for i, d in enumerate(donors)}
234
+ adata.obs["age_group"] = adata.obs["donor"].astype(str).map(age)
235
+ with warnings.catch_warnings():
236
+ warnings.simplefilter("ignore")
237
+ result = tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca", n_perm=20, n_boot=5,
238
+ test=["age_group"], time_key="timepoint", map_n_neighbors=30, map_min_dist=0.5,
239
+ verbose=False)
240
+ assert "age_group" not in result.profile_tests and "age_group" not in result.tests
241
+ assert "does not vary among the clones of any single 'donor'" in result.skipped["clone-level test of 'age_group'"]
242
+ assert "programme test of 'age_group'" not in result.skipped # the same reason is given once
243
+ text = result.summary()
244
+ assert "3. Do clones keep their state over 'timepoint'?" in text and "\n4. " not in text
245
+ with pytest.raises(ValueError, match="does not vary among the clones of any single 'donor'"):
246
+ tf.tl.profile_association(adata, "age_group", verbose=False)
@@ -39,7 +39,7 @@ from .programs import community_markers, community_score # noqa: E402
39
39
  from .reclustering import reclustering_presets # noqa: E402
40
40
  from .specificity import annotate_specificity, specificity_enrichment # noqa: E402
41
41
 
42
- __version__ = "4.5.1"
42
+ __version__ = "4.5.3"
43
43
  __all__ = [
44
44
  "ThreadfinResult",
45
45
  "DensityResult",
@@ -10,8 +10,9 @@ RNA-seq + BCR-seq dataset, in this order:
10
10
  into *clonal programmes* by the state bias of their cells (for example
11
11
  "plasmablast-biased" or "germinal-centre-retained" clones). Every split
12
12
  between programmes must pass a significance test, and every programme
13
- gets a bootstrap stability score; if no split is significant, the clones
14
- vary along a continuum and a single programme is reported.
13
+ gets a bootstrap stability score; if no split is significant, a single
14
+ programme is reported (the clones differ, but not as groups the test can
15
+ separate).
15
16
  3. **Do your labels explain how clones differ?** - optional clone-level
16
17
  tests against any labels you have (antigen specificity, isotype,
17
18
  infection, disease group): first whether the label explains clone
@@ -166,7 +167,7 @@ class ThreadfinResult:
166
167
  tests = get_programmes(ad).get("split_tests", pd.DataFrame())
167
168
  p_root = f" (split test p = {tests['pvalue'].iloc[0]:.2g})" if not tests.empty else ""
168
169
  lines.append(f" No distinct programmes: the {int(prog['n_clones'].sum()):,} reliable clones differ, "
169
- f"but along a continuum rather than in separate groups{p_root}.")
170
+ f"but no split into separate groups was significant{p_root}.")
170
171
  else:
171
172
  params = get_programmes(ad)["params"]
172
173
  n_stable = int((prog["stability"] >= params["stability_threshold"]).sum())
@@ -182,8 +183,10 @@ class ThreadfinResult:
182
183
  flag = "" if row["stability"] >= 0.6 else " [unstable - do not interpret]"
183
184
  lines.append(f" {name}: {int(row['n_clones']):,} clones, {int(row['n_cells']):,} cells, "
184
185
  f"stability {row['stability']:.2f}{desc}{flag}")
186
+ section = 3 # the optional sections are numbered in the order they appear
185
187
  if self.profile_tests or self.tests:
186
- lines += ["", "3. Do your labels explain how clones differ? (clone-level tests)"]
188
+ lines += ["", f"{section}. Do your labels explain how clones differ? (clone-level tests)"]
189
+ section += 1
187
190
  for label, r in self.profile_tests.items():
188
191
  verdict = "explains" if r["p_value"] < 0.05 else "does not significantly explain"
189
192
  lines.append(f" {label} {verdict} clone states: {100 * r['r2']:.1f}% of clone-profile variance "
@@ -211,7 +214,7 @@ class ThreadfinResult:
211
214
  lo, hi = m["memory_index_ci"]
212
215
  lines += [
213
216
  "",
214
- f"4. Do clones keep their state over '{m['time_key']}'? (clonal memory)",
217
+ f"{section}. Do clones keep their state over '{m['time_key']}'? (clonal memory)",
215
218
  f" {m['n_clones']} clones seen at >= 2 levels: memory index {m['memory_index']:.2f} "
216
219
  f"[{lo:.2f}, {hi:.2f}], p = {m['p_value']:.3g} (1 = clones stay as distinct as they were, "
217
220
  "0 = no more similar to their earlier self than to a random clone).",
@@ -432,6 +435,7 @@ def run(
432
435
  test=None,
433
436
  clone_key: str = "clone_id",
434
437
  basis: str | None = None,
438
+ counts_layer: str | None = None,
435
439
  representation: str = "kernel",
436
440
  map_n_neighbors: int | str = "auto",
437
441
  map_min_dist: float | str = "auto",
@@ -448,7 +452,8 @@ def run(
448
452
  ----------
449
453
  adata
450
454
  AnnData of B cells, or T cells (one row per cell). Needs raw counts in
451
- ``X`` (or ``layers['counts']``) unless you pass a ready-made ``basis``.
455
+ ``X`` (or in the layer named by ``counts_layer``) unless you pass a
456
+ ready-made ``basis``.
452
457
  bcr
453
458
  Receptor data, BCR or TCR: a path to a Cell Ranger
454
459
  ``filtered_contig_annotations.csv`` or an AIRR ``.tsv``, a contig-level
@@ -482,6 +487,10 @@ def run(
482
487
  Existing ``obsm`` embedding to use instead of building one. It
483
488
  should exclude immunoglobulin genes (see
484
489
  :func:`threadfin.pp.ig_gene_mask`).
490
+ counts_layer
491
+ ``layers`` key holding the raw counts, when ``X`` holds normalised
492
+ values (for example ``"counts"`` after Scanpy's preprocessing). Used
493
+ only to build the embedding (:func:`threadfin.pp.prepare_embedding`).
485
494
  representation
486
495
  How each clone is summarised for grouping into programmes:
487
496
  ``"kernel"`` (default; the whole distribution of the clone's cells,
@@ -536,6 +545,9 @@ def run(
536
545
  require_obs(adata, donor_key, sample_key, state_key, time_key, batch_key, *test_cols,
537
546
  context="threadfin.run()")
538
547
  require_complete_groups(adata, donor_key, sample_key, batch_key, context="threadfin.run()")
548
+ if counts_layer is not None and counts_layer not in adata.layers:
549
+ raise KeyError(f"counts_layer '{counts_layer}' is not in adata.layers (layers: "
550
+ f"{', '.join(map(repr, adata.layers.keys())) or 'none'}).")
539
551
  require_positive_int(n_perm, "n_perm")
540
552
  require_positive_int(n_boot, "n_boot")
541
553
  if representation not in {"mean", "kernel"}:
@@ -604,7 +616,8 @@ def run(
604
616
  if basis is None:
605
617
  basis = "X_threadfin"
606
618
  if basis not in adata.obsm:
607
- prepare_embedding(adata, batch_key=batch_key, random_state=random_state, verbose=verbose)
619
+ prepare_embedding(adata, counts_layer=counts_layer, batch_key=batch_key, random_state=random_state,
620
+ verbose=verbose)
608
621
 
609
622
  # Step 3 - one profile per clone, relative to its own sample
610
623
  clone_profiles(adata, clone_key=clone_key, basis=basis, context_key=sample_key,
@@ -642,7 +655,12 @@ def run(
642
655
  skipped[f"clone-level test of '{col}'"] = str(e)
643
656
  log(f"profile test '{col}' skipped: {e}", verbose)
644
657
  if programmes.shape[0] >= 2: # which programmes differ? (needs >= 2 programmes)
645
- tests[col] = association_test(adata, col, random_state=random_state, verbose=verbose)
658
+ try:
659
+ tests[col] = association_test(adata, col, random_state=random_state, verbose=verbose)
660
+ except ValueError as e:
661
+ if str(e) not in skipped.values(): # the profile test already reported the same reason
662
+ skipped[f"programme test of '{col}'"] = str(e)
663
+ log(f"programme test '{col}' skipped: {e}", verbose)
646
664
  memory = None
647
665
  if time_key is not None:
648
666
  # optional like the label tests: a time point or tissue column that cannot be tested (e.g. no clone seen at
@@ -23,8 +23,9 @@ continuously without forming groups. Two safeguards address this:
23
23
  work (Meinshausen 2008; sc-SHC, Grabski et al. 2023), but this implementation
24
24
  does not establish family-wise error control for the selected tree. Communities below a non-significant
25
25
  node are merged. When even the root is not significant, the clones form
26
- a single programme: they differ (see the coherence test) but along a
27
- continuum rather than in distinct groups.
26
+ a single programme: they differ (see the coherence test), but not as
27
+ groups the test can separate. This alone is not evidence of a continuum
28
+ (see :func:`split_test`).
28
29
  2. **Bootstrap stability.** Cells are resampled within clones (Poisson
29
30
  bootstrap), profiles are re-estimated and the whole procedure (graph,
30
31
  Leiden, split test) is repeated; each programme is matched to its best
@@ -33,7 +34,8 @@ continuously without forming groups. Two safeguards address this:
33
34
  not be interpreted.
34
35
 
35
36
  The Leiden resolution is chosen as the finest one whose size-weighted
36
- stability reaches the threshold, instead of being fixed by hand.
37
+ stability reaches the threshold (otherwise the most stable one, with a
38
+ warning), instead of being fixed by hand.
37
39
  """
38
40
 
39
41
  from __future__ import annotations
@@ -704,8 +706,8 @@ def find_programmes(
704
706
  extra = (f"; {int(table[f'{key_added}_assigned'].notna().sum())} of {len(table)} profiled clones "
705
707
  f"assigned with posterior >= {min_posterior}" if assign_remaining else "")
706
708
  if summary.shape[0] == 1:
707
- log(f"programmes: no significant split among {eligible.size} core clones (resolution {chosen}): the "
708
- "clones differ, but along a continuum rather than in distinct programmes.", verbose)
709
+ log(f"programmes: no significant split among {eligible.size} core clones (resolution {chosen}): one "
710
+ "programme. The clones differ, but not as groups the split test can separate.", verbose)
709
711
  else:
710
712
  n_merged = int((~split_tests["split"]).sum()) if not split_tests.empty else 0
711
713
  merged_txt = f" after merging {n_merged} non-significant split(s)" if n_merged else ""
@@ -178,6 +178,18 @@ def _mantel_haenszel(a, b, c, d):
178
178
  return float(np.exp(lor)), float(np.exp(lor - half)), float(np.exp(lor + half))
179
179
 
180
180
 
181
+ def _require_variation_within_strata(labels: pd.Series, strata, label_key: str, strata_key: str | None) -> None:
182
+ """Refuse a label that never varies among the clones of one stratum: shuffling within strata cannot test it."""
183
+ df = pd.DataFrame({"label": np.asarray(labels), "stratum": np.asarray(strata)})
184
+ if strata_key is None or df["label"].nunique() < 2: # one value overall is reported by the caller
185
+ return
186
+ if not df.groupby("stratum")["label"].nunique().gt(1).any():
187
+ raise ValueError(
188
+ f"'{label_key}' does not vary among the clones of any single '{strata_key}', so shuffling it within "
189
+ f"'{strata_key}' cannot test it: it is a property of each {strata_key}. Compare the {strata_key}s "
190
+ f"instead, with one value per {strata_key}.")
191
+
192
+
181
193
  def _assoc_table(adata, label_key, programme_key, clone_key, strata_key, how, min_frac):
182
194
  prof = get_profiles(adata)
183
195
  table = prof["clone_table"]
@@ -219,6 +231,8 @@ def association_test(
219
231
  clone (:func:`clone_labels`). P-values come from permuting clone labels
220
232
  within strata (default: donor), which keeps every donor's label
221
233
  frequencies fixed; Benjamini-Hochberg FDR is computed across all rows.
234
+ A label that never varies within a stratum (a donor's age or sex) cannot
235
+ be tested this way and raises ``ValueError``.
222
236
 
223
237
  *Categorical labels* (e.g. antigen specificity, isotype, infection
224
238
  status) give one row per (programme, level) with the observed and
@@ -250,6 +264,7 @@ def association_test(
250
264
  df = _assoc_table(adata, label_key, programme_key, clone_key, strata_key, how, min_frac)
251
265
  if df.empty:
252
266
  raise ValueError(f"No clones with both a programme and a '{label_key}' value.")
267
+ _require_variation_within_strata(df["label"], df["stratum"], label_key, strata_key)
253
268
  rng = np.random.default_rng(random_state)
254
269
  prog_codes, progs = codes(df["programme"])
255
270
  if len(progs) < 2:
@@ -299,6 +314,8 @@ def profile_association(
299
314
  captured by a linear trend in the label (numeric labels, as in
300
315
  distance-based redundancy analysis; McArdle & Anderson 2001). The
301
316
  p-value comes from permuting labels among clones within strata (donors).
317
+ A label that never varies within a stratum (a donor's age or sex) cannot
318
+ be tested this way and raises ``ValueError``.
302
319
 
303
320
  Parameters
304
321
  ----------
@@ -346,6 +363,7 @@ def profile_association(
346
363
  y = labels.loc[use]
347
364
  strata = (codes(table.loc[use, strata_key].astype(str))[0] if strata_key is not None
348
365
  else np.zeros(use.size, dtype=np.int64))
366
+ _require_variation_within_strata(y, strata, label_key, strata_key)
349
367
  numeric = pd.api.types.is_numeric_dtype(y) and not pd.api.types.is_bool_dtype(y)
350
368
  rng = np.random.default_rng(random_state)
351
369
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: threadfin
3
- Version: 4.5.1
3
+ Version: 4.5.3
4
4
  Summary: Relationships between B-cell clones from paired single-cell RNA and BCR sequencing: clone embeddings, clonal coherence, clonal programmes, clone-level tests and clonal memory
5
5
  Author-email: Chen Satoshi <103236530+Reynold4k@users.noreply.github.com>
6
6
  License: MIT
@@ -33,7 +33,7 @@ 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.5.8
36
+ Requires-Dist: pynndescent<0.7,>=0.5.8
37
37
  Requires-Dist: harmonypy>=0.0.9; platform_system != "Windows"
38
38
  Requires-Dist: harmonypy<2,>=0.0.9; platform_system == "Windows"
39
39
  Provides-Extra: dandelion
@@ -66,7 +66,7 @@ Dynamic: license-file
66
66
  <a href="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml"><img src="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
67
67
  <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
68
  <a href="https://pypi.org/project/threadfin/"><img src="https://img.shields.io/pypi/v/threadfin.svg" alt="PyPI version"></a>
69
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
69
+ <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>
70
70
  </p>
71
71
 
72
72
  Threadfin takes paired single-cell RNA and receptor (BCR or TCR) sequencing and describes every clone by the
@@ -78,12 +78,13 @@ distribution of its cells' transcriptional states, so that clones, not cells, ca
78
78
 
79
79
  ```bash
80
80
  pip install threadfin # Python 3.10–3.14 on Linux, macOS or Windows; no GPU or R needed
81
- pip install "threadfin[dandelion]" # also installs Dandelion (0.5.x), to call clones from BCR or TCR contigs
81
+ pip install "threadfin[dandelion]" # also installs Dandelion (0.5.x), to call clones from BCR or TCR contigs; Python 3.10–3.12
82
82
  ```
83
83
 
84
84
  Scanpy, Leiden, UMAP and Harmony are installed with it. Dandelion's clone calls depend on Python's hash seed:
85
85
  start Python with `PYTHONHASHSEED=0` when clone ids must be identical run after run. Threadfin is validated with
86
- Dandelion 0.5.x; Dandelion 1.0 (October 2026) calls clones differently, so the extra installs `sc-dandelion<1`. The development version
86
+ Dandelion 0.5.x; Dandelion 1.0 (October 2026) calls clones differently, so the extra installs `sc-dandelion<1`,
87
+ with matplotlib < 3.9 (which Dandelion 0.5 needs, and which has no packages for Python 3.13 or later). The development version
87
88
  installs with `pip install "git+https://github.com/Reynold4k/Threadfin.git"`.
88
89
 
89
90
  ### 2. Run
@@ -109,16 +110,17 @@ result = tf.run(
109
110
  ```
110
111
 
111
112
  `tf.run` calls clones within each donor (Dandelion, paired chains), builds an expression embedding without the
112
- receptor genes, estimates one profile per clone, tests clonal coherence, lays out the clone map and looks for
113
- clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to 15 minutes with 8 cores.
113
+ receptor genes, estimates one profile per clone with two or more cells, tests clonal coherence, lays out the
114
+ clone map and looks for clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to
115
+ 15 minutes with 8 cores.
114
116
 
115
117
  ### 3. Read the results
116
118
 
117
119
  ```python
118
120
  print(result.summary()) # plain-language report
119
- result.plot("threadfin_overview.pdf") # clone map, coherence, stability, composition
121
+ result.plot("threadfin_overview.pdf") # clone map, coherence, stability, programme sizes or composition
120
122
  print(result.methods()) # a Methods paragraph with the settings and versions used
121
- result.clones.to_csv("clones.csv") # one row per clone: size, reliability, programme, map position
123
+ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, reliability, programme, map position
122
124
  ```
123
125
 
124
126
  <p align="center">
@@ -157,7 +159,9 @@ result.clones.to_csv("clones.csv") # one row per clone: size, reliability,
157
159
  | [4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
158
160
  | [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) |
159
161
 
160
- 4.5.1 pins Dandelion below 1.0 and fixes T-cell contig files passed as a path. New in 4.5.0: T cells, scirpy input, `result.methods()` and gene-level summaries of the clone landscape
162
+ 4.5.2 lists labels that are fixed within each donor (age, sex) as not testable instead of reporting p = 1, and
163
+ reads raw counts from a layer (`counts_layer=`); 4.5.1 pins Dandelion below 1.0. New in 4.5.0: T cells, scirpy
164
+ input, `result.methods()` and gene-level summaries of the clone landscape
161
165
  ([changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md)).
162
166
 
163
167
  ---
@@ -184,9 +188,11 @@ state* need the clone as the unit of representation and of statistical inference
184
188
  repertoires sampled *in vivo* make this difficult, and Threadfin addresses each:
185
189
 
186
190
  * **Most clones are captured as one or a few cells.** Profiles are shrunk according to the number of cells
187
- sampled, and each clone carries a reliability score. No clone is discarded for being small.
191
+ sampled, and every clone with two or more cells carries a reliability score: none is discarded for being
192
+ small.
188
193
  * **Clone membership is confounded with donor, sample, tissue and sorting gate.** Each clone is described
189
- relative to the cells sampled with it, and every test shuffles labels within the sampling design.
194
+ relative to the cells sampled with it, and every permutation test shuffles labels within the sampling
195
+ design.
190
196
  * **Treating cells as independent inflates significance.** Tests use clones, not cells, as replicates.
191
197
 
192
198
  ## What Threadfin answers
@@ -293,7 +299,7 @@ error rate when samples differ, where per-clone graph scores and cell-level test
293
299
  measured clone annotations Threadfin is comparable to clone2vec and to a simple mean of the cells'
294
300
  coordinates, and better than Clonotrace at its default and than Benisse; in simulation, clone2vec groups clones by their
295
301
  planted programme and tells mixed from in-between clones more accurately. Threadfin needs a fraction of the
296
- others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 300 to 2,400
302
+ others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 290 to 2,400
297
303
  times) and finished every run without help; a million cells take about an hour on 8 cores
298
304
  ([scalability](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/scalability/README.md)).
299
305
  The benchmark reports every result, including those where Threadfin is not the best.
@@ -9,7 +9,7 @@ matplotlib>=3.7
9
9
  igraph>=0.10
10
10
  leidenalg>=0.10
11
11
  umap-learn>=0.5.5
12
- pynndescent>=0.5.8
12
+ pynndescent<0.7,>=0.5.8
13
13
 
14
14
  [:platform_system != "Windows"]
15
15
  harmonypy>=0.0.9
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes