threadfin 4.5.0__tar.gz → 4.5.2__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.0/threadfin.egg-info → threadfin-4.5.2}/PKG-INFO +112 -70
- {threadfin-4.5.0 → threadfin-4.5.2}/README.md +110 -68
- {threadfin-4.5.0 → threadfin-4.5.2}/pyproject.toml +4 -3
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_dandelion_adapter.py +9 -0
- threadfin-4.5.2/tests/test_user_inputs.py +246 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/__init__.py +1 -1
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/api.py +38 -12
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/dandelion.py +17 -3
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/plotting.py +37 -16
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/profiles.py +5 -7
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/programmes.py +18 -18
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/stats.py +33 -8
- {threadfin-4.5.0 → threadfin-4.5.2/threadfin.egg-info}/PKG-INFO +112 -70
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin.egg-info/requires.txt +1 -1
- threadfin-4.5.0/tests/test_user_inputs.py +0 -119
- {threadfin-4.5.0 → threadfin-4.5.2}/LICENSE +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/setup.cfg +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_api_reference.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_bcrgraph_clones.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_bone_marrow_design.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_case_study_signatures.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_clone_state_sharing.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_clones_v3.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_density.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_ebv_contig_matching.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_export.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_integrate.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_io.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_maptune.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_migration.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_parallel_and_robustness.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_phylo.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_profile_reproducibility.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_programs.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_reclustering_presets.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_release_metadata.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_sequence_v2.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_specificity.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_threadfin.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_v4_core.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/_utils.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/bcrgraph.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/clones.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/core.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/density.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/dynamics.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/export.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/expression.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/heritability.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/integrate.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/io.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/maptune.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/metrics.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/migration.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/phylo.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/pp.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/programs.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/reclustering.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/sequence.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/simulate.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/specificity.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/tl.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin.egg-info/SOURCES.txt +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/threadfin.egg-info/dependency_links.txt +0 -0
- {threadfin-4.5.0 → threadfin-4.5.2}/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.2
|
|
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
|
|
@@ -37,7 +37,7 @@ Requires-Dist: pynndescent>=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
|
|
40
|
-
Requires-Dist: sc-dandelion
|
|
40
|
+
Requires-Dist: sc-dandelion<1,>=0.5.7; extra == "dandelion"
|
|
41
41
|
Requires-Dist: matplotlib<3.9,>=3.7; extra == "dandelion"
|
|
42
42
|
Provides-Extra: seq
|
|
43
43
|
Requires-Dist: parasail>=1.3; extra == "seq"
|
|
@@ -65,10 +65,108 @@ Dynamic: license-file
|
|
|
65
65
|
<p align="center">
|
|
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
|
-
<a href="
|
|
69
|
-
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
|
|
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="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
|
+
Threadfin takes paired single-cell RNA and receptor (BCR or TCR) sequencing and describes every clone by the
|
|
73
|
+
distribution of its cells' transcriptional states, so that clones, not cells, can be compared, mapped and tested.
|
|
74
|
+
|
|
75
|
+
## Get started
|
|
76
|
+
|
|
77
|
+
### 1. Install
|
|
78
|
+
|
|
79
|
+
```bash
|
|
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
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Scanpy, Leiden, UMAP and Harmony are installed with it. Dandelion's clone calls depend on Python's hash seed:
|
|
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
|
|
87
|
+
installs with `pip install "git+https://github.com/Reynold4k/Threadfin.git"`.
|
|
88
|
+
|
|
89
|
+
### 2. Run
|
|
90
|
+
|
|
91
|
+
You need, for the same cells: raw gene counts in an [AnnData](https://anndata.readthedocs.io) object, the
|
|
92
|
+
contig-level receptor table (Cell Ranger's `filtered_contig_annotations.csv` or an AIRR `.tsv`), and the donor
|
|
93
|
+
and sample of each cell.
|
|
94
|
+
|
|
95
|
+
```python
|
|
96
|
+
import scanpy as sc
|
|
97
|
+
import threadfin as tf
|
|
98
|
+
|
|
99
|
+
adata = sc.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
|
|
100
|
+
|
|
101
|
+
result = tf.run(
|
|
102
|
+
adata,
|
|
103
|
+
bcr="filtered_contig_annotations.csv", # Cell Ranger VDJ output or an AIRR .tsv
|
|
104
|
+
donor_key="donor", # the individual each cell came from
|
|
105
|
+
sample_key="sample", # the sample or library each cell came from (never a sort gate,
|
|
106
|
+
# tissue or time point you want to compare: those go in test=)
|
|
107
|
+
n_jobs=8, # CPU cores to use; the result is the same with any number
|
|
108
|
+
)
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`tf.run` calls clones within each donor (Dandelion, paired chains), builds an expression embedding without the
|
|
112
|
+
receptor genes, estimates one profile per clone with two or more cells, tests clonal coherence, lays out the
|
|
113
|
+
clone map and looks for clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to
|
|
114
|
+
15 minutes with 8 cores.
|
|
115
|
+
|
|
116
|
+
### 3. Read the results
|
|
117
|
+
|
|
118
|
+
```python
|
|
119
|
+
print(result.summary()) # plain-language report
|
|
120
|
+
result.plot("threadfin_overview.pdf") # clone map, coherence, stability, programme sizes or composition
|
|
121
|
+
print(result.methods()) # a Methods paragraph with the settings and versions used
|
|
122
|
+
result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, reliability, programme, map position
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
<p align="center">
|
|
126
|
+
<img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
|
|
127
|
+
</p>
|
|
128
|
+
|
|
129
|
+
| What you get | Where |
|
|
130
|
+
|---|---|
|
|
131
|
+
| Does clone identity shape cell state? Clonal coherence, with its permutation P value | `result.coherence`; first part of the summary |
|
|
132
|
+
| A map with one point per clone | `result.plot()`; `result.clones[["x", "y"]]` |
|
|
133
|
+
| Groups of clones that behave alike, with their stability | `result.programmes`; `adata.obs["clone_programme"]` |
|
|
134
|
+
| How much your own labels explain the differences between clones | `result.profile_tests` (with `test=[...]`) |
|
|
135
|
+
| A Methods paragraph for your paper, with references | `result.methods()` |
|
|
136
|
+
|
|
137
|
+
### Common variations
|
|
138
|
+
|
|
139
|
+
* **Your own labels** (antigen binding, isotype, sort gate): any `adata.obs` columns, e.g.
|
|
140
|
+
`tf.run(..., test=["antigen_binding", "isotype"])`.
|
|
141
|
+
* **Time points or tissues**, to ask whether clones keep their state: `tf.run(..., time_key="timepoint")`.
|
|
142
|
+
* **T cells**: pass the TCR contigs as `bcr`; clones are called on identical beta and alpha junctions.
|
|
143
|
+
* **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
|
|
144
|
+
* **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
|
|
145
|
+
* **Large data**: `n_jobs=-1` uses every CPU core and gives the same result; a million cells take about an hour
|
|
146
|
+
on 8 cores.
|
|
147
|
+
* **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
|
|
148
|
+
has clone ids and an embedding, so run it with
|
|
149
|
+
`tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
|
|
150
|
+
|
|
151
|
+
### Tutorials
|
|
152
|
+
|
|
153
|
+
| Tutorial | What it covers |
|
|
154
|
+
|---|---|
|
|
155
|
+
| [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 |
|
|
156
|
+
| [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 |
|
|
157
|
+
| [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 |
|
|
158
|
+
| [4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
|
|
159
|
+
| [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) |
|
|
160
|
+
|
|
161
|
+
4.5.2 lists labels that are fixed within each donor (age, sex) as not testable instead of reporting p = 1, and
|
|
162
|
+
reads raw counts from a layer (`counts_layer=`); 4.5.1 pins Dandelion below 1.0. New in 4.5.0: T cells, scirpy
|
|
163
|
+
input, `result.methods()` and gene-level summaries of the clone landscape
|
|
164
|
+
([changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md)).
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## What Threadfin does
|
|
169
|
+
|
|
72
170
|
**Threadfin** is a Python package for paired single-cell RNA and B-cell receptor (BCR) sequencing. It
|
|
73
171
|
uses the **clone** — the B cells that descend from one V(D)J rearrangement — as the unit of analysis.
|
|
74
172
|
Each clone is represented by the distribution of transcriptional states among its sampled cells,
|
|
@@ -89,9 +187,11 @@ state* need the clone as the unit of representation and of statistical inference
|
|
|
89
187
|
repertoires sampled *in vivo* make this difficult, and Threadfin addresses each:
|
|
90
188
|
|
|
91
189
|
* **Most clones are captured as one or a few cells.** Profiles are shrunk according to the number of cells
|
|
92
|
-
sampled, and
|
|
190
|
+
sampled, and every clone with two or more cells carries a reliability score: none is discarded for being
|
|
191
|
+
small.
|
|
93
192
|
* **Clone membership is confounded with donor, sample, tissue and sorting gate.** Each clone is described
|
|
94
|
-
relative to the cells sampled with it, and every test shuffles labels within the sampling
|
|
193
|
+
relative to the cells sampled with it, and every permutation test shuffles labels within the sampling
|
|
194
|
+
design.
|
|
95
195
|
* **Treating cells as independent inflates significance.** Tests use clones, not cells, as replicates.
|
|
96
196
|
|
|
97
197
|
## What Threadfin answers
|
|
@@ -127,62 +227,6 @@ manuscript — status, datasets, every analysis and a benchmark against related
|
|
|
127
227
|
the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
|
|
128
228
|
clone profiles but were each sequenced in their own library.
|
|
129
229
|
|
|
130
|
-
## Installation
|
|
131
|
-
|
|
132
|
-
```bash
|
|
133
|
-
pip install "git+https://github.com/Reynold4k/Threadfin.git"
|
|
134
|
-
# with Dandelion, to define clones from BCR contigs:
|
|
135
|
-
pip install "threadfin[dandelion] @ git+https://github.com/Reynold4k/Threadfin.git"
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
Threadfin requires Python ≥ 3.10 and is tested on 3.10 to 3.14, down to the oldest dependency versions it
|
|
139
|
-
allows ([compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md)); Scanpy, Leiden, UMAP and Harmony are installed with it, and no
|
|
140
|
-
GPU or R is needed. Clones can be defined from BCR contigs with Dandelion (the `[dandelion]` extra also pins
|
|
141
|
-
`matplotlib<3.9`, which Dandelion 0.5.7 needs but does not declare), or you can provide your own clone ids
|
|
142
|
-
in `adata.obs["clone_id"]`. Dandelion's clone calls depend on Python's string-hash seed; start Python with
|
|
143
|
-
`PYTHONHASHSEED=0` if clone ids must be identical run after run.
|
|
144
|
-
|
|
145
|
-
## Quick start
|
|
146
|
-
|
|
147
|
-
```python
|
|
148
|
-
import scanpy as sc
|
|
149
|
-
import threadfin as tf
|
|
150
|
-
|
|
151
|
-
adata = sc.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
|
|
152
|
-
|
|
153
|
-
result = tf.run(
|
|
154
|
-
adata,
|
|
155
|
-
bcr="filtered_contig_annotations.csv", # Cell Ranger VDJ output or an AIRR .tsv
|
|
156
|
-
donor_key="donor", # the individual each cell came from
|
|
157
|
-
sample_key="sample", # the sample or library each cell came from
|
|
158
|
-
)
|
|
159
|
-
print(result.summary()) # plain-language report
|
|
160
|
-
result.plot("threadfin_overview.pdf") # clone map, coherence, stability, composition
|
|
161
|
-
print(result.methods()) # a Methods paragraph with the settings used
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
`tf.run` defines clones within each donor, builds an expression embedding without immunoglobulin genes,
|
|
165
|
-
estimates one profile per clone, tests clonal coherence, lays out the clone embedding, finds clonal
|
|
166
|
-
programmes and reports their stability. Add `test=[...]` to test your own labels and `time_key=` to ask
|
|
167
|
-
whether clones keep their state, and `n_jobs=-1` to use every CPU core (the results do not change). No data
|
|
168
|
-
at hand? `tf.sim.simulate_repertoire()` makes a repertoire with a known answer
|
|
169
|
-
([Tutorial 1](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md)).
|
|
170
|
-
T cells work the same way, with TCR contigs as `bcr`, and receptor data loaded with scirpy can be passed as
|
|
171
|
-
they are ([Tutorial 2, section 6](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md#6-how-clones-are-called)).
|
|
172
|
-
|
|
173
|
-
<p align="center">
|
|
174
|
-
<img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
|
|
175
|
-
</p>
|
|
176
|
-
|
|
177
|
-
## A complete, tested tutorial on public data
|
|
178
|
-
|
|
179
|
-
[`docs/tutorials/05_end_to_end_tutorial.ipynb`](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) takes you from an
|
|
180
|
-
empty folder to the main result of the manuscript's Figure 4: it creates the environment
|
|
181
|
-
([`environment.yml`](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/environment.yml)), downloads a published dataset from GEO (GSE287123,
|
|
182
|
-
about 600 MB), assigns cells to mice from hashtags, defines clones, builds the embedding, runs Threadfin and
|
|
183
|
-
explains every output, including how to tell biology from a sequencing-library effect. It was executed end
|
|
184
|
-
to end in a fresh environment before release and takes about 6 minutes on 8 CPU cores (about 8 GB of memory).
|
|
185
|
-
|
|
186
230
|
## A clone embedding that holds together
|
|
187
231
|
|
|
188
232
|
UMAP draws continuous populations of clones as one picture only for suitable settings, and the suitable
|
|
@@ -206,7 +250,8 @@ tf.tl.map_quality(features, xy) # score any clone map (p
|
|
|
206
250
|
<img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/threadfin_workflow.png" width="760" alt="Threadfin workflow">
|
|
207
251
|
</p>
|
|
208
252
|
|
|
209
|
-
1. **Clones** are defined from paired heavy- and light-chain sequences
|
|
253
|
+
1. **Clones** are defined from paired heavy- and light-chain sequences (for T cells, beta and alpha chains)
|
|
254
|
+
within each donor (Dandelion).
|
|
210
255
|
2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
|
|
211
256
|
a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
|
|
212
257
|
between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
|
|
@@ -226,18 +271,15 @@ The full description, with references, is in [Methods](https://github.com/Reynol
|
|
|
226
271
|
|
|
227
272
|
| | |
|
|
228
273
|
|---|---|
|
|
229
|
-
| [Tutorial 1 — Getting started](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md) | the whole analysis on simulated data, with its output |
|
|
230
|
-
| [Tutorial 2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results, with several samples and donors |
|
|
231
|
-
| [Tutorial 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 |
|
|
232
|
-
| [Tutorial 4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
|
|
233
|
-
| [Tutorial 5 — From GEO to results (notebook)](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) | a published dataset end to end: download, demultiplexing, clones, embedding, Threadfin, interpretation |
|
|
234
274
|
| [Methods](https://github.com/Reynold4k/Threadfin/blob/main/docs/METHODS.md) | the statistical model behind each step |
|
|
235
275
|
| [Function reference](https://github.com/Reynold4k/Threadfin/blob/main/docs/API.md) | every public function and its arguments, generated from the code |
|
|
276
|
+
| [Compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md) | Python and dependency versions, operating systems and datasets tested |
|
|
277
|
+
| [Changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md) | what changed in each version |
|
|
236
278
|
| [The manuscript](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md) | publication status, datasets, every analysis, open work |
|
|
237
279
|
| [Case studies](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/case_studies/README.md) | scripts and results for the public datasets |
|
|
238
280
|
| [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
|
|
239
281
|
| [Benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md) | Threadfin against Clonotrace, clone2vec, Benisse, CoNGA and scirpy |
|
|
240
|
-
| [
|
|
282
|
+
| [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 |
|
|
241
283
|
|
|
242
284
|
## Citation
|
|
243
285
|
|
|
@@ -256,7 +298,7 @@ error rate when samples differ, where per-clone graph scores and cell-level test
|
|
|
256
298
|
measured clone annotations Threadfin is comparable to clone2vec and to a simple mean of the cells'
|
|
257
299
|
coordinates, and better than Clonotrace at its default and than Benisse; in simulation, clone2vec groups clones by their
|
|
258
300
|
planted programme and tells mixed from in-between clones more accurately. Threadfin needs a fraction of the
|
|
259
|
-
others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace
|
|
301
|
+
others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 290 to 2,400
|
|
260
302
|
times) and finished every run without help; a million cells take about an hour on 8 cores
|
|
261
303
|
([scalability](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/scalability/README.md)).
|
|
262
304
|
The benchmark reports every result, including those where Threadfin is not the best.
|
|
@@ -11,10 +11,108 @@
|
|
|
11
11
|
<p align="center">
|
|
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
|
-
<a href="
|
|
15
|
-
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
|
|
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="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
|
+
Threadfin takes paired single-cell RNA and receptor (BCR or TCR) sequencing and describes every clone by the
|
|
19
|
+
distribution of its cells' transcriptional states, so that clones, not cells, can be compared, mapped and tested.
|
|
20
|
+
|
|
21
|
+
## Get started
|
|
22
|
+
|
|
23
|
+
### 1. Install
|
|
24
|
+
|
|
25
|
+
```bash
|
|
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
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Scanpy, Leiden, UMAP and Harmony are installed with it. Dandelion's clone calls depend on Python's hash seed:
|
|
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
|
|
33
|
+
installs with `pip install "git+https://github.com/Reynold4k/Threadfin.git"`.
|
|
34
|
+
|
|
35
|
+
### 2. Run
|
|
36
|
+
|
|
37
|
+
You need, for the same cells: raw gene counts in an [AnnData](https://anndata.readthedocs.io) object, the
|
|
38
|
+
contig-level receptor table (Cell Ranger's `filtered_contig_annotations.csv` or an AIRR `.tsv`), and the donor
|
|
39
|
+
and sample of each cell.
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
import scanpy as sc
|
|
43
|
+
import threadfin as tf
|
|
44
|
+
|
|
45
|
+
adata = sc.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
|
|
46
|
+
|
|
47
|
+
result = tf.run(
|
|
48
|
+
adata,
|
|
49
|
+
bcr="filtered_contig_annotations.csv", # Cell Ranger VDJ output or an AIRR .tsv
|
|
50
|
+
donor_key="donor", # the individual each cell came from
|
|
51
|
+
sample_key="sample", # the sample or library each cell came from (never a sort gate,
|
|
52
|
+
# tissue or time point you want to compare: those go in test=)
|
|
53
|
+
n_jobs=8, # CPU cores to use; the result is the same with any number
|
|
54
|
+
)
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`tf.run` calls clones within each donor (Dandelion, paired chains), builds an expression embedding without the
|
|
58
|
+
receptor genes, estimates one profile per clone with two or more cells, tests clonal coherence, lays out the
|
|
59
|
+
clone map and looks for clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to
|
|
60
|
+
15 minutes with 8 cores.
|
|
61
|
+
|
|
62
|
+
### 3. Read the results
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
print(result.summary()) # plain-language report
|
|
66
|
+
result.plot("threadfin_overview.pdf") # clone map, coherence, stability, programme sizes or composition
|
|
67
|
+
print(result.methods()) # a Methods paragraph with the settings and versions used
|
|
68
|
+
result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, reliability, programme, map position
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
<p align="center">
|
|
72
|
+
<img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
|
|
73
|
+
</p>
|
|
74
|
+
|
|
75
|
+
| What you get | Where |
|
|
76
|
+
|---|---|
|
|
77
|
+
| Does clone identity shape cell state? Clonal coherence, with its permutation P value | `result.coherence`; first part of the summary |
|
|
78
|
+
| A map with one point per clone | `result.plot()`; `result.clones[["x", "y"]]` |
|
|
79
|
+
| Groups of clones that behave alike, with their stability | `result.programmes`; `adata.obs["clone_programme"]` |
|
|
80
|
+
| How much your own labels explain the differences between clones | `result.profile_tests` (with `test=[...]`) |
|
|
81
|
+
| A Methods paragraph for your paper, with references | `result.methods()` |
|
|
82
|
+
|
|
83
|
+
### Common variations
|
|
84
|
+
|
|
85
|
+
* **Your own labels** (antigen binding, isotype, sort gate): any `adata.obs` columns, e.g.
|
|
86
|
+
`tf.run(..., test=["antigen_binding", "isotype"])`.
|
|
87
|
+
* **Time points or tissues**, to ask whether clones keep their state: `tf.run(..., time_key="timepoint")`.
|
|
88
|
+
* **T cells**: pass the TCR contigs as `bcr`; clones are called on identical beta and alpha junctions.
|
|
89
|
+
* **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
|
|
90
|
+
* **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
|
|
91
|
+
* **Large data**: `n_jobs=-1` uses every CPU core and gives the same result; a million cells take about an hour
|
|
92
|
+
on 8 cores.
|
|
93
|
+
* **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
|
|
94
|
+
has clone ids and an embedding, so run it with
|
|
95
|
+
`tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
|
|
96
|
+
|
|
97
|
+
### Tutorials
|
|
98
|
+
|
|
99
|
+
| Tutorial | What it covers |
|
|
100
|
+
|---|---|
|
|
101
|
+
| [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 |
|
|
102
|
+
| [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 |
|
|
103
|
+
| [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 |
|
|
104
|
+
| [4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
|
|
105
|
+
| [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) |
|
|
106
|
+
|
|
107
|
+
4.5.2 lists labels that are fixed within each donor (age, sex) as not testable instead of reporting p = 1, and
|
|
108
|
+
reads raw counts from a layer (`counts_layer=`); 4.5.1 pins Dandelion below 1.0. New in 4.5.0: T cells, scirpy
|
|
109
|
+
input, `result.methods()` and gene-level summaries of the clone landscape
|
|
110
|
+
([changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md)).
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## What Threadfin does
|
|
115
|
+
|
|
18
116
|
**Threadfin** is a Python package for paired single-cell RNA and B-cell receptor (BCR) sequencing. It
|
|
19
117
|
uses the **clone** — the B cells that descend from one V(D)J rearrangement — as the unit of analysis.
|
|
20
118
|
Each clone is represented by the distribution of transcriptional states among its sampled cells,
|
|
@@ -35,9 +133,11 @@ state* need the clone as the unit of representation and of statistical inference
|
|
|
35
133
|
repertoires sampled *in vivo* make this difficult, and Threadfin addresses each:
|
|
36
134
|
|
|
37
135
|
* **Most clones are captured as one or a few cells.** Profiles are shrunk according to the number of cells
|
|
38
|
-
sampled, and
|
|
136
|
+
sampled, and every clone with two or more cells carries a reliability score: none is discarded for being
|
|
137
|
+
small.
|
|
39
138
|
* **Clone membership is confounded with donor, sample, tissue and sorting gate.** Each clone is described
|
|
40
|
-
relative to the cells sampled with it, and every test shuffles labels within the sampling
|
|
139
|
+
relative to the cells sampled with it, and every permutation test shuffles labels within the sampling
|
|
140
|
+
design.
|
|
41
141
|
* **Treating cells as independent inflates significance.** Tests use clones, not cells, as replicates.
|
|
42
142
|
|
|
43
143
|
## What Threadfin answers
|
|
@@ -73,62 +173,6 @@ manuscript — status, datasets, every analysis and a benchmark against related
|
|
|
73
173
|
the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
|
|
74
174
|
clone profiles but were each sequenced in their own library.
|
|
75
175
|
|
|
76
|
-
## Installation
|
|
77
|
-
|
|
78
|
-
```bash
|
|
79
|
-
pip install "git+https://github.com/Reynold4k/Threadfin.git"
|
|
80
|
-
# with Dandelion, to define clones from BCR contigs:
|
|
81
|
-
pip install "threadfin[dandelion] @ git+https://github.com/Reynold4k/Threadfin.git"
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
Threadfin requires Python ≥ 3.10 and is tested on 3.10 to 3.14, down to the oldest dependency versions it
|
|
85
|
-
allows ([compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md)); Scanpy, Leiden, UMAP and Harmony are installed with it, and no
|
|
86
|
-
GPU or R is needed. Clones can be defined from BCR contigs with Dandelion (the `[dandelion]` extra also pins
|
|
87
|
-
`matplotlib<3.9`, which Dandelion 0.5.7 needs but does not declare), or you can provide your own clone ids
|
|
88
|
-
in `adata.obs["clone_id"]`. Dandelion's clone calls depend on Python's string-hash seed; start Python with
|
|
89
|
-
`PYTHONHASHSEED=0` if clone ids must be identical run after run.
|
|
90
|
-
|
|
91
|
-
## Quick start
|
|
92
|
-
|
|
93
|
-
```python
|
|
94
|
-
import scanpy as sc
|
|
95
|
-
import threadfin as tf
|
|
96
|
-
|
|
97
|
-
adata = sc.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
|
|
98
|
-
|
|
99
|
-
result = tf.run(
|
|
100
|
-
adata,
|
|
101
|
-
bcr="filtered_contig_annotations.csv", # Cell Ranger VDJ output or an AIRR .tsv
|
|
102
|
-
donor_key="donor", # the individual each cell came from
|
|
103
|
-
sample_key="sample", # the sample or library each cell came from
|
|
104
|
-
)
|
|
105
|
-
print(result.summary()) # plain-language report
|
|
106
|
-
result.plot("threadfin_overview.pdf") # clone map, coherence, stability, composition
|
|
107
|
-
print(result.methods()) # a Methods paragraph with the settings used
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
`tf.run` defines clones within each donor, builds an expression embedding without immunoglobulin genes,
|
|
111
|
-
estimates one profile per clone, tests clonal coherence, lays out the clone embedding, finds clonal
|
|
112
|
-
programmes and reports their stability. Add `test=[...]` to test your own labels and `time_key=` to ask
|
|
113
|
-
whether clones keep their state, and `n_jobs=-1` to use every CPU core (the results do not change). No data
|
|
114
|
-
at hand? `tf.sim.simulate_repertoire()` makes a repertoire with a known answer
|
|
115
|
-
([Tutorial 1](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md)).
|
|
116
|
-
T cells work the same way, with TCR contigs as `bcr`, and receptor data loaded with scirpy can be passed as
|
|
117
|
-
they are ([Tutorial 2, section 6](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md#6-how-clones-are-called)).
|
|
118
|
-
|
|
119
|
-
<p align="center">
|
|
120
|
-
<img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
|
|
121
|
-
</p>
|
|
122
|
-
|
|
123
|
-
## A complete, tested tutorial on public data
|
|
124
|
-
|
|
125
|
-
[`docs/tutorials/05_end_to_end_tutorial.ipynb`](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) takes you from an
|
|
126
|
-
empty folder to the main result of the manuscript's Figure 4: it creates the environment
|
|
127
|
-
([`environment.yml`](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/environment.yml)), downloads a published dataset from GEO (GSE287123,
|
|
128
|
-
about 600 MB), assigns cells to mice from hashtags, defines clones, builds the embedding, runs Threadfin and
|
|
129
|
-
explains every output, including how to tell biology from a sequencing-library effect. It was executed end
|
|
130
|
-
to end in a fresh environment before release and takes about 6 minutes on 8 CPU cores (about 8 GB of memory).
|
|
131
|
-
|
|
132
176
|
## A clone embedding that holds together
|
|
133
177
|
|
|
134
178
|
UMAP draws continuous populations of clones as one picture only for suitable settings, and the suitable
|
|
@@ -152,7 +196,8 @@ tf.tl.map_quality(features, xy) # score any clone map (p
|
|
|
152
196
|
<img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/threadfin_workflow.png" width="760" alt="Threadfin workflow">
|
|
153
197
|
</p>
|
|
154
198
|
|
|
155
|
-
1. **Clones** are defined from paired heavy- and light-chain sequences
|
|
199
|
+
1. **Clones** are defined from paired heavy- and light-chain sequences (for T cells, beta and alpha chains)
|
|
200
|
+
within each donor (Dandelion).
|
|
156
201
|
2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
|
|
157
202
|
a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
|
|
158
203
|
between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
|
|
@@ -172,18 +217,15 @@ The full description, with references, is in [Methods](https://github.com/Reynol
|
|
|
172
217
|
|
|
173
218
|
| | |
|
|
174
219
|
|---|---|
|
|
175
|
-
| [Tutorial 1 — Getting started](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md) | the whole analysis on simulated data, with its output |
|
|
176
|
-
| [Tutorial 2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results, with several samples and donors |
|
|
177
|
-
| [Tutorial 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 |
|
|
178
|
-
| [Tutorial 4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
|
|
179
|
-
| [Tutorial 5 — From GEO to results (notebook)](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) | a published dataset end to end: download, demultiplexing, clones, embedding, Threadfin, interpretation |
|
|
180
220
|
| [Methods](https://github.com/Reynold4k/Threadfin/blob/main/docs/METHODS.md) | the statistical model behind each step |
|
|
181
221
|
| [Function reference](https://github.com/Reynold4k/Threadfin/blob/main/docs/API.md) | every public function and its arguments, generated from the code |
|
|
222
|
+
| [Compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md) | Python and dependency versions, operating systems and datasets tested |
|
|
223
|
+
| [Changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md) | what changed in each version |
|
|
182
224
|
| [The manuscript](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md) | publication status, datasets, every analysis, open work |
|
|
183
225
|
| [Case studies](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/case_studies/README.md) | scripts and results for the public datasets |
|
|
184
226
|
| [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
|
|
185
227
|
| [Benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md) | Threadfin against Clonotrace, clone2vec, Benisse, CoNGA and scirpy |
|
|
186
|
-
| [
|
|
228
|
+
| [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 |
|
|
187
229
|
|
|
188
230
|
## Citation
|
|
189
231
|
|
|
@@ -202,7 +244,7 @@ error rate when samples differ, where per-clone graph scores and cell-level test
|
|
|
202
244
|
measured clone annotations Threadfin is comparable to clone2vec and to a simple mean of the cells'
|
|
203
245
|
coordinates, and better than Clonotrace at its default and than Benisse; in simulation, clone2vec groups clones by their
|
|
204
246
|
planted programme and tells mixed from in-between clones more accurately. Threadfin needs a fraction of the
|
|
205
|
-
others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace
|
|
247
|
+
others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 290 to 2,400
|
|
206
248
|
times) and finished every run without help; a million cells take about an hour on 8 cores
|
|
207
249
|
([scalability](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/scalability/README.md)).
|
|
208
250
|
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.2"
|
|
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"
|
|
@@ -44,8 +44,9 @@ dependencies = [
|
|
|
44
44
|
]
|
|
45
45
|
|
|
46
46
|
[project.optional-dependencies]
|
|
47
|
-
# clone definition with Dandelion; sc-dandelion 0.5.7 uses matplotlib.cm.get_cmap, removed in matplotlib 3.9
|
|
48
|
-
|
|
47
|
+
# clone definition with Dandelion; sc-dandelion 0.5.7 uses matplotlib.cm.get_cmap, removed in matplotlib 3.9.
|
|
48
|
+
# sc-dandelion 1.0 (2026-10-25) calls clones differently and is not yet validated, hence < 1.
|
|
49
|
+
dandelion = ["sc-dandelion>=0.5.7,<1", "matplotlib>=3.7,<3.9"]
|
|
49
50
|
seq = ["parasail>=1.3"] # faster CDR3 alignment for the legacy v3 functions
|
|
50
51
|
data = ["mudata>=0.3", "awkward>=2"] # reading scirpy/MuData example data
|
|
51
52
|
test = ["pytest>=7", "pytest-cov>=4"]
|
|
@@ -279,3 +279,12 @@ def test_receptor_data_can_come_from_a_scirpy_object():
|
|
|
279
279
|
t = read_contigs(adata)
|
|
280
280
|
assert len(t) == 5 and set(t["cell_id"]) == {"cell0", "cell1", "cell2"}
|
|
281
281
|
assert {"v_call", "j_call", "junction", "locus"} <= set(t.columns)
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
def test_dandelion_1x_is_flagged(monkeypatch):
|
|
285
|
+
"""sc-dandelion 1.0 calls clones differently from the validated 0.5.x; using it must not be silent."""
|
|
286
|
+
pytest.importorskip("dandelion")
|
|
287
|
+
import threadfin.dandelion as tfd
|
|
288
|
+
monkeypatch.setattr(tfd, "_dandelion_version", lambda ddl: "1.0.0")
|
|
289
|
+
with pytest.warns(UserWarning, match="validated with sc-dandelion 0.5.x"):
|
|
290
|
+
tfd._require_dandelion()
|