gotmap 0.1.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.
- gotmap-0.1.0/PKG-INFO +188 -0
- gotmap-0.1.0/README.md +171 -0
- gotmap-0.1.0/gotmap/__init__.py +37 -0
- gotmap-0.1.0/gotmap/confidence.py +63 -0
- gotmap-0.1.0/gotmap/knn_map.py +107 -0
- gotmap-0.1.0/gotmap/mapper.py +240 -0
- gotmap-0.1.0/gotmap/nn_map.py +114 -0
- gotmap-0.1.0/gotmap/pl.py +232 -0
- gotmap-0.1.0/gotmap/pp.py +185 -0
- gotmap-0.1.0/gotmap/tl.py +192 -0
- gotmap-0.1.0/gotmap/update.py +330 -0
- gotmap-0.1.0/gotmap/utils.py +39 -0
- gotmap-0.1.0/gotmap.egg-info/PKG-INFO +188 -0
- gotmap-0.1.0/gotmap.egg-info/SOURCES.txt +17 -0
- gotmap-0.1.0/gotmap.egg-info/dependency_links.txt +1 -0
- gotmap-0.1.0/gotmap.egg-info/requires.txt +7 -0
- gotmap-0.1.0/gotmap.egg-info/top_level.txt +1 -0
- gotmap-0.1.0/pyproject.toml +27 -0
- gotmap-0.1.0/setup.cfg +4 -0
gotmap-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: gotmap
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Query-to-Reference Atlas Mapping for Single-Cell Data via Grassmann Optimal Transport
|
|
5
|
+
Author: GOTMap Developers
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/ZengFLab/gotmap
|
|
8
|
+
Requires-Python: >=3.9
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
Requires-Dist: numpy>=1.21
|
|
11
|
+
Requires-Dist: scipy>=1.8
|
|
12
|
+
Requires-Dist: torch>=1.12
|
|
13
|
+
Requires-Dist: scanpy>=1.9
|
|
14
|
+
Requires-Dist: grassmann-ot>=0.3.1
|
|
15
|
+
Requires-Dist: scikit-learn>=1.0
|
|
16
|
+
Requires-Dist: matplotlib>=3.5
|
|
17
|
+
|
|
18
|
+
# GOTMap
|
|
19
|
+
|
|
20
|
+
> **Query-to-Reference Atlas Mapping via Grassmann Optimal Transport**
|
|
21
|
+
|
|
22
|
+
GOTMap maps query single-cell data into a fixed reference atlas using
|
|
23
|
+
[grassmann-ot](https://github.com/ZengFLab/grassmann-ot). It is NOT a
|
|
24
|
+
symmetric batch-integration tool — its purpose is to project new samples
|
|
25
|
+
into an existing atlas for annotation transfer and quality control.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Why GOTMap?
|
|
30
|
+
|
|
31
|
+
| | Symmetric Integration | **GOTMap (Query → Atlas)** |
|
|
32
|
+
|---|---|---|
|
|
33
|
+
| Goal | Remove batch effects | **Map new data into a stable atlas** |
|
|
34
|
+
| Symmetry | Bidirectional | **Unidirectional (reference fixed)** |
|
|
35
|
+
| Output | Joint embedding | **Query coords in reference space** |
|
|
36
|
+
| Labels | Optional | **First-class (transfer + confidence)** |
|
|
37
|
+
| Use case | Combining batches | **Clinical / atlas extension / QC** |
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Installation
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
pip install grassmann-ot scanpy torch
|
|
45
|
+
pip install gotmap-0.1.0.zip
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Quick start
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
import scanpy as sc
|
|
54
|
+
import gotmap
|
|
55
|
+
from gotmap.pp import preprocess_reference, preprocess_query
|
|
56
|
+
from gotmap.tl import map_query_to_reference, transfer_labels, evaluate_mapping
|
|
57
|
+
from gotmap.pl import sanity_check, label_transfer_confidence
|
|
58
|
+
|
|
59
|
+
# ---- 1. Build & freeze reference atlas ----
|
|
60
|
+
ref = sc.read_h5ad("atlas.h5ad")
|
|
61
|
+
ref = preprocess_reference(ref, n_comps=50, n_top_genes=2000)
|
|
62
|
+
|
|
63
|
+
# ---- 2. Preprocess and map query ----
|
|
64
|
+
query = sc.read_h5ad("new_sample.h5ad")
|
|
65
|
+
query = preprocess_query(query, ref, n_comps=50)
|
|
66
|
+
|
|
67
|
+
mapped = map_query_to_reference(query, ref, method="nn",
|
|
68
|
+
hidden_dim=128, epochs=200)
|
|
69
|
+
|
|
70
|
+
# ---- 3. Transfer labels ----
|
|
71
|
+
labelled = transfer_labels(query, ref, label_key="cell_type")
|
|
72
|
+
|
|
73
|
+
# ---- 4. Evaluate ----
|
|
74
|
+
quality = evaluate_mapping(query, ref)
|
|
75
|
+
print(quality) # {'mean_confidence': ..., 'mapping_rate': ..., 'n_anchors': ...}
|
|
76
|
+
|
|
77
|
+
# ---- 5. Visualize ----
|
|
78
|
+
sanity_check(ref, query, mapped_query=mapped, label_key="cell_type")
|
|
79
|
+
label_transfer_confidence(labelled, label_key="cell_type")
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## API
|
|
85
|
+
|
|
86
|
+
### `gotmap.pp` — Preprocessing
|
|
87
|
+
|
|
88
|
+
| Function | Purpose |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `preprocess_reference(adata, n_comps=50, ...)` | Full pipeline: normalize → HVG → PCA |
|
|
91
|
+
| `preprocess_query(adata, reference, n_comps=50)` | Normalize + project query into **reference PCA space** |
|
|
92
|
+
| `normalize_and_hvg(adata, ...)` | Normalize and select HVGs |
|
|
93
|
+
|
|
94
|
+
### `gotmap.tl` — Tools
|
|
95
|
+
|
|
96
|
+
| Function | Purpose |
|
|
97
|
+
|---|---|
|
|
98
|
+
| `map_query_to_reference(query, ref, method="nn", ...)` | Map query → reference space |
|
|
99
|
+
| `transfer_labels(query, ref, label_key, ...)` | Transfer labels + confidence |
|
|
100
|
+
| `evaluate_mapping(query, ref, ...)` | Mapping quality metrics |
|
|
101
|
+
|
|
102
|
+
### `gotmap.pl` — Plotting
|
|
103
|
+
|
|
104
|
+
| Function | Purpose |
|
|
105
|
+
|---|---|
|
|
106
|
+
| `mapping_scatter(adata, basis="X_gotmap", color=...)` | Scatter of mapped cells |
|
|
107
|
+
| `label_transfer_confidence(adata, label_key)` | Confidence histogram + by-label boxplot |
|
|
108
|
+
| `embedding(adata, basis=..., color=...)` | Generic embedding plot |
|
|
109
|
+
| `sanity_check(ref, query, mapped_query=...)` | Reference / mapped / overlay panels |
|
|
110
|
+
|
|
111
|
+
### `gotmap.GOTMap` — Low-level class
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
from gotmap import GOTMap
|
|
115
|
+
|
|
116
|
+
mapper = GOTMap(ref_adata=ref, pca_key="X_pca", k=30, p=3, reg=0.1)
|
|
117
|
+
mapper.fit(query)
|
|
118
|
+
|
|
119
|
+
# neural-network projection
|
|
120
|
+
mapped = mapper.transform(query, method="nn", hidden_dim=128, epochs=200)
|
|
121
|
+
|
|
122
|
+
# kNN projection
|
|
123
|
+
mapped_knn = mapper.transform(query, method="knn")
|
|
124
|
+
|
|
125
|
+
# transfer labels
|
|
126
|
+
labelled = mapper.transfer_labels(query, label_key="cell_type")
|
|
127
|
+
|
|
128
|
+
# quality
|
|
129
|
+
quality = mapper.evaluate_mapping(query)
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### `gotmap.FrozenReference` — Lightweight update (scArches-style)
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
from gotmap import FrozenReference
|
|
136
|
+
|
|
137
|
+
# freeze
|
|
138
|
+
frozen = FrozenReference(ref)
|
|
139
|
+
frozen.save("./frozen_atlas")
|
|
140
|
+
|
|
141
|
+
# load (no recomputation)
|
|
142
|
+
frozen = FrozenReference.load("./frozen_atlas")
|
|
143
|
+
|
|
144
|
+
# project any new query into the SAME space
|
|
145
|
+
query_pca = frozen.project_query(new_query)
|
|
146
|
+
|
|
147
|
+
# extend with new validated cells
|
|
148
|
+
report = frozen.extend(new_cells, min_new_cells=500, update_ratio=0.1)
|
|
149
|
+
# - lightweight: append only (PCA unchanged)
|
|
150
|
+
# - full rebuild triggered when new cells exceed threshold
|
|
151
|
+
|
|
152
|
+
# full rebuild (call sparingly)
|
|
153
|
+
frozen.rebuild_reference(full_atlas)
|
|
154
|
+
frozen.save("./frozen_atlas_v2")
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## How it works
|
|
160
|
+
|
|
161
|
+
1. **Grassmann subspaces** — For each cell, a local PCA neighborhood
|
|
162
|
+
defines a point on the Grassmann manifold (dimension `p`).
|
|
163
|
+
2. **Optimal transport** — Sinkhorn OT computes a soft coupling
|
|
164
|
+
`gamma` (n_ref × n_query) and hard anchors between reference and
|
|
165
|
+
query cells.
|
|
166
|
+
3. **Mapping** — Anchors (+ gamma-sampled soft pairs) supervise a
|
|
167
|
+
neural network that projects query cells into reference PCA space.
|
|
168
|
+
4. **Label transfer** — Weighted kNN in reference space assigns
|
|
169
|
+
cell-type labels; confidence = max class probability.
|
|
170
|
+
|
|
171
|
+
GOTMap calls `grassmann-ot` only for coupling (`fit`, `get_hard_anchors`).
|
|
172
|
+
All mapping logic is implemented independently.
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## Requirements
|
|
177
|
+
|
|
178
|
+
- Python ≥ 3.9
|
|
179
|
+
- scanpy ≥ 1.9
|
|
180
|
+
- grassmann-ot ≥ 0.3.1
|
|
181
|
+
- torch ≥ 1.12
|
|
182
|
+
- numpy, scipy, scikit-learn
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## License
|
|
187
|
+
|
|
188
|
+
MIT
|
gotmap-0.1.0/README.md
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
# GOTMap
|
|
2
|
+
|
|
3
|
+
> **Query-to-Reference Atlas Mapping via Grassmann Optimal Transport**
|
|
4
|
+
|
|
5
|
+
GOTMap maps query single-cell data into a fixed reference atlas using
|
|
6
|
+
[grassmann-ot](https://github.com/ZengFLab/grassmann-ot). It is NOT a
|
|
7
|
+
symmetric batch-integration tool — its purpose is to project new samples
|
|
8
|
+
into an existing atlas for annotation transfer and quality control.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Why GOTMap?
|
|
13
|
+
|
|
14
|
+
| | Symmetric Integration | **GOTMap (Query → Atlas)** |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| Goal | Remove batch effects | **Map new data into a stable atlas** |
|
|
17
|
+
| Symmetry | Bidirectional | **Unidirectional (reference fixed)** |
|
|
18
|
+
| Output | Joint embedding | **Query coords in reference space** |
|
|
19
|
+
| Labels | Optional | **First-class (transfer + confidence)** |
|
|
20
|
+
| Use case | Combining batches | **Clinical / atlas extension / QC** |
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Installation
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pip install grassmann-ot scanpy torch
|
|
28
|
+
pip install gotmap-0.1.0.zip
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Quick start
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
import scanpy as sc
|
|
37
|
+
import gotmap
|
|
38
|
+
from gotmap.pp import preprocess_reference, preprocess_query
|
|
39
|
+
from gotmap.tl import map_query_to_reference, transfer_labels, evaluate_mapping
|
|
40
|
+
from gotmap.pl import sanity_check, label_transfer_confidence
|
|
41
|
+
|
|
42
|
+
# ---- 1. Build & freeze reference atlas ----
|
|
43
|
+
ref = sc.read_h5ad("atlas.h5ad")
|
|
44
|
+
ref = preprocess_reference(ref, n_comps=50, n_top_genes=2000)
|
|
45
|
+
|
|
46
|
+
# ---- 2. Preprocess and map query ----
|
|
47
|
+
query = sc.read_h5ad("new_sample.h5ad")
|
|
48
|
+
query = preprocess_query(query, ref, n_comps=50)
|
|
49
|
+
|
|
50
|
+
mapped = map_query_to_reference(query, ref, method="nn",
|
|
51
|
+
hidden_dim=128, epochs=200)
|
|
52
|
+
|
|
53
|
+
# ---- 3. Transfer labels ----
|
|
54
|
+
labelled = transfer_labels(query, ref, label_key="cell_type")
|
|
55
|
+
|
|
56
|
+
# ---- 4. Evaluate ----
|
|
57
|
+
quality = evaluate_mapping(query, ref)
|
|
58
|
+
print(quality) # {'mean_confidence': ..., 'mapping_rate': ..., 'n_anchors': ...}
|
|
59
|
+
|
|
60
|
+
# ---- 5. Visualize ----
|
|
61
|
+
sanity_check(ref, query, mapped_query=mapped, label_key="cell_type")
|
|
62
|
+
label_transfer_confidence(labelled, label_key="cell_type")
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## API
|
|
68
|
+
|
|
69
|
+
### `gotmap.pp` — Preprocessing
|
|
70
|
+
|
|
71
|
+
| Function | Purpose |
|
|
72
|
+
|---|---|
|
|
73
|
+
| `preprocess_reference(adata, n_comps=50, ...)` | Full pipeline: normalize → HVG → PCA |
|
|
74
|
+
| `preprocess_query(adata, reference, n_comps=50)` | Normalize + project query into **reference PCA space** |
|
|
75
|
+
| `normalize_and_hvg(adata, ...)` | Normalize and select HVGs |
|
|
76
|
+
|
|
77
|
+
### `gotmap.tl` — Tools
|
|
78
|
+
|
|
79
|
+
| Function | Purpose |
|
|
80
|
+
|---|---|
|
|
81
|
+
| `map_query_to_reference(query, ref, method="nn", ...)` | Map query → reference space |
|
|
82
|
+
| `transfer_labels(query, ref, label_key, ...)` | Transfer labels + confidence |
|
|
83
|
+
| `evaluate_mapping(query, ref, ...)` | Mapping quality metrics |
|
|
84
|
+
|
|
85
|
+
### `gotmap.pl` — Plotting
|
|
86
|
+
|
|
87
|
+
| Function | Purpose |
|
|
88
|
+
|---|---|
|
|
89
|
+
| `mapping_scatter(adata, basis="X_gotmap", color=...)` | Scatter of mapped cells |
|
|
90
|
+
| `label_transfer_confidence(adata, label_key)` | Confidence histogram + by-label boxplot |
|
|
91
|
+
| `embedding(adata, basis=..., color=...)` | Generic embedding plot |
|
|
92
|
+
| `sanity_check(ref, query, mapped_query=...)` | Reference / mapped / overlay panels |
|
|
93
|
+
|
|
94
|
+
### `gotmap.GOTMap` — Low-level class
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
from gotmap import GOTMap
|
|
98
|
+
|
|
99
|
+
mapper = GOTMap(ref_adata=ref, pca_key="X_pca", k=30, p=3, reg=0.1)
|
|
100
|
+
mapper.fit(query)
|
|
101
|
+
|
|
102
|
+
# neural-network projection
|
|
103
|
+
mapped = mapper.transform(query, method="nn", hidden_dim=128, epochs=200)
|
|
104
|
+
|
|
105
|
+
# kNN projection
|
|
106
|
+
mapped_knn = mapper.transform(query, method="knn")
|
|
107
|
+
|
|
108
|
+
# transfer labels
|
|
109
|
+
labelled = mapper.transfer_labels(query, label_key="cell_type")
|
|
110
|
+
|
|
111
|
+
# quality
|
|
112
|
+
quality = mapper.evaluate_mapping(query)
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### `gotmap.FrozenReference` — Lightweight update (scArches-style)
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
from gotmap import FrozenReference
|
|
119
|
+
|
|
120
|
+
# freeze
|
|
121
|
+
frozen = FrozenReference(ref)
|
|
122
|
+
frozen.save("./frozen_atlas")
|
|
123
|
+
|
|
124
|
+
# load (no recomputation)
|
|
125
|
+
frozen = FrozenReference.load("./frozen_atlas")
|
|
126
|
+
|
|
127
|
+
# project any new query into the SAME space
|
|
128
|
+
query_pca = frozen.project_query(new_query)
|
|
129
|
+
|
|
130
|
+
# extend with new validated cells
|
|
131
|
+
report = frozen.extend(new_cells, min_new_cells=500, update_ratio=0.1)
|
|
132
|
+
# - lightweight: append only (PCA unchanged)
|
|
133
|
+
# - full rebuild triggered when new cells exceed threshold
|
|
134
|
+
|
|
135
|
+
# full rebuild (call sparingly)
|
|
136
|
+
frozen.rebuild_reference(full_atlas)
|
|
137
|
+
frozen.save("./frozen_atlas_v2")
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## How it works
|
|
143
|
+
|
|
144
|
+
1. **Grassmann subspaces** — For each cell, a local PCA neighborhood
|
|
145
|
+
defines a point on the Grassmann manifold (dimension `p`).
|
|
146
|
+
2. **Optimal transport** — Sinkhorn OT computes a soft coupling
|
|
147
|
+
`gamma` (n_ref × n_query) and hard anchors between reference and
|
|
148
|
+
query cells.
|
|
149
|
+
3. **Mapping** — Anchors (+ gamma-sampled soft pairs) supervise a
|
|
150
|
+
neural network that projects query cells into reference PCA space.
|
|
151
|
+
4. **Label transfer** — Weighted kNN in reference space assigns
|
|
152
|
+
cell-type labels; confidence = max class probability.
|
|
153
|
+
|
|
154
|
+
GOTMap calls `grassmann-ot` only for coupling (`fit`, `get_hard_anchors`).
|
|
155
|
+
All mapping logic is implemented independently.
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Requirements
|
|
160
|
+
|
|
161
|
+
- Python ≥ 3.9
|
|
162
|
+
- scanpy ≥ 1.9
|
|
163
|
+
- grassmann-ot ≥ 0.3.1
|
|
164
|
+
- torch ≥ 1.12
|
|
165
|
+
- numpy, scipy, scikit-learn
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## License
|
|
170
|
+
|
|
171
|
+
MIT
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""
|
|
2
|
+
GOTMap: Query-to-Reference Atlas Mapping via Grassmann Optimal Transport.
|
|
3
|
+
|
|
4
|
+
Modules
|
|
5
|
+
-------
|
|
6
|
+
pp : preprocessing (normalize, HVG, PCA projection)
|
|
7
|
+
tl : tools (map_query_to_reference, transfer_labels, evaluate_mapping)
|
|
8
|
+
pl : plotting (mapping_scatter, label_transfer_confidence, sanity_check)
|
|
9
|
+
|
|
10
|
+
Classes
|
|
11
|
+
-------
|
|
12
|
+
GOTMap : main mapper class
|
|
13
|
+
FrozenReference : lightweight cached reference for repeated mapping
|
|
14
|
+
|
|
15
|
+
Note: torch is imported lazily (only when NN mapping is used).
|
|
16
|
+
kNN mapping, label transfer, and FrozenReference work without torch.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from .mapper import GOTMap
|
|
20
|
+
from .update import FrozenReference
|
|
21
|
+
|
|
22
|
+
__version__ = "0.1.0"
|
|
23
|
+
|
|
24
|
+
__all__ = [
|
|
25
|
+
"GOTMap",
|
|
26
|
+
"FrozenReference",
|
|
27
|
+
"pp",
|
|
28
|
+
"tl",
|
|
29
|
+
"pl",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
# lazy submodules
|
|
33
|
+
import importlib
|
|
34
|
+
def __getattr__(name):
|
|
35
|
+
if name in ("pp", "tl", "pl", "utils", "knn_map", "confidence", "update", "nn_map", "mapper"):
|
|
36
|
+
return importlib.import_module(f".{name}", __name__)
|
|
37
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Mapping confidence / quality evaluation.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
import numpy as np
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def mapping_confidence(ref_pca, query_projected, anchors, gamma):
|
|
9
|
+
"""
|
|
10
|
+
Evaluate the quality of a query-to-reference mapping.
|
|
11
|
+
|
|
12
|
+
Metrics:
|
|
13
|
+
- mean_confidence : average local agreement with anchors
|
|
14
|
+
- per_cell_confidence : per-query-cell confidence
|
|
15
|
+
- n_anchors : number of anchor pairs
|
|
16
|
+
- mapping_rate : fraction of cells with confidence > 0.5
|
|
17
|
+
|
|
18
|
+
Confidence for a query cell is defined as the fraction of its
|
|
19
|
+
k nearest reference cells that are also its anchor partners.
|
|
20
|
+
|
|
21
|
+
Parameters
|
|
22
|
+
----------
|
|
23
|
+
ref_pca : ndarray of shape (n_ref, d)
|
|
24
|
+
Reference PCA coordinates.
|
|
25
|
+
query_projected : ndarray of shape (n_query, d)
|
|
26
|
+
Query coordinates after projection into reference space.
|
|
27
|
+
anchors : ndarray of shape (K, 2)
|
|
28
|
+
Anchor pairs (ref_idx, query_idx).
|
|
29
|
+
gamma : ndarray of shape (n_ref, n_query)
|
|
30
|
+
Soft coupling matrix.
|
|
31
|
+
|
|
32
|
+
Returns
|
|
33
|
+
-------
|
|
34
|
+
dict
|
|
35
|
+
"""
|
|
36
|
+
from sklearn.neighbors import NearestNeighbors
|
|
37
|
+
|
|
38
|
+
n_query = query_projected.shape[0]
|
|
39
|
+
|
|
40
|
+
# reference partners for each query cell (from anchors)
|
|
41
|
+
q2r = {}
|
|
42
|
+
for ri, qi in anchors:
|
|
43
|
+
q2r.setdefault(qi, set()).add(ri)
|
|
44
|
+
|
|
45
|
+
# reference-side kNN in PCA space
|
|
46
|
+
nbrs = NearestNeighbors(n_neighbors=20, metric="cosine")
|
|
47
|
+
nbrs.fit(ref_pca)
|
|
48
|
+
_, idx = nbrs.kneighbors(query_projected)
|
|
49
|
+
|
|
50
|
+
per_cell = np.zeros(n_query)
|
|
51
|
+
for i in range(n_query):
|
|
52
|
+
partners = q2r.get(i, set())
|
|
53
|
+
if len(partners) == 0:
|
|
54
|
+
per_cell[i] = 0.0
|
|
55
|
+
else:
|
|
56
|
+
per_cell[i] = len(set(idx[i]) & partners) / max(len(partners), 1)
|
|
57
|
+
|
|
58
|
+
return {
|
|
59
|
+
"mean_confidence": float(per_cell.mean()),
|
|
60
|
+
"per_cell_confidence": per_cell,
|
|
61
|
+
"n_anchors": len(anchors),
|
|
62
|
+
"mapping_rate": float((per_cell > 0.5).mean()),
|
|
63
|
+
}
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Non-parametric projection and label transfer using anchors + gamma.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
import numpy as np
|
|
6
|
+
from sklearn.neighbors import NearestNeighbors, KNeighborsClassifier
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def knn_projection(ref_pca, query_pca, anchors, gamma, n_neighbors=15):
|
|
10
|
+
"""
|
|
11
|
+
Project query cells into reference PCA space by anchor/kNN interpolation.
|
|
12
|
+
|
|
13
|
+
For each query cell, find its nearest neighbors among the query-side
|
|
14
|
+
anchor cells, then use the corresponding reference anchor coordinates
|
|
15
|
+
(plus high-probability gamma couplings) as interpolation targets.
|
|
16
|
+
|
|
17
|
+
Parameters
|
|
18
|
+
----------
|
|
19
|
+
ref_pca : ndarray of shape (n_ref, d)
|
|
20
|
+
Reference PCA coordinates.
|
|
21
|
+
query_pca : ndarray of shape (n_query, d)
|
|
22
|
+
Query PCA coordinates.
|
|
23
|
+
anchors : ndarray of shape (K, 2)
|
|
24
|
+
Anchor pairs (ref_idx, query_idx).
|
|
25
|
+
gamma : ndarray of shape (n_ref, n_query)
|
|
26
|
+
Soft coupling matrix.
|
|
27
|
+
n_neighbors : int, default=15
|
|
28
|
+
Number of anchor neighbors used for interpolation.
|
|
29
|
+
|
|
30
|
+
Returns
|
|
31
|
+
-------
|
|
32
|
+
ndarray of shape (n_query, d)
|
|
33
|
+
Query cells projected into reference PCA space.
|
|
34
|
+
"""
|
|
35
|
+
n_query = query_pca.shape[0]
|
|
36
|
+
d = ref_pca.shape[1]
|
|
37
|
+
|
|
38
|
+
# query-side anchor coordinates and their reference targets
|
|
39
|
+
anchor_query_coords = query_pca[anchors[:, 1]]
|
|
40
|
+
anchor_ref_coords = ref_pca[anchors[:, 0]]
|
|
41
|
+
|
|
42
|
+
# fit kNN among anchor cells
|
|
43
|
+
nbrs = NearestNeighbors(n_neighbors=min(n_neighbors, len(anchors)),
|
|
44
|
+
metric="cosine")
|
|
45
|
+
nbrs.fit(anchor_query_coords)
|
|
46
|
+
dist, idx = nbrs.kneighbors(query_pca)
|
|
47
|
+
|
|
48
|
+
# weighted interpolation
|
|
49
|
+
weights = 1.0 / (dist + 1e-8)
|
|
50
|
+
weights = weights / weights.sum(axis=1, keepdims=True)
|
|
51
|
+
|
|
52
|
+
projected = np.zeros((n_query, d))
|
|
53
|
+
for i in range(n_query):
|
|
54
|
+
ref_targets = anchor_ref_coords[idx[i]]
|
|
55
|
+
projected[i] = (weights[i, :, None] * ref_targets).sum(axis=0)
|
|
56
|
+
|
|
57
|
+
return projected
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def weighted_knn_labels(ref_pca, query_pca, ref_labels, gamma=None,
|
|
61
|
+
anchors=None, k=50):
|
|
62
|
+
"""
|
|
63
|
+
Transfer labels from reference to query using distance-weighted kNN.
|
|
64
|
+
|
|
65
|
+
Training set is augmented with anchor pairs (high-confidence matches).
|
|
66
|
+
|
|
67
|
+
Parameters
|
|
68
|
+
----------
|
|
69
|
+
ref_pca : ndarray of shape (n_ref, d)
|
|
70
|
+
Reference PCA coordinates.
|
|
71
|
+
query_pca : ndarray of shape (n_query, d)
|
|
72
|
+
Query PCA coordinates (typically already projected).
|
|
73
|
+
ref_labels : ndarray of shape (n_ref,)
|
|
74
|
+
Reference cell-type / state labels.
|
|
75
|
+
gamma : ndarray or None
|
|
76
|
+
(Reserved for future gamma-weighted transfer.)
|
|
77
|
+
anchors : ndarray of shape (K, 2) or None
|
|
78
|
+
Anchor pairs used to augment training set.
|
|
79
|
+
k : int, default=50
|
|
80
|
+
Number of neighbors.
|
|
81
|
+
|
|
82
|
+
Returns
|
|
83
|
+
-------
|
|
84
|
+
pred_labels : ndarray of shape (n_query,)
|
|
85
|
+
Predicted label for each query cell.
|
|
86
|
+
conf : ndarray of shape (n_query,)
|
|
87
|
+
Max predicted probability (= mapping confidence).
|
|
88
|
+
"""
|
|
89
|
+
if anchors is not None and len(anchors) > 0:
|
|
90
|
+
anchor_ref = ref_pca[anchors[:, 0]]
|
|
91
|
+
anchor_query = ref_pca[anchors[:, 1]]
|
|
92
|
+
anchor_labels = ref_labels[anchors[:, 0]]
|
|
93
|
+
|
|
94
|
+
X_train = np.vstack([anchor_query, ref_pca])
|
|
95
|
+
y_train = np.concatenate([anchor_labels, ref_labels])
|
|
96
|
+
else:
|
|
97
|
+
X_train = ref_pca
|
|
98
|
+
y_train = ref_labels
|
|
99
|
+
|
|
100
|
+
knn = KNeighborsClassifier(n_neighbors=min(k, len(X_train)),
|
|
101
|
+
weights="distance")
|
|
102
|
+
knn.fit(X_train, y_train)
|
|
103
|
+
|
|
104
|
+
pred = knn.predict(query_pca)
|
|
105
|
+
proba = knn.predict_proba(query_pca)
|
|
106
|
+
conf = proba.max(axis=1)
|
|
107
|
+
return pred, conf
|