threadfin 4.5.0__tar.gz → 4.5.1__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.1}/PKG-INFO +103 -66
- {threadfin-4.5.0 → threadfin-4.5.1}/README.md +101 -64
- {threadfin-4.5.0 → threadfin-4.5.1}/pyproject.toml +4 -3
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_dandelion_adapter.py +9 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_user_inputs.py +82 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/__init__.py +1 -1
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/api.py +12 -4
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/dandelion.py +17 -3
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/plotting.py +37 -16
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/profiles.py +5 -7
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/programmes.py +11 -13
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/stats.py +15 -8
- {threadfin-4.5.0 → threadfin-4.5.1/threadfin.egg-info}/PKG-INFO +103 -66
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin.egg-info/requires.txt +1 -1
- {threadfin-4.5.0 → threadfin-4.5.1}/LICENSE +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/setup.cfg +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_api_reference.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_bcrgraph_clones.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_bone_marrow_design.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_case_study_signatures.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_clone_state_sharing.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_clones_v3.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_density.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_ebv_contig_matching.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_export.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_integrate.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_io.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_maptune.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_migration.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_parallel_and_robustness.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_phylo.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_profile_reproducibility.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_programs.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_reclustering_presets.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_release_metadata.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_sequence_v2.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_specificity.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_threadfin.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_v4_core.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/_utils.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/bcrgraph.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/clones.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/core.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/density.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/dynamics.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/export.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/expression.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/heritability.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/integrate.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/io.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/maptune.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/metrics.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/migration.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/phylo.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/pp.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/programs.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/reclustering.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/sequence.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/simulate.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/specificity.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/tl.py +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin.egg-info/SOURCES.txt +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/threadfin.egg-info/dependency_links.txt +0 -0
- {threadfin-4.5.0 → threadfin-4.5.1}/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.1
|
|
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,105 @@ 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="
|
|
68
|
+
<a href="https://pypi.org/project/threadfin/"><img src="https://img.shields.io/pypi/v/threadfin.svg" alt="PyPI version"></a>
|
|
69
69
|
<a href="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, 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.
|
|
114
|
+
|
|
115
|
+
### 3. Read the results
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
print(result.summary()) # plain-language report
|
|
119
|
+
result.plot("threadfin_overview.pdf") # clone map, coherence, stability, composition
|
|
120
|
+
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
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
<p align="center">
|
|
125
|
+
<img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
|
|
126
|
+
</p>
|
|
127
|
+
|
|
128
|
+
| What you get | Where |
|
|
129
|
+
|---|---|
|
|
130
|
+
| Does clone identity shape cell state? Clonal coherence, with its permutation P value | `result.coherence`; first part of the summary |
|
|
131
|
+
| A map with one point per clone | `result.plot()`; `result.clones[["x", "y"]]` |
|
|
132
|
+
| Groups of clones that behave alike, with their stability | `result.programmes`; `adata.obs["clone_programme"]` |
|
|
133
|
+
| How much your own labels explain the differences between clones | `result.profile_tests` (with `test=[...]`) |
|
|
134
|
+
| A Methods paragraph for your paper, with references | `result.methods()` |
|
|
135
|
+
|
|
136
|
+
### Common variations
|
|
137
|
+
|
|
138
|
+
* **Your own labels** (antigen binding, isotype, sort gate): any `adata.obs` columns, e.g.
|
|
139
|
+
`tf.run(..., test=["antigen_binding", "isotype"])`.
|
|
140
|
+
* **Time points or tissues**, to ask whether clones keep their state: `tf.run(..., time_key="timepoint")`.
|
|
141
|
+
* **T cells**: pass the TCR contigs as `bcr`; clones are called on identical beta and alpha junctions.
|
|
142
|
+
* **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
|
|
143
|
+
* **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
|
|
144
|
+
* **Large data**: `n_jobs=-1` uses every CPU core and gives the same result; a million cells take about an hour
|
|
145
|
+
on 8 cores.
|
|
146
|
+
* **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
|
|
147
|
+
has clone ids and an embedding, so run it with
|
|
148
|
+
`tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
|
|
149
|
+
|
|
150
|
+
### Tutorials
|
|
151
|
+
|
|
152
|
+
| Tutorial | What it covers |
|
|
153
|
+
|---|---|
|
|
154
|
+
| [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 |
|
|
155
|
+
| [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 |
|
|
156
|
+
| [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 |
|
|
157
|
+
| [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
|
+
| [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
|
+
|
|
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
|
|
161
|
+
([changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md)).
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## What Threadfin does
|
|
166
|
+
|
|
72
167
|
**Threadfin** is a Python package for paired single-cell RNA and B-cell receptor (BCR) sequencing. It
|
|
73
168
|
uses the **clone** — the B cells that descend from one V(D)J rearrangement — as the unit of analysis.
|
|
74
169
|
Each clone is represented by the distribution of transcriptional states among its sampled cells,
|
|
@@ -127,62 +222,6 @@ manuscript — status, datasets, every analysis and a benchmark against related
|
|
|
127
222
|
the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
|
|
128
223
|
clone profiles but were each sequenced in their own library.
|
|
129
224
|
|
|
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
225
|
## A clone embedding that holds together
|
|
187
226
|
|
|
188
227
|
UMAP draws continuous populations of clones as one picture only for suitable settings, and the suitable
|
|
@@ -206,7 +245,8 @@ tf.tl.map_quality(features, xy) # score any clone map (p
|
|
|
206
245
|
<img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/threadfin_workflow.png" width="760" alt="Threadfin workflow">
|
|
207
246
|
</p>
|
|
208
247
|
|
|
209
|
-
1. **Clones** are defined from paired heavy- and light-chain sequences
|
|
248
|
+
1. **Clones** are defined from paired heavy- and light-chain sequences (for T cells, beta and alpha chains)
|
|
249
|
+
within each donor (Dandelion).
|
|
210
250
|
2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
|
|
211
251
|
a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
|
|
212
252
|
between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
|
|
@@ -226,18 +266,15 @@ The full description, with references, is in [Methods](https://github.com/Reynol
|
|
|
226
266
|
|
|
227
267
|
| | |
|
|
228
268
|
|---|---|
|
|
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
269
|
| [Methods](https://github.com/Reynold4k/Threadfin/blob/main/docs/METHODS.md) | the statistical model behind each step |
|
|
235
270
|
| [Function reference](https://github.com/Reynold4k/Threadfin/blob/main/docs/API.md) | every public function and its arguments, generated from the code |
|
|
271
|
+
| [Compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md) | Python and dependency versions, operating systems and datasets tested |
|
|
272
|
+
| [Changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md) | what changed in each version |
|
|
236
273
|
| [The manuscript](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md) | publication status, datasets, every analysis, open work |
|
|
237
274
|
| [Case studies](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/case_studies/README.md) | scripts and results for the public datasets |
|
|
238
275
|
| [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
|
|
239
276
|
| [Benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md) | Threadfin against Clonotrace, clone2vec, Benisse, CoNGA and scirpy |
|
|
240
|
-
| [
|
|
277
|
+
| [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
278
|
|
|
242
279
|
## Citation
|
|
243
280
|
|
|
@@ -11,10 +11,105 @@
|
|
|
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="
|
|
14
|
+
<a href="https://pypi.org/project/threadfin/"><img src="https://img.shields.io/pypi/v/threadfin.svg" alt="PyPI version"></a>
|
|
15
15
|
<a href="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, 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.
|
|
60
|
+
|
|
61
|
+
### 3. Read the results
|
|
62
|
+
|
|
63
|
+
```python
|
|
64
|
+
print(result.summary()) # plain-language report
|
|
65
|
+
result.plot("threadfin_overview.pdf") # clone map, coherence, stability, composition
|
|
66
|
+
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
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
<p align="center">
|
|
71
|
+
<img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
|
|
72
|
+
</p>
|
|
73
|
+
|
|
74
|
+
| What you get | Where |
|
|
75
|
+
|---|---|
|
|
76
|
+
| Does clone identity shape cell state? Clonal coherence, with its permutation P value | `result.coherence`; first part of the summary |
|
|
77
|
+
| A map with one point per clone | `result.plot()`; `result.clones[["x", "y"]]` |
|
|
78
|
+
| Groups of clones that behave alike, with their stability | `result.programmes`; `adata.obs["clone_programme"]` |
|
|
79
|
+
| How much your own labels explain the differences between clones | `result.profile_tests` (with `test=[...]`) |
|
|
80
|
+
| A Methods paragraph for your paper, with references | `result.methods()` |
|
|
81
|
+
|
|
82
|
+
### Common variations
|
|
83
|
+
|
|
84
|
+
* **Your own labels** (antigen binding, isotype, sort gate): any `adata.obs` columns, e.g.
|
|
85
|
+
`tf.run(..., test=["antigen_binding", "isotype"])`.
|
|
86
|
+
* **Time points or tissues**, to ask whether clones keep their state: `tf.run(..., time_key="timepoint")`.
|
|
87
|
+
* **T cells**: pass the TCR contigs as `bcr`; clones are called on identical beta and alpha junctions.
|
|
88
|
+
* **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
|
|
89
|
+
* **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
|
|
90
|
+
* **Large data**: `n_jobs=-1` uses every CPU core and gives the same result; a million cells take about an hour
|
|
91
|
+
on 8 cores.
|
|
92
|
+
* **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
|
|
93
|
+
has clone ids and an embedding, so run it with
|
|
94
|
+
`tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
|
|
95
|
+
|
|
96
|
+
### Tutorials
|
|
97
|
+
|
|
98
|
+
| Tutorial | What it covers |
|
|
99
|
+
|---|---|
|
|
100
|
+
| [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 |
|
|
101
|
+
| [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 |
|
|
102
|
+
| [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 |
|
|
103
|
+
| [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
|
+
| [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
|
+
|
|
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
|
|
107
|
+
([changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md)).
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## What Threadfin does
|
|
112
|
+
|
|
18
113
|
**Threadfin** is a Python package for paired single-cell RNA and B-cell receptor (BCR) sequencing. It
|
|
19
114
|
uses the **clone** — the B cells that descend from one V(D)J rearrangement — as the unit of analysis.
|
|
20
115
|
Each clone is represented by the distribution of transcriptional states among its sampled cells,
|
|
@@ -73,62 +168,6 @@ manuscript — status, datasets, every analysis and a benchmark against related
|
|
|
73
168
|
the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
|
|
74
169
|
clone profiles but were each sequenced in their own library.
|
|
75
170
|
|
|
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
171
|
## A clone embedding that holds together
|
|
133
172
|
|
|
134
173
|
UMAP draws continuous populations of clones as one picture only for suitable settings, and the suitable
|
|
@@ -152,7 +191,8 @@ tf.tl.map_quality(features, xy) # score any clone map (p
|
|
|
152
191
|
<img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/threadfin_workflow.png" width="760" alt="Threadfin workflow">
|
|
153
192
|
</p>
|
|
154
193
|
|
|
155
|
-
1. **Clones** are defined from paired heavy- and light-chain sequences
|
|
194
|
+
1. **Clones** are defined from paired heavy- and light-chain sequences (for T cells, beta and alpha chains)
|
|
195
|
+
within each donor (Dandelion).
|
|
156
196
|
2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
|
|
157
197
|
a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
|
|
158
198
|
between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
|
|
@@ -172,18 +212,15 @@ The full description, with references, is in [Methods](https://github.com/Reynol
|
|
|
172
212
|
|
|
173
213
|
| | |
|
|
174
214
|
|---|---|
|
|
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
215
|
| [Methods](https://github.com/Reynold4k/Threadfin/blob/main/docs/METHODS.md) | the statistical model behind each step |
|
|
181
216
|
| [Function reference](https://github.com/Reynold4k/Threadfin/blob/main/docs/API.md) | every public function and its arguments, generated from the code |
|
|
217
|
+
| [Compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md) | Python and dependency versions, operating systems and datasets tested |
|
|
218
|
+
| [Changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md) | what changed in each version |
|
|
182
219
|
| [The manuscript](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md) | publication status, datasets, every analysis, open work |
|
|
183
220
|
| [Case studies](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/case_studies/README.md) | scripts and results for the public datasets |
|
|
184
221
|
| [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
|
|
185
222
|
| [Benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md) | Threadfin against Clonotrace, clone2vec, Benisse, CoNGA and scirpy |
|
|
186
|
-
| [
|
|
223
|
+
| [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
224
|
|
|
188
225
|
## Citation
|
|
189
226
|
|
|
@@ -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.1"
|
|
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()
|
|
@@ -117,3 +117,85 @@ def test_a_subset_without_copy_runs_and_keeps_its_results():
|
|
|
117
117
|
assert view.is_view
|
|
118
118
|
res = tf.run(view, basis="X_pca", donor_key="donor", sample_key="context", n_perm=10, n_boot=3, verbose=False)
|
|
119
119
|
assert not view.is_view and "threadfin" in view.uns and len(res.clones) > 0
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def _tcr_csv_for(adata, path):
|
|
123
|
+
"""A Cell Ranger TCR filtered_contig_annotations.csv for the simulated cells: one beta and one alpha chain
|
|
124
|
+
per cell, identical within a clone and distinct between clones."""
|
|
125
|
+
rng = np.random.default_rng(0)
|
|
126
|
+
aa = np.array(list("ACDEFGHIKLMNPQRSTVWY"))
|
|
127
|
+
junctions = {c: ("CASS" + "".join(rng.choice(aa, 7)) + "F", "CAV" + "".join(rng.choice(aa, 7)) + "F")
|
|
128
|
+
for c in adata.obs["clone_id"].astype(str).unique()}
|
|
129
|
+
rows = []
|
|
130
|
+
for cell, clone in adata.obs["clone_id"].astype(str).items():
|
|
131
|
+
beta, alpha = junctions[clone]
|
|
132
|
+
for chain, v, j, cdr3 in (("TRB", "TRBV7-9", "TRBJ2-7", beta), ("TRA", "TRAV1-2", "TRAJ33", alpha)):
|
|
133
|
+
rows.append({"barcode": cell, "is_cell": True, "high_confidence": True, "chain": chain, "v_gene": v,
|
|
134
|
+
"d_gene": "None", "j_gene": j, "c_gene": chain[:2] + "C", "productive": True,
|
|
135
|
+
"cdr3": cdr3, "cdr3_nt": "TGT" * len(cdr3), "reads": 500, "umis": 5})
|
|
136
|
+
pd.DataFrame(rows).to_csv(path, index=False)
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def test_t_cell_contigs_can_be_passed_as_a_file_path(tmp_path):
|
|
140
|
+
"""The README's T-cell route: a TCR filtered_contig_annotations.csv path used to crash after clone calling
|
|
141
|
+
('No productive BCR contigs left') because the per-cell summary read B-cell chains only."""
|
|
142
|
+
pytest.importorskip("dandelion")
|
|
143
|
+
adata = tf.sim.simulate_repertoire(random_state=0, n_clones=150)
|
|
144
|
+
true_clone = adata.obs["clone_id"].astype(str).copy()
|
|
145
|
+
_tcr_csv_for(adata, tmp_path / "tcr.csv")
|
|
146
|
+
del adata.obs["clone_id"]
|
|
147
|
+
res = tf.run(adata, bcr=str(tmp_path / "tcr.csv"), basis="X_pca", donor_key="donor", sample_key="context",
|
|
148
|
+
n_perm=10, n_boot=3, verbose=False)
|
|
149
|
+
called = adata.obs["clone_id"]
|
|
150
|
+
assert res.settings.get("receptor") == "TCR" and called.notna().all()
|
|
151
|
+
# the called clones are the simulated ones (within donors)
|
|
152
|
+
assert pd.crosstab(called, true_clone).gt(0).sum(axis=1).eq(1).all()
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def test_define_clones_accepts_cell_ranger_column_names():
|
|
156
|
+
"""Tutorial 2 passes the Cell Ranger contig table (barcode, v_gene, j_gene, cdr3_nt) directly."""
|
|
157
|
+
pytest.importorskip("dandelion")
|
|
158
|
+
adata = tf.sim.simulate_repertoire(random_state=0, n_clones=40)
|
|
159
|
+
import tempfile, os
|
|
160
|
+
with tempfile.TemporaryDirectory() as d:
|
|
161
|
+
_tcr_csv_for(adata, os.path.join(d, "tcr.csv"))
|
|
162
|
+
contigs = pd.read_csv(os.path.join(d, "tcr.csv"))
|
|
163
|
+
contigs["donor"] = contigs["barcode"].map(adata.obs["donor"].astype(str))
|
|
164
|
+
ids = tf.define_clones_dandelion(contigs, donor_key="donor", verbose=False)
|
|
165
|
+
assert ids.notna().all() and ids.index.isin(adata.obs_names).all()
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def test_fraction_of_a_level_that_never_occurs_warns():
|
|
169
|
+
"""fraction:IGHA on a column holding IGHA1/IGHA2 used to return 0 for every clone without a word."""
|
|
170
|
+
adata = tf.sim.simulate_repertoire(random_state=0, n_clones=60)
|
|
171
|
+
tf.tl.clone_profiles(adata, basis="X_pca", context_key="context", donor_key="donor", verbose=False)
|
|
172
|
+
adata.obs["iso"] = np.where(np.arange(adata.n_obs) % 2, "IGHA1", "IGHG1")
|
|
173
|
+
with pytest.warns(UserWarning, match="Levels starting with 'IGHA': IGHA1"):
|
|
174
|
+
out = tf.tl.clone_labels(adata, "iso", how="fraction:IGHA")
|
|
175
|
+
assert (out == 0).all()
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def test_overview_shows_the_coherence_of_the_result(monkeypatch):
|
|
179
|
+
"""Panel b used to show whatever clonal_coherence ran last, not result.coherence."""
|
|
180
|
+
import threadfin.plotting as plotting
|
|
181
|
+
adata = tf.sim.simulate_repertoire(random_state=0, n_clones=1000)
|
|
182
|
+
res = tf.run(adata, basis="X_pca", donor_key="donor", sample_key="context", n_perm=10, n_boot=3, verbose=False)
|
|
183
|
+
tf.tl.clonal_coherence(adata, strata_key="donor", n_perm=10, verbose=False) # a later, different test
|
|
184
|
+
seen = {}
|
|
185
|
+
original = plotting.coherence
|
|
186
|
+
|
|
187
|
+
def spy(adata, *, result=None, ax=None, save=None):
|
|
188
|
+
seen["icc"] = (result or adata.uns["threadfin"]["coherence"])["icc"]
|
|
189
|
+
return original(adata, result=result, ax=ax, save=save)
|
|
190
|
+
|
|
191
|
+
monkeypatch.setattr(plotting, "coherence", spy)
|
|
192
|
+
res.plot()
|
|
193
|
+
assert seen["icc"] == res.coherence["icc"]
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def test_overview_is_drawn_when_no_programmes_were_found():
|
|
197
|
+
"""A small dataset gets 'not enough reliably profiled clones' for programmes; result.plot() used to crash."""
|
|
198
|
+
adata = tf.sim.simulate_repertoire(random_state=0, n_clones=200)
|
|
199
|
+
res = tf.run(adata, basis="X_pca", donor_key="donor", sample_key="context", n_perm=10, n_boot=3, verbose=False)
|
|
200
|
+
assert res.programmes.empty
|
|
201
|
+
assert res.plot() is not None
|
|
@@ -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.1"
|
|
43
43
|
__all__ = [
|
|
44
44
|
"ThreadfinResult",
|
|
45
45
|
"DensityResult",
|
|
@@ -150,8 +150,14 @@ class ThreadfinResult:
|
|
|
150
150
|
vc = VarianceComponents(np.asarray(prof_vc["sigma2"]), np.asarray(prof_vc["tau2"]),
|
|
151
151
|
prof_vc["n0"], prof_vc["n_clones"], prof_vc["n_cells"],
|
|
152
152
|
np.zeros(len(prof_vc["tau2"])))
|
|
153
|
+
n_half = vc.min_cells_for(0.5)
|
|
153
154
|
lines.append(f" Profiles are shrunk towards the mean, so a clone reaches reliability 0.5 at "
|
|
154
|
-
f"{
|
|
155
|
+
f"{n_half} {'cell' if n_half == 1 else 'cells'}. No clone is filtered out on reliability.")
|
|
156
|
+
n_profiled = int(prof_vc["n_clones"])
|
|
157
|
+
if n_profiled < 10:
|
|
158
|
+
lines.append(f" Caution: only {n_profiled} clones have two or more cells. Estimates from so few clones "
|
|
159
|
+
"are unstable; Threadfin's power analyses need about 10 clones to detect a clonal ICC "
|
|
160
|
+
"of 0.1, and more for weaker effects.")
|
|
155
161
|
prog = self.programmes
|
|
156
162
|
lines += ["", "2. Which clones behave alike? (clonal programmes)"]
|
|
157
163
|
if prog.empty:
|
|
@@ -408,7 +414,7 @@ class ThreadfinResult:
|
|
|
408
414
|
"""Overview figure (clone map, coherence test, programme composition, stability)."""
|
|
409
415
|
from .plotting import overview
|
|
410
416
|
|
|
411
|
-
return overview(self.adata, state_key=self.settings.get("state_key"), save=save)
|
|
417
|
+
return overview(self.adata, state_key=self.settings.get("state_key"), coherence_result=self.coherence, save=save)
|
|
412
418
|
|
|
413
419
|
|
|
414
420
|
# --------------------------------------------------------------------------- the pipeline
|
|
@@ -553,7 +559,7 @@ def run(
|
|
|
553
559
|
raise ValueError(
|
|
554
560
|
"No barcode of the receptor data matches adata.obs_names. Check that both use the same barcode "
|
|
555
561
|
"format; for multi-sample data, harmonise the barcodes first (see "
|
|
556
|
-
"
|
|
562
|
+
"tutorial 2, section 4: prefix the cell_id column of the contig table)."
|
|
557
563
|
)
|
|
558
564
|
if donor_key is not None:
|
|
559
565
|
donor_of_cell = pd.Series(adata.obs[donor_key].astype(str).to_numpy(),
|
|
@@ -568,7 +574,9 @@ def run(
|
|
|
568
574
|
"Matched receptor contigs produced no clone calls. Each retained cell needs "
|
|
569
575
|
"heavy-chain (TCR: beta or delta) V and J calls plus a non-empty junction/CDR3 sequence."
|
|
570
576
|
)
|
|
571
|
-
if not isinstance(bcr, (str, Path))
|
|
577
|
+
if not isinstance(bcr, (str, Path)) or receptor != "BCR":
|
|
578
|
+
# a DataFrame or a scirpy object, or T-cell contigs (read_bcr summarises B-cell chains only):
|
|
579
|
+
# clone ids only
|
|
572
580
|
table = ids.rename(clone_key).to_frame()
|
|
573
581
|
table.index.name = "barcode"
|
|
574
582
|
else:
|