actinn-jax 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- actinn_jax-0.3.0/LICENSE +25 -0
- actinn_jax-0.3.0/MANIFEST.in +23 -0
- actinn_jax-0.3.0/PKG-INFO +453 -0
- actinn_jax-0.3.0/README.md +410 -0
- actinn_jax-0.3.0/actinn_jax/__init__.py +57 -0
- actinn_jax-0.3.0/actinn_jax/actinn_predict.py +597 -0
- actinn_jax-0.3.0/actinn_jax/actinn_utils.py +240 -0
- actinn_jax-0.3.0/actinn_jax/cli.py +139 -0
- actinn_jax-0.3.0/actinn_jax/embed.py +84 -0
- actinn_jax-0.3.0/actinn_jax/hierarchy.py +638 -0
- actinn_jax-0.3.0/actinn_jax/novelty.py +136 -0
- actinn_jax-0.3.0/actinn_jax/references/README.md +126 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/build_info.json +52 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/coarse.json +1 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/coarse.npz +0 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Embryonic cell.json +1 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Embryonic cell.npz +0 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Endothelial cell.json +1 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Endothelial cell.npz +0 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Epithelial cell.json +1 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Epithelial cell.npz +0 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Fibroblast.json +1 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Fibroblast.npz +0 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Glial cell.json +1 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Glial cell.npz +0 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Immune cell.json +1 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Immune cell.npz +0 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Muscle cell.json +1 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Muscle cell.npz +0 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Neuron.json +1 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Neuron.npz +0 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Perivascular cell.json +1 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Perivascular cell.npz +0 -0
- actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/manifest.json +1 -0
- actinn_jax-0.3.0/actinn_jax/registry.py +205 -0
- actinn_jax-0.3.0/actinn_jax.egg-info/PKG-INFO +453 -0
- actinn_jax-0.3.0/actinn_jax.egg-info/SOURCES.txt +49 -0
- actinn_jax-0.3.0/actinn_jax.egg-info/dependency_links.txt +1 -0
- actinn_jax-0.3.0/actinn_jax.egg-info/entry_points.txt +2 -0
- actinn_jax-0.3.0/actinn_jax.egg-info/not-zip-safe +1 -0
- actinn_jax-0.3.0/actinn_jax.egg-info/requires.txt +23 -0
- actinn_jax-0.3.0/actinn_jax.egg-info/top_level.txt +1 -0
- actinn_jax-0.3.0/examples/build_reference.py +44 -0
- actinn_jax-0.3.0/examples/detect_novel_celltypes.py +54 -0
- actinn_jax-0.3.0/examples/quickstart_annotate.py +39 -0
- actinn_jax-0.3.0/pyproject.toml +73 -0
- actinn_jax-0.3.0/setup.cfg +4 -0
- actinn_jax-0.3.0/tests/conftest.py +36 -0
- actinn_jax-0.3.0/tests/test_actinn.py +171 -0
- actinn_jax-0.3.0/tests/test_hierarchy.py +299 -0
- actinn_jax-0.3.0/tests/test_novelty.py +49 -0
actinn_jax-0.3.0/LICENSE
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ian Driver
|
|
4
|
+
|
|
5
|
+
This project is a reimplementation of ACTINN (Ma & Pellegrini, Bioinformatics
|
|
6
|
+
2020; https://github.com/mafeiyang/ACTINN), which is also released under the MIT
|
|
7
|
+
License.
|
|
8
|
+
|
|
9
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
10
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
11
|
+
in the Software without restriction, including without limitation the rights
|
|
12
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
13
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
14
|
+
furnished to do so, subject to the following conditions:
|
|
15
|
+
|
|
16
|
+
The above copyright notice and this permission notice shall be included in all
|
|
17
|
+
copies or substantial portions of the Software.
|
|
18
|
+
|
|
19
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
20
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
21
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
22
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
23
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
24
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
25
|
+
SOFTWARE.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Controls the SOURCE distribution. `include-package-data = false` in pyproject.toml only
|
|
2
|
+
# governs the wheel -- sdists are assembled by different rules, and without this file the
|
|
3
|
+
# sdist was 110 MB (all bundled references), over PyPI's 100 MB per-file limit even though
|
|
4
|
+
# the wheel was fine at 15 MB.
|
|
5
|
+
#
|
|
6
|
+
# The large references are downloaded from Zenodo at runtime (actinn_jax/registry.py); only
|
|
7
|
+
# the small default one is distributed.
|
|
8
|
+
|
|
9
|
+
prune actinn_jax/references
|
|
10
|
+
recursive-include actinn_jax/references/panhuman_distill_v1 *.npz *.json
|
|
11
|
+
include actinn_jax/references/README.md
|
|
12
|
+
|
|
13
|
+
include LICENSE
|
|
14
|
+
include README.md
|
|
15
|
+
recursive-include tests *.py
|
|
16
|
+
recursive-include examples *.py
|
|
17
|
+
|
|
18
|
+
# Never ship a local dev environment, build leftovers, or caches.
|
|
19
|
+
prune .venv
|
|
20
|
+
prune build
|
|
21
|
+
prune dist
|
|
22
|
+
prune .github
|
|
23
|
+
global-exclude *.py[cod] __pycache__/* .DS_Store
|
|
@@ -0,0 +1,453 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: actinn-jax
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Fast JAX reimplementation of ACTINN for single-cell cell-type reference mapping
|
|
5
|
+
Author-email: Ian Driver <driver.ian@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Keywords: single-cell,cell-type-annotation,ACTINN,jax,scanpy
|
|
8
|
+
Classifier: Development Status :: 4 - Beta
|
|
9
|
+
Classifier: Intended Audience :: Science/Research
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Natural Language :: English
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Operating System :: MacOS :: MacOS X
|
|
16
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
17
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
19
|
+
Requires-Python: >=3.10
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: numpy>=1.15
|
|
23
|
+
Requires-Dist: scipy>=1.7
|
|
24
|
+
Requires-Dist: anndata>=0.6.22
|
|
25
|
+
Requires-Dist: pandas>=1.3
|
|
26
|
+
Requires-Dist: h5py
|
|
27
|
+
Requires-Dist: scanpy>=1.8
|
|
28
|
+
Requires-Dist: jax>=0.4.0
|
|
29
|
+
Requires-Dist: jaxlib>=0.4.0
|
|
30
|
+
Requires-Dist: optax>=0.1.5
|
|
31
|
+
Provides-Extra: metal
|
|
32
|
+
Requires-Dist: jax-metal; extra == "metal"
|
|
33
|
+
Provides-Extra: test
|
|
34
|
+
Requires-Dist: pytest; extra == "test"
|
|
35
|
+
Provides-Extra: notebooks
|
|
36
|
+
Requires-Dist: jupyterlab; extra == "notebooks"
|
|
37
|
+
Requires-Dist: ipykernel; extra == "notebooks"
|
|
38
|
+
Requires-Dist: matplotlib; extra == "notebooks"
|
|
39
|
+
Requires-Dist: pronto; extra == "notebooks"
|
|
40
|
+
Requires-Dist: leidenalg; extra == "notebooks"
|
|
41
|
+
Requires-Dist: igraph; extra == "notebooks"
|
|
42
|
+
Dynamic: license-file
|
|
43
|
+
|
|
44
|
+
# actinn-jax
|
|
45
|
+
|
|
46
|
+
Fast, dependency-light cell-type **reference mapping** for single-cell data: train
|
|
47
|
+
on a labeled reference dataset, then annotate any query dataset.
|
|
48
|
+
|
|
49
|
+
## ⭐ Annotate single-cell data — fast, on CPU
|
|
50
|
+
|
|
51
|
+
Pre-trained organism-wide references ship with the package, so unknown data works out of
|
|
52
|
+
the box. From the command line, with no arguments to choose:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
actinn-jax annotate my_data.h5ad --min-prob 0.5 -o annotations.csv
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
That infers the organism from the query's gene ids and loads the matching reference.
|
|
59
|
+
`actinn-jax references` lists what is installed. From Python:
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
import scanpy as sc, actinn_jax as aj
|
|
63
|
+
|
|
64
|
+
for r in aj.list_references(): # what's available, and for what
|
|
65
|
+
print(r["name"], r["organism"], r["n_classes"])
|
|
66
|
+
|
|
67
|
+
adata = sc.read_h5ad("my_data.h5ad") # raw counts
|
|
68
|
+
model = aj.bundled_reference("panhuman_distill_v1") # pre-trained, CPU-only
|
|
69
|
+
adata = aj.annotate(adata, model, min_prob=0.5) # -> obs['celltype', _coarse, _probability]
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Annotating with a reference for the wrong organism raises rather than returning
|
|
73
|
+
meaningless labels.
|
|
74
|
+
|
|
75
|
+
### Where the references live
|
|
76
|
+
|
|
77
|
+
`panhuman_distill_v1` (16 MB, human) ships inside the wheel, so `pip install actinn-jax`
|
|
78
|
+
annotates human data offline with nothing to download. The census-scale references are
|
|
79
|
+
tens of MB each and are **fetched once on first use** from Zenodo
|
|
80
|
+
([10.5281/zenodo.21688151](https://doi.org/10.5281/zenodo.21688151)), then cached in
|
|
81
|
+
`~/.cache/actinn-jax/` — `bundled_reference("broad_mouse_v1")` works whether or not it has
|
|
82
|
+
been downloaded before (~40 s on a cold cache, instant after). Each archive is
|
|
83
|
+
checksum-verified before it is unpacked.
|
|
84
|
+
|
|
85
|
+
For a tutorial or a workshop on a slow connection, pull them ahead of time:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
actinn-jax fetch # everything
|
|
89
|
+
actinn-jax fetch broad_mouse_v1 # or just one
|
|
90
|
+
actinn-jax references # installed / cached / available
|
|
91
|
+
actinn-jax cache --clear # free the space again
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
In a notebook the same thing is one call, and it is safe to re-run:
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
from actinn_jax import registry
|
|
98
|
+
registry.fetch_reference("broad_mouse_v1") # no-op once cached
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Point `ACTINN_JAX_REFERENCE_URL` at a mirror to serve them from somewhere else, and
|
|
102
|
+
`ACTINN_JAX_CACHE` to relocate the cache (useful on a shared cluster filesystem).
|
|
103
|
+
|
|
104
|
+
Under the hood this is a **two-stage workflow**: a coarse→fine cell-type hierarchy is
|
|
105
|
+
discovered *once, offline*, and a small actinn-jax model trained on it annotates new data
|
|
106
|
+
in **milliseconds on a CPU — no GPU at inference**.
|
|
107
|
+
|
|
108
|
+
`min_prob` is an **abstain threshold**: cells whose confidence is below it are labeled
|
|
109
|
+
`"unknown"` instead of being force-mapped to the nearest reference type — so genuinely
|
|
110
|
+
novel cell types get flagged rather than mislabeled. Held-out calibration (10% of cell
|
|
111
|
+
types held out entirely as out-of-distribution):
|
|
112
|
+
|
|
113
|
+
| `min_prob` | accuracy (kept) | coverage | OOD flagged as unknown |
|
|
114
|
+
|-----------:|----------------:|---------:|-----------------------:|
|
|
115
|
+
| 0.0 (off) | 0.55 | 100% | 0% |
|
|
116
|
+
| 0.5 | 0.80 | 46% | 75% |
|
|
117
|
+
| 0.7 | 0.86 | 30% | 88% |
|
|
118
|
+
|
|
119
|
+
Breadth vs. precision is a deliberate trade: ~800-way annotation from a small per-type
|
|
120
|
+
sample is far harder than a narrow atlas (many near-duplicate subtypes, e.g. cortical
|
|
121
|
+
neuron layers), so raw accuracy is lower than a focused reference — the abstain threshold
|
|
122
|
+
recovers precision on the cells it keeps. For a narrower, higher-accuracy reference on
|
|
123
|
+
your own cell types, build one (below).
|
|
124
|
+
|
|
125
|
+
The abstain threshold above is for the ~800-type census reference; each bundled reference
|
|
126
|
+
reports its own calibration in `build_info.json`, and `broad_mouse_v1`'s is notably better
|
|
127
|
+
(0.88 accuracy at 82% coverage).
|
|
128
|
+
|
|
129
|
+
**Build your own reference** (the only step that may use a GPU; install `scprint`):
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
from actinn_jax.embed import scprint_embed
|
|
133
|
+
emb = scprint_embed(ref_adata) # GPU/MPS, once
|
|
134
|
+
model = aj.build_hierarchical_reference(ref_adata, "cell_type", emb)
|
|
135
|
+
model.save("my_reference") # then annotate on CPU
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
**`refine_to_query`** masks the broad reference down to just the classes your query's own
|
|
139
|
+
predictions actually support (no ground truth, no retraining, sub-second):
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
refined = aj.refine_to_query(model, adata)
|
|
143
|
+
adata = aj.annotate(adata, refined)
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Measured on real data (see
|
|
147
|
+
[actinn-jax-benchmark's REFINE.md](https://github.com/iandriver/actinn-jax-benchmark/blob/main/docs/REFINE.md)):
|
|
148
|
+
this is a safe, free pruning pass — it reliably protects real types and never made
|
|
149
|
+
accuracy worse in testing — but it's **not a fix** for the large-reference accuracy gap.
|
|
150
|
+
The classes actually causing confusion are the model's genuinely-confusable siblings of
|
|
151
|
+
real types, and they carry the same confidence signature as real rare ones, so no
|
|
152
|
+
threshold built from the classifier's own output cleanly separates them. **Retraining on
|
|
153
|
+
a narrower, focused reference (`build_reference.py` above) is the reliable way to close
|
|
154
|
+
that gap** — it measurably outperforms masking because it reshapes the decision boundary
|
|
155
|
+
rather than restricting a frozen one's candidate set.
|
|
156
|
+
|
|
157
|
+
**`refine_to_tissue`** uses a stronger, label-free prior: a sample is (mostly) from one
|
|
158
|
+
tissue, and a liver sample should not be labeled with lung-specific epithelium. It prunes
|
|
159
|
+
the candidate classes to those the CELLxGENE census records in that tissue, while keeping
|
|
160
|
+
**pan-tissue** types (immune, endothelial, stromal) available everywhere — so
|
|
161
|
+
liver-resident T cells and macrophages are unaffected. The broad reference ships with a
|
|
162
|
+
per-class tissue map (`tissue_general` from ~62 M census cells) baked in, so this is
|
|
163
|
+
offline and instant:
|
|
164
|
+
|
|
165
|
+
```python
|
|
166
|
+
refined = aj.refine_to_tissue(model, tissue='liver') # or ['liver','blood'] for mixed
|
|
167
|
+
adata = aj.annotate(adata, refined)
|
|
168
|
+
# or read the tissue from adata.obs['tissue'/'tissue_general'] automatically:
|
|
169
|
+
refined = aj.refine_to_tissue(model, adata=adata) # tissue inferred from obs
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
On a real liver query this roughly **halves** the label set — it removes the cross-tissue
|
|
173
|
+
misfires (cardiac muscle, alveolar fibroblast, colonocyte, adrenal cortex…) that the broad
|
|
174
|
+
798-type model otherwise scatters in, while leaving hepatocyte / LSEC / stellate counts
|
|
175
|
+
essentially unchanged. It composes with `refine_to_query` (a class must be both evidenced
|
|
176
|
+
*and* tissue-plausible):
|
|
177
|
+
|
|
178
|
+
```python
|
|
179
|
+
refined = aj.refine_to_query(model, adata, tissue='liver') # tissue='auto' reads obs
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Common synonyms (`PBMC`→blood, `hepatic`→liver, …) are recognized; a tissue not in the
|
|
183
|
+
reference's vocabulary, or a reference with no tissue map, simply imposes no filter.
|
|
184
|
+
|
|
185
|
+
## Finding novel / unknown cell types
|
|
186
|
+
|
|
187
|
+
A cell type the reference has never seen doesn't show up as a few scattered uncertain
|
|
188
|
+
cells — it shows up as a **coherent group the reference can't confidently explain**.
|
|
189
|
+
`detect_novel_celltypes` looks for exactly that: clusters that are both large enough to
|
|
190
|
+
be a real population and predominantly low-confidence. (This is cluster-level rejection —
|
|
191
|
+
distinct from the per-cell `min_prob` abstain, which flags individual uncertain cells.)
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
evidence, markers = aj.detect_novel_celltypes(
|
|
195
|
+
model, adata,
|
|
196
|
+
cluster_key='leiden', # your clustering; omit to auto-cluster (needs leidenalg)
|
|
197
|
+
min_cells=10, # size floor for calling something novel — lower to go rarer
|
|
198
|
+
)
|
|
199
|
+
evidence[evidence.novel] # candidate novel populations, most-suspect first
|
|
200
|
+
markers['novel_1'] # its top marker genes (vs the rest of the dataset)
|
|
201
|
+
adata.obs['novel'] # 'novel_1'… on flagged cells, '' otherwise
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
`min_cells` is the tunable **minimum population size** — the default (10) separates a real
|
|
205
|
+
novel type from noise/doublets; lower it (`min_cells=5`) to surface rarer candidates, raise
|
|
206
|
+
it to be stricter. `evidence` also reports each cluster's `nearest_label` (what the
|
|
207
|
+
reference *would* have called it) and `frac_low_conf`.
|
|
208
|
+
|
|
209
|
+
**Validated on a real discovery.** In the Krasnow *et al.* (2020) human lung atlas we
|
|
210
|
+
trained a reference but **withheld the pulmonary ionocyte** — itself a landmark 2018
|
|
211
|
+
novel-cell-type discovery (Montoro/Plasschaert) — then ran `detect_novel_celltypes`. Of all
|
|
212
|
+
57 populations, the 22 withheld ionocytes were the **only** cluster flagged (86% low
|
|
213
|
+
confidence, median 0.30; the reference would have mislabeled them "B cell"), and the
|
|
214
|
+
recovered markers were led by **ASCL3** (the ionocyte master transcription factor) and
|
|
215
|
+
**ATP6V0B** (the V-ATPase subunit ionocytes are named for). Raising `min_cells` above 22
|
|
216
|
+
correctly drops the flag — the knob does what it says. The full walkthrough (with the
|
|
217
|
+
t-SNE highlight of the flagged population) is in
|
|
218
|
+
[`examples/novel_celltypes.ipynb`](https://github.com/iandriver/actinn-jax/blob/main/examples/novel_celltypes.ipynb); a script version is
|
|
219
|
+
[`examples/detect_novel_celltypes.py`](https://github.com/iandriver/actinn-jax/blob/main/examples/detect_novel_celltypes.py).
|
|
220
|
+
|
|
221
|
+
## Focused reference: liver (HLiCA)
|
|
222
|
+
|
|
223
|
+
`liver_hlica_v2` ships a **48-type, 7-lineage liver reference** built from
|
|
224
|
+
[HLiCA](https://doi.org/10.64898/2026.06.30.735539) (Edgar, Portman, Hu et al. 2026),
|
|
225
|
+
a 522,730-cell, 110-donor, expert-curated integrated human liver atlas — including
|
|
226
|
+
hepatocyte and endothelial **zonation** (periportal/pericentral), plasmacytoid dendritic
|
|
227
|
+
cells, and HLiCA's own novel-cell-type findings (NRXN1+ stromal cells, CUX2+ hepatic
|
|
228
|
+
stellate cells, MAMLD1+ trans monocytes, TREM2+ macrophages). This is exactly the
|
|
229
|
+
`refine_to_query` → `build_reference.py` recommendation above, executed for real: on a
|
|
230
|
+
held-out study, this focused reference reaches **exact-CL 0.72 / ontology 0.86**, vs.
|
|
231
|
+
**0.23 / 0.58** for the broad 798-type reference on the same cells (see
|
|
232
|
+
[actinn-jax-benchmark's HLICA_LIVER.md](https://github.com/iandriver/actinn-jax-benchmark/blob/main/docs/HLICA_LIVER.md)
|
|
233
|
+
and
|
|
234
|
+
[HLICA_EDGE_CASES.md](https://github.com/iandriver/actinn-jax-benchmark/blob/main/docs/HLICA_EDGE_CASES.md)
|
|
235
|
+
for the full cross-study validation and how v2 fixed two coverage gaps found by checking
|
|
236
|
+
the paper's own stated edge cases against v1).
|
|
237
|
+
|
|
238
|
+
```python
|
|
239
|
+
model = aj.bundled_reference("liver_hlica_v2")
|
|
240
|
+
adata = aj.annotate(adata, model)
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
(`liver_hlica_v1`, 38 types, also ships — for anyone who wants the smaller taxonomy.)
|
|
244
|
+
|
|
245
|
+
Data used under CC-BY 4.0; please cite the original paper if you use this reference.
|
|
246
|
+
|
|
247
|
+
**Runnable notebooks:**
|
|
248
|
+
[`examples/annotate_with_timing.ipynb`](https://github.com/iandriver/actinn-jax/blob/main/examples/annotate_with_timing.ipynb) annotates a
|
|
249
|
+
65k-cell human lung atlas end-to-end — load, throughput (cells/s), exact vs
|
|
250
|
+
**ontology-aware** concordance, and the abstain sweep.
|
|
251
|
+
[`examples/liver_zonation.ipynb`](https://github.com/iandriver/actinn-jax/blob/main/examples/liver_zonation.ipynb) shows **fine-label
|
|
252
|
+
mapping around hepatocyte zonation** — mapping a liver dataset onto the portal→mid→central
|
|
253
|
+
axis, with a confusion heatmap and ordinal (within-1-zone) scoring. See also
|
|
254
|
+
[`examples/quickstart_annotate.py`](https://github.com/iandriver/actinn-jax/blob/main/examples/quickstart_annotate.py) and
|
|
255
|
+
[`examples/build_reference.py`](https://github.com/iandriver/actinn-jax/blob/main/examples/build_reference.py). The *why* —
|
|
256
|
+
accuracy/speed/memory benchmarks and the design rationale — lives in the companion
|
|
257
|
+
[actinn-jax-benchmark](https://github.com/iandriver/actinn-jax-benchmark) repo
|
|
258
|
+
([model-flow mini-paper](https://github.com/iandriver/actinn-jax-benchmark/blob/main/docs/MODEL_FLOW.md)).
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
`actinn-jax` is a from-scratch **JAX** reimplementation of
|
|
264
|
+
[ACTINN](https://github.com/mafeiyang/ACTINN.git) (Ma, Pellegrini et al.). The
|
|
265
|
+
original ACTINN was written in TensorFlow 1.x; this version replaces it with a
|
|
266
|
+
small JIT-compiled JAX MLP and a sparse-aware preprocessing pipeline, adds a
|
|
267
|
+
cached "train once, map many" reference model, and scales to atlas-sized data.
|
|
268
|
+
|
|
269
|
+
## Attribution
|
|
270
|
+
|
|
271
|
+
This package is based entirely on the ACTINN method. If you use it, please cite
|
|
272
|
+
the original work:
|
|
273
|
+
|
|
274
|
+
> Feiyang Ma, Matteo Pellegrini. **ACTINN: automated identification of cell types
|
|
275
|
+
> in single cell RNA sequencing.** *Bioinformatics*, 2020.
|
|
276
|
+
> https://doi.org/10.1093/bioinformatics/btz592
|
|
277
|
+
|
|
278
|
+
Original ACTINN implementation: https://github.com/mafeiyang/ACTINN
|
|
279
|
+
|
|
280
|
+
## Installation
|
|
281
|
+
|
|
282
|
+
The classifier is a small MLP in JAX — **no TensorFlow dependency** — so a plain
|
|
283
|
+
CPU install works everywhere and needs no special wheels.
|
|
284
|
+
|
|
285
|
+
### With `uv` (recommended)
|
|
286
|
+
|
|
287
|
+
[`uv`](https://docs.astral.sh/uv/) resolves the scientific stack (JAX, scanpy) fast
|
|
288
|
+
and pins a compatible Python for you:
|
|
289
|
+
|
|
290
|
+
```bash
|
|
291
|
+
git clone https://github.com/iandriver/actinn-jax.git
|
|
292
|
+
cd actinn-jax
|
|
293
|
+
uv venv --python 3.12 # create .venv on a supported Python
|
|
294
|
+
uv pip install -e . # install actinn-jax + deps into it
|
|
295
|
+
source .venv/bin/activate # (or: `uv run python -c "import actinn_jax"`)
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
### With `pip`
|
|
299
|
+
|
|
300
|
+
```bash
|
|
301
|
+
git clone https://github.com/iandriver/actinn-jax.git
|
|
302
|
+
cd actinn-jax
|
|
303
|
+
python3.12 -m venv .venv && source .venv/bin/activate
|
|
304
|
+
pip install -e .
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
Published builds also install straight from PyPI once released: `pip install actinn-jax`.
|
|
308
|
+
|
|
309
|
+
### Running the example notebooks
|
|
310
|
+
|
|
311
|
+
The [`examples/`](https://github.com/iandriver/actinn-jax/blob/main/examples/) notebooks need a few extra packages (Jupyter,
|
|
312
|
+
matplotlib, the `pronto` ontology reader). Install the `notebooks` extra and
|
|
313
|
+
launch JupyterLab:
|
|
314
|
+
|
|
315
|
+
```bash
|
|
316
|
+
uv pip install -e ".[notebooks]" # or: pip install -e ".[notebooks]"
|
|
317
|
+
uv run jupyter lab examples/ # or: jupyter lab examples/
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
Each notebook has a `QUERY = '...'` line near the top — point it at your own
|
|
321
|
+
`.h5ad` (raw counts). No GPU or extra download is required: the pre-trained
|
|
322
|
+
references ship with the package.
|
|
323
|
+
|
|
324
|
+
### Requirements
|
|
325
|
+
|
|
326
|
+
1. [JAX](https://docs.jax.dev/en/latest/installation.html) — CPU by default, runs everywhere
|
|
327
|
+
2. [scanpy](https://scanpy.readthedocs.io/) / [anndata](https://anndata.readthedocs.io/)
|
|
328
|
+
3. Python 3.10–3.12 (3.13+ may lack JAX/scanpy wheels)
|
|
329
|
+
|
|
330
|
+
The model is small enough that the **CPU path is fast and is recommended**. On
|
|
331
|
+
Apple Silicon an experimental GPU backend is available via `uv pip install -e .[metal]`
|
|
332
|
+
(installs `jax-metal`), but for this model size it is not generally faster than CPU.
|
|
333
|
+
|
|
334
|
+
## Input data
|
|
335
|
+
|
|
336
|
+
`actinn-jax` expects **raw integer counts**. For CELLxGENE-style objects where
|
|
337
|
+
`.X` is normalized and raw counts live in `.raw`, the default `use_raw='auto'`
|
|
338
|
+
picks the raw counts automatically. Genes are matched by `var_names`
|
|
339
|
+
(case-insensitive); the reference and query must share gene-name format.
|
|
340
|
+
|
|
341
|
+
### Gene identifiers are matched automatically
|
|
342
|
+
|
|
343
|
+
Genes are matched by identifier, so query and reference must use the **same
|
|
344
|
+
identifier type**. The bundled references (`broad_human_v1`, `liver_hlica_v2`, …)
|
|
345
|
+
are keyed by **Ensembl gene IDs** (`ENSG…`). **You usually don't need to do
|
|
346
|
+
anything:** if your query's `var_names` are gene **symbols** (`A1BG`, `CD3D`, …)
|
|
347
|
+
and don't match, `actinn-jax` automatically falls back to the best-matching
|
|
348
|
+
`.var` column (`Ensembl_id`, `gene_ids`, `feature_id`, …) and prints a one-line
|
|
349
|
+
notice of which column it used.
|
|
350
|
+
|
|
351
|
+
If no identifier matches at all (neither `var_names` nor any `.var` column), it
|
|
352
|
+
raises a clear error rather than silently returning **one constant label** for
|
|
353
|
+
every cell (the classic symptom of an unmatched gene set). To force a specific
|
|
354
|
+
identifier yourself:
|
|
355
|
+
|
|
356
|
+
```python
|
|
357
|
+
adata.var_names = adata.var['Ensembl_id'].astype(str).values # or 'gene_ids', etc.
|
|
358
|
+
adata.var_names_make_unique()
|
|
359
|
+
adata = aj.annotate(adata, model)
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
(Symbol-keyed references work fine too — just make the *query* resolvable to the
|
|
363
|
+
*reference*. Check overlap with `set(adata.var_names) & set(model.coarse.norm_genes)`.)
|
|
364
|
+
|
|
365
|
+
## Usage
|
|
366
|
+
|
|
367
|
+
### One-off: train and predict in a single call
|
|
368
|
+
|
|
369
|
+
```python
|
|
370
|
+
import actinn_jax as aj
|
|
371
|
+
|
|
372
|
+
adata, params = aj.celltype_predict_actinn(
|
|
373
|
+
adata, # query AnnData (raw counts)
|
|
374
|
+
'reference.h5ad', # labeled reference
|
|
375
|
+
'/path/to/output_dir',
|
|
376
|
+
train_label_name='cell_type',
|
|
377
|
+
output_label_name='celltype_pred',
|
|
378
|
+
)
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
Predictions are written to `adata.obs['celltype_pred']` and confidences to
|
|
382
|
+
`adata.obs['celltype_pred_probability']`.
|
|
383
|
+
|
|
384
|
+
### Reference mapping: train once, map many queries (fastest)
|
|
385
|
+
|
|
386
|
+
```python
|
|
387
|
+
import actinn_jax as aj
|
|
388
|
+
|
|
389
|
+
# Train once and cache to disk (weights .npz + metadata .json).
|
|
390
|
+
model = aj.train_reference('reference.h5ad', train_label_name='cell_type')
|
|
391
|
+
model.save('/path/to/my_reference')
|
|
392
|
+
|
|
393
|
+
# Later / elsewhere: load and annotate any number of queries, no retraining.
|
|
394
|
+
model = aj.ReferenceModel.load('/path/to/my_reference')
|
|
395
|
+
adata, _ = aj.predict(adata, model, output_label_name='celltype_pred')
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
### Large / atlas-scale references
|
|
399
|
+
|
|
400
|
+
```python
|
|
401
|
+
# Balance + cap training cells per class (bounds memory, speeds up training);
|
|
402
|
+
# prediction runs in cell chunks so huge queries never fully densify.
|
|
403
|
+
model = aj.train_reference(
|
|
404
|
+
'big_atlas.h5ad',
|
|
405
|
+
train_label_name='cell_type',
|
|
406
|
+
max_cells_per_label=500, # subsample per class
|
|
407
|
+
)
|
|
408
|
+
adata, _ = aj.predict(adata, model, chunk_size=50000)
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
### Standardization (opt-in accuracy boost)
|
|
412
|
+
|
|
413
|
+
`standardize=True` z-scores each gene with the reference's frozen mean/std and
|
|
414
|
+
applies the same transform to every query — a cheap domain-alignment into the
|
|
415
|
+
reference feature space (the CPU-transferable idea behind scANVI+scArches).
|
|
416
|
+
Across the Open Problems `label_projection` datasets it lifts mean accuracy
|
|
417
|
+
+0.3 pt and macro-F1 +1.1 pt, with the largest gains on batch-shifted and
|
|
418
|
+
fine-grained references (e.g. Tabula Sapiens +1.8 pt accuracy, GTEx macro-F1
|
|
419
|
+
+7.9 pt). See `docs/PREPROC_ABLATION.md` in the benchmark repo.
|
|
420
|
+
|
|
421
|
+
```python
|
|
422
|
+
model = aj.train_reference('reference.h5ad', train_label_name='cell_type',
|
|
423
|
+
standardize=True) # scaler saved with the model
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
It is **opt-in** (default `False`) because it shifts the softmax probability
|
|
427
|
+
calibration, which the two-stage refine / abstain thresholds are tuned against;
|
|
428
|
+
use it for a one-stage accuracy win, or re-tune those thresholds before combining.
|
|
429
|
+
|
|
430
|
+
## How it works
|
|
431
|
+
|
|
432
|
+
- **Sparse-aware preprocessing** — gene-name matching and intersection happen on
|
|
433
|
+
the sparse matrix; only the shared-gene submatrix is densified.
|
|
434
|
+
- **Normalization** follows ACTINN: per-cell library-size normalize to 1e4,
|
|
435
|
+
`log2(x+1)`, then expr- and CV-percentile gene filtering. Optional per-gene
|
|
436
|
+
standardization (`standardize=True`) aligns the query into the reference's
|
|
437
|
+
feature space for an accuracy boost.
|
|
438
|
+
- **Model** — a 4-layer MLP (100→50→25→n_types), Glorot init, Adam with
|
|
439
|
+
exponential-decay schedule, trained with a JIT-compiled epoch step.
|
|
440
|
+
- **Cached `ReferenceModel`** stores the trained weights, gene set, and label
|
|
441
|
+
mapping so queries are projected onto the reference's fixed gene space.
|
|
442
|
+
|
|
443
|
+
## Tests & benchmarks
|
|
444
|
+
|
|
445
|
+
```bash
|
|
446
|
+
uv pip install -e ".[test]" # or: pip install -e ".[test]"
|
|
447
|
+
pytest # synthetic-data unit tests
|
|
448
|
+
python benchmark/benchmark.py # timing on synthetic data
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
## License
|
|
452
|
+
|
|
453
|
+
MIT. See [LICENSE](https://github.com/iandriver/actinn-jax/blob/main/LICENSE).
|