gotmap 0.1.0__py3-none-any.whl
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/__init__.py +37 -0
- gotmap/confidence.py +63 -0
- gotmap/knn_map.py +107 -0
- gotmap/mapper.py +240 -0
- gotmap/nn_map.py +114 -0
- gotmap/pl.py +232 -0
- gotmap/pp.py +185 -0
- gotmap/tl.py +192 -0
- gotmap/update.py +330 -0
- gotmap/utils.py +39 -0
- gotmap-0.1.0.dist-info/METADATA +188 -0
- gotmap-0.1.0.dist-info/RECORD +14 -0
- gotmap-0.1.0.dist-info/WHEEL +5 -0
- gotmap-0.1.0.dist-info/top_level.txt +1 -0
gotmap/__init__.py
ADDED
|
@@ -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}")
|
gotmap/confidence.py
ADDED
|
@@ -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
|
+
}
|
gotmap/knn_map.py
ADDED
|
@@ -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
|
gotmap/mapper.py
ADDED
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
"""
|
|
2
|
+
GOTMap: Query-to-Reference Atlas Mapping via Grassmann Optimal Transport.
|
|
3
|
+
|
|
4
|
+
Main class: GOTMap
|
|
5
|
+
- fit(query_adata): compute Grassmann-OT coupling (gamma, anchors)
|
|
6
|
+
- transform(query_adata): project query cells into reference PCA space
|
|
7
|
+
- transfer_labels(query_adata): transfer cell type / state labels
|
|
8
|
+
- evaluate_mapping(query_adata): mapping confidence scores
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
import numpy as np
|
|
12
|
+
import scanpy as sc
|
|
13
|
+
from grassmann_ot import GrassmannOT
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class GOTMap:
|
|
17
|
+
"""
|
|
18
|
+
Map query single-cell data into a reference atlas using Grassmann-OT.
|
|
19
|
+
|
|
20
|
+
Parameters
|
|
21
|
+
----------
|
|
22
|
+
ref_adata : AnnData
|
|
23
|
+
Reference atlas (well-annotated, stable).
|
|
24
|
+
pca_key : str, default='X_pca'
|
|
25
|
+
Key in obsm for PCA coordinates.
|
|
26
|
+
k : int, default=30
|
|
27
|
+
Neighborhood size for Grassmann construction.
|
|
28
|
+
p : int, default=3
|
|
29
|
+
Grassmann subspace dimension.
|
|
30
|
+
reg : float, default=0.1
|
|
31
|
+
Sinkhorn entropy regularization.
|
|
32
|
+
backend : str, default='batched'
|
|
33
|
+
Grassmann construction backend.
|
|
34
|
+
device : str or None, default=None
|
|
35
|
+
Torch device (None = auto-detect).
|
|
36
|
+
|
|
37
|
+
Attributes
|
|
38
|
+
----------
|
|
39
|
+
gamma_ : ndarray of shape (n_ref, n_query)
|
|
40
|
+
Soft coupling matrix after fitting.
|
|
41
|
+
anchors_ : ndarray of shape (K, 2)
|
|
42
|
+
Mutual nearest anchors (ref_idx, query_idx).
|
|
43
|
+
nn_mapper_ : torch.nn.Module or None
|
|
44
|
+
Trained neural mapper (available after transform(method='nn')).
|
|
45
|
+
"""
|
|
46
|
+
|
|
47
|
+
def __init__(self, ref_adata, pca_key="X_pca",
|
|
48
|
+
k=30, p=3, reg=0.1, backend="batched", device=None):
|
|
49
|
+
self.ref_adata = ref_adata.copy()
|
|
50
|
+
self.pca_key = pca_key
|
|
51
|
+
self.k = k
|
|
52
|
+
self.p = p
|
|
53
|
+
self.reg = reg
|
|
54
|
+
self.backend = backend
|
|
55
|
+
self.device = device
|
|
56
|
+
|
|
57
|
+
# fitted attributes
|
|
58
|
+
self.ot_ = None
|
|
59
|
+
self.anchors_ = None
|
|
60
|
+
self.gamma_ = None
|
|
61
|
+
self.nn_mapper_ = None
|
|
62
|
+
|
|
63
|
+
# ----------------------------------------------------------------
|
|
64
|
+
# fit
|
|
65
|
+
# ----------------------------------------------------------------
|
|
66
|
+
def fit(self, query_adata):
|
|
67
|
+
"""
|
|
68
|
+
Compute Grassmann-OT coupling between reference and query.
|
|
69
|
+
|
|
70
|
+
Parameters
|
|
71
|
+
----------
|
|
72
|
+
query_adata : AnnData
|
|
73
|
+
Query batch to map.
|
|
74
|
+
|
|
75
|
+
Returns
|
|
76
|
+
-------
|
|
77
|
+
self
|
|
78
|
+
"""
|
|
79
|
+
H_X = self.ref_adata.obsm[self.pca_key].T.astype(np.float64)
|
|
80
|
+
H_Y = query_adata.obsm[self.pca_key].T.astype(np.float64)
|
|
81
|
+
|
|
82
|
+
got = GrassmannOT(
|
|
83
|
+
k=self.k, p=self.p, reg=self.reg,
|
|
84
|
+
backend=self.backend, device=self.device
|
|
85
|
+
)
|
|
86
|
+
self.gamma_ = got.fit(H_X, H_Y)
|
|
87
|
+
self.anchors_ = got.get_hard_anchors(method="mutual")
|
|
88
|
+
self.ot_ = got
|
|
89
|
+
return self
|
|
90
|
+
|
|
91
|
+
# ----------------------------------------------------------------
|
|
92
|
+
# transform
|
|
93
|
+
# ----------------------------------------------------------------
|
|
94
|
+
def transform(self, query_adata, method="nn", **kwargs):
|
|
95
|
+
"""
|
|
96
|
+
Project query cells into reference PCA space.
|
|
97
|
+
|
|
98
|
+
Parameters
|
|
99
|
+
----------
|
|
100
|
+
query_adata : AnnData
|
|
101
|
+
Query batch to map.
|
|
102
|
+
method : str, default='nn'
|
|
103
|
+
'nn' : neural-network based projection.
|
|
104
|
+
'knn' : non-parametric kNN projection via anchors + gamma.
|
|
105
|
+
|
|
106
|
+
Returns
|
|
107
|
+
-------
|
|
108
|
+
AnnData
|
|
109
|
+
Query data with obsm['X_gotmap'] set to the projected coordinates.
|
|
110
|
+
"""
|
|
111
|
+
if self.gamma_ is None:
|
|
112
|
+
raise RuntimeError("Call fit() before transform().")
|
|
113
|
+
|
|
114
|
+
if method == "nn":
|
|
115
|
+
return self._transform_nn(query_adata, **kwargs)
|
|
116
|
+
elif method == "knn":
|
|
117
|
+
return self._transform_knn(query_adata, **kwargs)
|
|
118
|
+
else:
|
|
119
|
+
raise ValueError(f"Unknown method: {method}")
|
|
120
|
+
|
|
121
|
+
def _transform_nn(self, query_adata, hidden_dim=128, epochs=200, lr=1e-3):
|
|
122
|
+
from .nn_map import train_neural_mapper, apply_neural_mapper
|
|
123
|
+
|
|
124
|
+
ref_pca = self.ref_adata.obsm[self.pca_key]
|
|
125
|
+
query_pca = query_adata.obsm[self.pca_key]
|
|
126
|
+
|
|
127
|
+
# anchor supervision
|
|
128
|
+
anchor_ref = ref_pca[self.anchors_[:, 0]]
|
|
129
|
+
anchor_query = query_pca[self.anchors_[:, 1]]
|
|
130
|
+
|
|
131
|
+
# gamma soft-augmentation: top 1% couplings
|
|
132
|
+
gamma = self.gamma_
|
|
133
|
+
soft_i, soft_j = np.where(gamma > np.percentile(gamma, 99))
|
|
134
|
+
extra_ref = ref_pca[soft_i]
|
|
135
|
+
extra_query = query_pca[soft_j]
|
|
136
|
+
|
|
137
|
+
X_src = np.vstack([anchor_query, extra_query])
|
|
138
|
+
X_tgt = np.vstack([anchor_ref, extra_ref])
|
|
139
|
+
|
|
140
|
+
self.nn_mapper_ = train_neural_mapper(
|
|
141
|
+
X_src, X_tgt,
|
|
142
|
+
hidden_dim=hidden_dim, epochs=epochs, lr=lr
|
|
143
|
+
)
|
|
144
|
+
projected = apply_neural_mapper(self.nn_mapper_, query_pca)
|
|
145
|
+
|
|
146
|
+
result = query_adata.copy()
|
|
147
|
+
result.obsm["X_gotmap"] = projected
|
|
148
|
+
return result
|
|
149
|
+
|
|
150
|
+
def _transform_knn(self, query_adata, n_neighbors=15):
|
|
151
|
+
from .knn_map import knn_projection
|
|
152
|
+
|
|
153
|
+
ref_pca = self.ref_adata.obsm[self.pca_key]
|
|
154
|
+
query_pca = query_adata.obsm[self.pca_key]
|
|
155
|
+
projected = knn_projection(
|
|
156
|
+
ref_pca, query_pca,
|
|
157
|
+
self.anchors_, self.gamma_,
|
|
158
|
+
n_neighbors=n_neighbors
|
|
159
|
+
)
|
|
160
|
+
result = query_adata.copy()
|
|
161
|
+
result.obsm["X_gotmap"] = projected
|
|
162
|
+
return result
|
|
163
|
+
|
|
164
|
+
# ----------------------------------------------------------------
|
|
165
|
+
# label transfer
|
|
166
|
+
# ----------------------------------------------------------------
|
|
167
|
+
def transfer_labels(self, query_adata, label_key, method="weighted_knn", k=50):
|
|
168
|
+
"""
|
|
169
|
+
Transfer cell type / state labels from reference to query.
|
|
170
|
+
|
|
171
|
+
Parameters
|
|
172
|
+
----------
|
|
173
|
+
query_adata : AnnData
|
|
174
|
+
Query batch to label.
|
|
175
|
+
label_key : str
|
|
176
|
+
Column in ref_adata.obs containing reference labels.
|
|
177
|
+
method : str, default='weighted_knn'
|
|
178
|
+
Label transfer strategy.
|
|
179
|
+
k : int, default=50
|
|
180
|
+
Number of neighbors for weighted kNN.
|
|
181
|
+
|
|
182
|
+
Returns
|
|
183
|
+
-------
|
|
184
|
+
AnnData
|
|
185
|
+
Query data with two new columns in obs:
|
|
186
|
+
'{label_key}_predicted' and '{label_key}_confidence'.
|
|
187
|
+
"""
|
|
188
|
+
if label_key not in self.ref_adata.obs:
|
|
189
|
+
raise ValueError(f"'{label_key}' not found in ref_adata.obs")
|
|
190
|
+
|
|
191
|
+
from .knn_map import weighted_knn_labels
|
|
192
|
+
|
|
193
|
+
query = self.transform(query_adata, method="knn")
|
|
194
|
+
ref_labels = self.ref_adata.obs[label_key].values
|
|
195
|
+
|
|
196
|
+
pred_labels, conf = weighted_knn_labels(
|
|
197
|
+
self.ref_adata.obsm[self.pca_key],
|
|
198
|
+
query.obsm["X_gotmap"],
|
|
199
|
+
ref_labels,
|
|
200
|
+
gamma=self.gamma_,
|
|
201
|
+
anchors=self.anchors_,
|
|
202
|
+
k=k
|
|
203
|
+
)
|
|
204
|
+
query.obs[f"{label_key}_predicted"] = pred_labels
|
|
205
|
+
query.obs[f"{label_key}_confidence"] = conf
|
|
206
|
+
return query
|
|
207
|
+
|
|
208
|
+
# ----------------------------------------------------------------
|
|
209
|
+
# evaluation
|
|
210
|
+
# ----------------------------------------------------------------
|
|
211
|
+
def evaluate_mapping(self, query_adata):
|
|
212
|
+
"""
|
|
213
|
+
Compute mapping confidence scores for each query cell.
|
|
214
|
+
|
|
215
|
+
Parameters
|
|
216
|
+
----------
|
|
217
|
+
query_adata : AnnData
|
|
218
|
+
Query batch to evaluate.
|
|
219
|
+
|
|
220
|
+
Returns
|
|
221
|
+
-------
|
|
222
|
+
dict with keys:
|
|
223
|
+
'mean_confidence' : float
|
|
224
|
+
'per_cell_confidence' : ndarray of shape (n_query,)
|
|
225
|
+
'n_anchors' : int
|
|
226
|
+
'mapping_rate' : float (fraction of cells with confidence > 0.5)
|
|
227
|
+
"""
|
|
228
|
+
if "X_gotmap" not in query_adata.obsm:
|
|
229
|
+
query = self.transform(query_adata, method="knn")
|
|
230
|
+
else:
|
|
231
|
+
query = query_adata
|
|
232
|
+
|
|
233
|
+
from .confidence import mapping_confidence
|
|
234
|
+
|
|
235
|
+
return mapping_confidence(
|
|
236
|
+
self.ref_adata.obsm[self.pca_key],
|
|
237
|
+
query.obsm["X_gotmap"],
|
|
238
|
+
self.anchors_,
|
|
239
|
+
self.gamma_
|
|
240
|
+
)
|
gotmap/nn_map.py
ADDED
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Neural-network based projection from query space to reference space.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
import numpy as np
|
|
6
|
+
import torch
|
|
7
|
+
import torch.nn as nn
|
|
8
|
+
import torch.optim as optim
|
|
9
|
+
from sklearn.preprocessing import StandardScaler
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class _MapperNet(nn.Module):
|
|
13
|
+
"""Lightweight MLP: query PCA -> reference PCA."""
|
|
14
|
+
|
|
15
|
+
def __init__(self, input_dim, output_dim, hidden_dim=128):
|
|
16
|
+
super().__init__()
|
|
17
|
+
self.scaler_x = None
|
|
18
|
+
self.scaler_y = None
|
|
19
|
+
self.net = nn.Sequential(
|
|
20
|
+
nn.Linear(input_dim, hidden_dim),
|
|
21
|
+
nn.ReLU(),
|
|
22
|
+
nn.Dropout(0.1),
|
|
23
|
+
nn.Linear(hidden_dim, hidden_dim // 2),
|
|
24
|
+
nn.ReLU(),
|
|
25
|
+
nn.Linear(hidden_dim // 2, output_dim),
|
|
26
|
+
)
|
|
27
|
+
|
|
28
|
+
def forward(self, x):
|
|
29
|
+
return self.net(x)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def train_neural_mapper(X_source, X_target, hidden_dim=128,
|
|
33
|
+
epochs=200, lr=1e-3, batch_size=256):
|
|
34
|
+
"""
|
|
35
|
+
Train an MLP to map source (query) cells into target (reference) PCA space.
|
|
36
|
+
|
|
37
|
+
Uses anchors (hard) + gamma top-couplings (soft) as training pairs.
|
|
38
|
+
|
|
39
|
+
Parameters
|
|
40
|
+
----------
|
|
41
|
+
X_source : ndarray of shape (N, d)
|
|
42
|
+
Query PCA coordinates.
|
|
43
|
+
X_target : ndarray of shape (N, d)
|
|
44
|
+
Reference PCA coordinates (paired with X_source).
|
|
45
|
+
hidden_dim : int, default=128
|
|
46
|
+
epochs : int, default=200
|
|
47
|
+
lr : float, default=1e-3
|
|
48
|
+
batch_size : int, default=256
|
|
49
|
+
|
|
50
|
+
Returns
|
|
51
|
+
-------
|
|
52
|
+
_MapperNet
|
|
53
|
+
Trained model (with attached scalers).
|
|
54
|
+
"""
|
|
55
|
+
device = "cuda" if torch.cuda.is_available() else "cpu"
|
|
56
|
+
input_dim = X_source.shape[1]
|
|
57
|
+
output_dim = X_target.shape[1]
|
|
58
|
+
|
|
59
|
+
scaler_x = StandardScaler()
|
|
60
|
+
scaler_y = StandardScaler()
|
|
61
|
+
X_source = scaler_x.fit_transform(X_source)
|
|
62
|
+
X_target = scaler_y.fit_transform(X_target)
|
|
63
|
+
|
|
64
|
+
model = _MapperNet(input_dim, output_dim, hidden_dim).to(device)
|
|
65
|
+
optimizer = optim.Adam(model.parameters(), lr=lr)
|
|
66
|
+
criterion = nn.MSELoss()
|
|
67
|
+
|
|
68
|
+
X_src = torch.tensor(X_source, dtype=torch.float32).to(device)
|
|
69
|
+
X_tgt = torch.tensor(X_target, dtype=torch.float32).to(device)
|
|
70
|
+
|
|
71
|
+
model.train()
|
|
72
|
+
for epoch in range(epochs):
|
|
73
|
+
perm = torch.randperm(X_src.size(0))
|
|
74
|
+
epoch_loss = 0.0
|
|
75
|
+
for i in range(0, X_src.size(0), batch_size):
|
|
76
|
+
idx = perm[i:i + batch_size]
|
|
77
|
+
batch_x, batch_y = X_src[idx], X_tgt[idx]
|
|
78
|
+
optimizer.zero_grad()
|
|
79
|
+
pred = model(batch_x)
|
|
80
|
+
loss = criterion(pred, batch_y)
|
|
81
|
+
loss.backward()
|
|
82
|
+
optimizer.step()
|
|
83
|
+
epoch_loss += loss.item()
|
|
84
|
+
if (epoch + 1) % 50 == 0:
|
|
85
|
+
print(f"[GOTMap] Epoch {epoch+1}/{epochs} loss={epoch_loss:.4f}")
|
|
86
|
+
|
|
87
|
+
model.scaler_x = scaler_x
|
|
88
|
+
model.scaler_y = scaler_y
|
|
89
|
+
return model
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def apply_neural_mapper(model, X):
|
|
93
|
+
"""
|
|
94
|
+
Apply a trained mapper to new query data.
|
|
95
|
+
|
|
96
|
+
Parameters
|
|
97
|
+
----------
|
|
98
|
+
model : _MapperNet
|
|
99
|
+
Trained mapper returned by train_neural_mapper.
|
|
100
|
+
X : ndarray of shape (M, d)
|
|
101
|
+
Query PCA coordinates.
|
|
102
|
+
|
|
103
|
+
Returns
|
|
104
|
+
-------
|
|
105
|
+
ndarray of shape (M, output_dim)
|
|
106
|
+
Projected coordinates in reference PCA space.
|
|
107
|
+
"""
|
|
108
|
+
device = next(model.parameters()).device
|
|
109
|
+
X_scaled = model.scaler_x.transform(X)
|
|
110
|
+
X_tensor = torch.tensor(X_scaled, dtype=torch.float32).to(device)
|
|
111
|
+
model.eval()
|
|
112
|
+
with torch.no_grad():
|
|
113
|
+
pred = model(X_tensor).cpu().numpy()
|
|
114
|
+
return model.scaler_y.inverse_transform(pred)
|