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