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 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