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.
- {threadfin-4.5.1/threadfin.egg-info → threadfin-4.5.3}/PKG-INFO +19 -13
- {threadfin-4.5.1 → threadfin-4.5.3}/README.md +17 -11
- {threadfin-4.5.1 → threadfin-4.5.3}/pyproject.toml +6 -3
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_user_inputs.py +45 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/__init__.py +1 -1
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/api.py +26 -8
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/programmes.py +7 -5
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/stats.py +18 -0
- {threadfin-4.5.1 → threadfin-4.5.3/threadfin.egg-info}/PKG-INFO +19 -13
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin.egg-info/requires.txt +1 -1
- {threadfin-4.5.1 → threadfin-4.5.3}/LICENSE +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/setup.cfg +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_api_reference.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_bcrgraph_clones.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_bone_marrow_design.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_case_study_signatures.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_clone_state_sharing.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_clones_v3.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_dandelion_adapter.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_density.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_ebv_contig_matching.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_export.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_integrate.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_io.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_maptune.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_migration.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_parallel_and_robustness.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_phylo.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_profile_reproducibility.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_programs.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_reclustering_presets.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_release_metadata.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_sequence_v2.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_specificity.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_threadfin.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/tests/test_v4_core.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/_utils.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/bcrgraph.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/clones.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/core.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/dandelion.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/density.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/dynamics.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/export.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/expression.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/heritability.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/integrate.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/io.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/maptune.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/metrics.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/migration.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/phylo.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/plotting.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/pp.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/profiles.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/programs.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/reclustering.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/sequence.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/simulate.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/specificity.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin/tl.py +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin.egg-info/SOURCES.txt +0 -0
- {threadfin-4.5.1 → threadfin-4.5.3}/threadfin.egg-info/dependency_links.txt +0 -0
- {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.
|
|
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
|
|
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
|
|
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
|
|
113
|
-
clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to
|
|
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") #
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
59
|
-
clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to
|
|
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") #
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
-
|
|
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
|
|
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.
|
|
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,
|
|
14
|
-
|
|
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
|
|
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 += ["", "
|
|
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"
|
|
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 ``
|
|
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,
|
|
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
|
-
|
|
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
|
|
27
|
-
|
|
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
|
|
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}):
|
|
708
|
-
"clones differ, but
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
113
|
-
clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to
|
|
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") #
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|