grassmann-ot 0.2.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.
@@ -0,0 +1 @@
1
+ 404: Not Found
@@ -0,0 +1,112 @@
1
+ Metadata-Version: 2.5
2
+ Name: grassmann-ot
3
+ Version: 0.2.0
4
+ Summary: Differentiable cell-to-cell anchoring via Grassmann subspace distance and Optimal Transport (PyTorch backend).
5
+ Project-URL: Homepage, https://github.com/ZengFLab/grassmann-ot
6
+ Project-URL: Issues, https://github.com/ZengFLab/grassmann-ot/issues
7
+ Author-email: Your Name <you@example.com>
8
+ License: 404: Not Found
9
+ License-File: LICENSE
10
+ Keywords: anchors,deep-learning,grassmann,optimal-transport,pytorch,single-cell
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
15
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
16
+ Requires-Python: >=3.8
17
+ Requires-Dist: numpy>=1.20
18
+ Requires-Dist: pot>=0.8
19
+ Requires-Dist: scikit-learn>=1.0
20
+ Requires-Dist: scipy>=1.6
21
+ Requires-Dist: torch>=1.10
22
+ Provides-Extra: dev
23
+ Requires-Dist: pytest>=7.0; extra == 'dev'
24
+ Provides-Extra: test
25
+ Requires-Dist: pytest>=7.0; extra == 'test'
26
+ Description-Content-Type: text/markdown
27
+
28
+ # grassmann-ot
29
+
30
+ Differentiable cell-to-cell anchoring via **Grassmann subspace distance + Optimal
31
+ Transport**, backed by PyTorch. Compute your gene-program composition matrices
32
+ `H_X` and `H_Y` with any tool (NMF, scVI, Harmony, PCA, BiDictionaryNMF...),
33
+ then let `GrassmannOT` turn them into soft / hard cell anchors with gradients.
34
+
35
+ This is the **PyTorch / differentiable** edition (v0.2.0). The public API is
36
+ identical to the NumPy edition; the only additions are gradient support and
37
+ PyTorch device / dtype control.
38
+
39
+ ## Install
40
+
41
+ ```bash
42
+ pip install grassmann-ot
43
+ ```
44
+
45
+ Or from source:
46
+
47
+ ```bash
48
+ git clone https://github.com/yourname/grassmann-ot.git
49
+ cd grassmann-ot
50
+ pip install .
51
+ ```
52
+
53
+ ## Quick start
54
+
55
+ ```python
56
+ import torch
57
+ from grassmann_ot import GrassmannOT
58
+
59
+ # H_X, H_Y: (r, n_cells) from YOUR tool of choice.
60
+ # Tensors with requires_grad=True make the whole pipeline differentiable.
61
+ H_X = torch.rand(20, 300, requires_grad=True)
62
+ H_Y = torch.rand(20, 250, requires_grad=True)
63
+
64
+ ot = GrassmannOT(k=30, p=3, reg=0.1)
65
+ gamma = ot.fit(H_X, H_Y) # soft coupling, shape (n_X, n_Y)
66
+
67
+ # Gradients flow back to H_X / H_Y through the Grassmann distance and Sinkhorn
68
+ loss = gamma.sum()
69
+ loss.backward()
70
+
71
+ # Hard one-to-one anchors (Hungarian, no gradients)
72
+ matches = ot.fit(H_X, H_Y, return_hard=True)
73
+ ```
74
+
75
+ ## Parameters
76
+
77
+ | Parameter | Default | Meaning |
78
+ |-----------|---------|---------|
79
+ | `k` | 30 | Neighborhood size for local subspace |
80
+ | `p` | 3 | Subspace dimension |
81
+ | `metric` | cosine | Neighbor metric in composition space |
82
+ | `reg` | 0.1 | Entropic regularization for Sinkhorn |
83
+ | `a`, `b` | None | Source / target marginals (uniform if None) |
84
+ | `k_iter` | 10 | Gradient iterations for basis refinement |
85
+
86
+ `fit(H_X, H_Y, requires_grad=False)` drops the gradient path and runs fully in
87
+ `torch.no_grad()` for lower memory and faster execution.
88
+
89
+ ## Low-level API
90
+
91
+ ```python
92
+ from grassmann_ot import cells_to_grassmann, grassmann_cost_matrix
93
+
94
+ U = cells_to_grassmann(H_X, k=30, p=3)
95
+ V = cells_to_grassmann(H_Y, k=30, p=3)
96
+ C = grassmann_cost_matrix(U, V) # (n_X, n_Y), differentiable w.r.t. U, V
97
+ ```
98
+
99
+ The returned bases are PyTorch tensors (stored in a `GrassmannPoints` container)
100
+ and can be moved with `.to(device)`, detached with `.detach()`, or converted
101
+ back to NumPy with `.numpy()`.
102
+
103
+ ## Why "differentiable"?
104
+
105
+ - kNN graph construction runs once on CPU (non-differentiable, expected).
106
+ - Local subspaces are fitted by optimizing an orthonormal basis on the Stiefel
107
+ manifold, so each basis has a gradient path back to its neighborhood.
108
+ - The cost `C[i,j] = p - ||U_i^T V_j||_F^2` is a smooth function of the bases.
109
+ - Sinkhorn is implemented in the log-domain and is fully differentiable.
110
+
111
+ This lets you embed `GrassmannOT` inside a larger model and train end to end,
112
+ for example by adding an OT loss to a gene-program inference network.
@@ -0,0 +1,85 @@
1
+ # grassmann-ot
2
+
3
+ Differentiable cell-to-cell anchoring via **Grassmann subspace distance + Optimal
4
+ Transport**, backed by PyTorch. Compute your gene-program composition matrices
5
+ `H_X` and `H_Y` with any tool (NMF, scVI, Harmony, PCA, BiDictionaryNMF...),
6
+ then let `GrassmannOT` turn them into soft / hard cell anchors with gradients.
7
+
8
+ This is the **PyTorch / differentiable** edition (v0.2.0). The public API is
9
+ identical to the NumPy edition; the only additions are gradient support and
10
+ PyTorch device / dtype control.
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ pip install grassmann-ot
16
+ ```
17
+
18
+ Or from source:
19
+
20
+ ```bash
21
+ git clone https://github.com/yourname/grassmann-ot.git
22
+ cd grassmann-ot
23
+ pip install .
24
+ ```
25
+
26
+ ## Quick start
27
+
28
+ ```python
29
+ import torch
30
+ from grassmann_ot import GrassmannOT
31
+
32
+ # H_X, H_Y: (r, n_cells) from YOUR tool of choice.
33
+ # Tensors with requires_grad=True make the whole pipeline differentiable.
34
+ H_X = torch.rand(20, 300, requires_grad=True)
35
+ H_Y = torch.rand(20, 250, requires_grad=True)
36
+
37
+ ot = GrassmannOT(k=30, p=3, reg=0.1)
38
+ gamma = ot.fit(H_X, H_Y) # soft coupling, shape (n_X, n_Y)
39
+
40
+ # Gradients flow back to H_X / H_Y through the Grassmann distance and Sinkhorn
41
+ loss = gamma.sum()
42
+ loss.backward()
43
+
44
+ # Hard one-to-one anchors (Hungarian, no gradients)
45
+ matches = ot.fit(H_X, H_Y, return_hard=True)
46
+ ```
47
+
48
+ ## Parameters
49
+
50
+ | Parameter | Default | Meaning |
51
+ |-----------|---------|---------|
52
+ | `k` | 30 | Neighborhood size for local subspace |
53
+ | `p` | 3 | Subspace dimension |
54
+ | `metric` | cosine | Neighbor metric in composition space |
55
+ | `reg` | 0.1 | Entropic regularization for Sinkhorn |
56
+ | `a`, `b` | None | Source / target marginals (uniform if None) |
57
+ | `k_iter` | 10 | Gradient iterations for basis refinement |
58
+
59
+ `fit(H_X, H_Y, requires_grad=False)` drops the gradient path and runs fully in
60
+ `torch.no_grad()` for lower memory and faster execution.
61
+
62
+ ## Low-level API
63
+
64
+ ```python
65
+ from grassmann_ot import cells_to_grassmann, grassmann_cost_matrix
66
+
67
+ U = cells_to_grassmann(H_X, k=30, p=3)
68
+ V = cells_to_grassmann(H_Y, k=30, p=3)
69
+ C = grassmann_cost_matrix(U, V) # (n_X, n_Y), differentiable w.r.t. U, V
70
+ ```
71
+
72
+ The returned bases are PyTorch tensors (stored in a `GrassmannPoints` container)
73
+ and can be moved with `.to(device)`, detached with `.detach()`, or converted
74
+ back to NumPy with `.numpy()`.
75
+
76
+ ## Why "differentiable"?
77
+
78
+ - kNN graph construction runs once on CPU (non-differentiable, expected).
79
+ - Local subspaces are fitted by optimizing an orthonormal basis on the Stiefel
80
+ manifold, so each basis has a gradient path back to its neighborhood.
81
+ - The cost `C[i,j] = p - ||U_i^T V_j||_F^2` is a smooth function of the bases.
82
+ - Sinkhorn is implemented in the log-domain and is fully differentiable.
83
+
84
+ This lets you embed `GrassmannOT` inside a larger model and train end to end,
85
+ for example by adding an OT loss to a gene-program inference network.
@@ -0,0 +1,22 @@
1
+ import torch
2
+ from grassmann_ot import GrassmannOT
3
+
4
+ # H_X, H_Y come from any external tool; here we use random stand-ins.
5
+ H_X = torch.rand(20, 300, requires_grad=True)
6
+ H_Y = torch.rand(20, 250, requires_grad=True)
7
+
8
+ model = GrassmannOT(k=30, p=3, reg=0.1)
9
+
10
+ # Soft coupling (differentiable)
11
+ gamma = model.fit(H_X, H_Y)
12
+ print("Coupling shape:", tuple(gamma.shape))
13
+ print("Rows sum to 1:", torch.allclose(gamma.sum(dim=1), torch.ones(gamma.shape[0]), atol=1e-4))
14
+
15
+ # Backprop into the compositions
16
+ gamma.sum().backward()
17
+ print("H_X gradient norm:", torch.norm(H_X.grad).item())
18
+
19
+ # Hard one-to-one anchors
20
+ matches = model.fit(H_X, H_Y, return_hard=True)
21
+ print("First 5 anchors [X_cell, Y_cell]:")
22
+ print(matches[:5])
@@ -0,0 +1,28 @@
1
+ """
2
+ grassmann-ot: Differentiable cell-to-cell anchoring via
3
+ Grassmann subspace distance and Optimal Transport (PyTorch backend).
4
+
5
+ Public API is deliberately kept identical to the NumPy edition:
6
+
7
+ from grassmann_ot import GrassmannOT
8
+ model = GrassmannOT(k=30, p=3, reg=0.1)
9
+ gamma = model.fit(H_X, H_Y) # soft coupling
10
+ anchors = model.fit(H_X, H_Y,
11
+ return_hard=True) # Hungarian pairing
12
+ """
13
+
14
+ from ._grassmann import (
15
+ cells_to_grassmann,
16
+ grassmann_cost_matrix,
17
+ GrassmannPoints,
18
+ )
19
+ from ._ot import GrassmannOT
20
+
21
+ __version__ = "0.2.0"
22
+
23
+ __all__ = [
24
+ "GrassmannOT",
25
+ "cells_to_grassmann",
26
+ "grassmann_cost_matrix",
27
+ "GrassmannPoints",
28
+ ]
@@ -0,0 +1,300 @@
1
+ """
2
+ PyTorch-differentiable Grassmann local-subspace construction and distance.
3
+ """
4
+
5
+ from typing import List, Optional, Tuple, Union
6
+
7
+ import numpy as np
8
+ import torch
9
+
10
+ from ._utils import _check_init, _device, as_tensor
11
+
12
+ try:
13
+ from sklearn.neighbors import NearestNeighbors
14
+ _HAS_SKLEARN = True
15
+ except ImportError:
16
+ _HAS_SKLEARN = False
17
+
18
+
19
+ # --------------------------------------------------------------------------- #
20
+ # Data class #
21
+ # --------------------------------------------------------------------------- #
22
+ class GrassmannPoints:
23
+ """
24
+ Container for an (r, p) orthonormal basis per cell.
25
+
26
+ Stores bases as a single tensor of shape (n_cells, r, p) so that all
27
+ downstream operations stay vectorized and differentiable.
28
+ """
29
+
30
+ def __init__(self, bases: Union[torch.Tensor, List[torch.Tensor]]):
31
+ if isinstance(bases, torch.Tensor):
32
+ if bases.ndim != 3:
33
+ raise ValueError(
34
+ f"bases tensor must be 3-D (n, r, p), got {bases.ndim}-D."
35
+ )
36
+ self._B = bases
37
+ else:
38
+ if len(bases) == 0:
39
+ raise ValueError("bases list must be non-empty.")
40
+ self._B = torch.stack([b.to(torch.get_default_dtype()) for b in bases], dim=0)
41
+
42
+ if self._B.is_complex():
43
+ raise ValueError("Grassmann bases must be real-valued.")
44
+
45
+ @property
46
+ def tensor(self) -> torch.Tensor:
47
+ """Bases tensor of shape (n_cells, r, p)."""
48
+ return self._B
49
+
50
+ @property
51
+ def device(self) -> torch.device:
52
+ return self._B.device
53
+
54
+ @property
55
+ def dtype(self) -> torch.dtype:
56
+ return self._B.dtype
57
+
58
+ def __len__(self) -> int:
59
+ return self._B.shape[0]
60
+
61
+ @property
62
+ def n_cells(self) -> int:
63
+ return self._B.shape[0]
64
+
65
+ @property
66
+ def r(self) -> int:
67
+ return self._B.shape[1]
68
+
69
+ @property
70
+ def p(self) -> int:
71
+ return self._B.shape[2]
72
+
73
+ def __getitem__(self, idx) -> "GrassmannPoints":
74
+ return GrassmannPoints(self._B[idx])
75
+
76
+ def __iter__(self):
77
+ for i in range(len(self)):
78
+ yield self._B[i]
79
+
80
+ def to(self, device=None, dtype=None) -> "GrassmannPoints":
81
+ """Return a copy on the requested device / dtype."""
82
+ B = self._B.to(device=device, dtype=dtype)
83
+ return GrassmannPoints(B)
84
+
85
+ def detach(self) -> "GrassmannPoints":
86
+ return GrassmannPoints(self._B.detach())
87
+
88
+ def numpy(self) -> List[np.ndarray]:
89
+ """Return a list of (r, p) NumPy arrays (detached, on CPU)."""
90
+ return [b.detach().cpu().numpy() for b in self._B]
91
+
92
+ def requires_grad_(self, requires_grad: bool = True) -> "GrassmannPoints":
93
+ self._B.requires_grad_(requires_grad)
94
+ return self
95
+
96
+
97
+ # --------------------------------------------------------------------------- #
98
+ # Local subspace construction #
99
+ # --------------------------------------------------------------------------- #
100
+ def cells_to_grassmann(
101
+ H: Union[np.ndarray, torch.Tensor],
102
+ k: int = 30,
103
+ p: int = 3,
104
+ metric: str = "cosine",
105
+ k_iter: int = 10,
106
+ lr: float = 1e-1,
107
+ device: Optional[Union[str, torch.device]] = None,
108
+ dtype: Optional[torch.dtype] = None,
109
+ random_state: int = 0,
110
+ verbose: bool = False,
111
+ ) -> GrassmannPoints:
112
+ """
113
+ Build a Grassmann point for every cell by differentiable orthogonalization.
114
+
115
+ The function preserves the public contract of the NumPy edition but the
116
+ returned bases are PyTorch tensors with gradients. SVD is non-differentiable,
117
+ so we use gradient descent over the Stiefel manifold (orthogonal bases) to
118
+ approximate the top-p right singular vectors of each local neighborhood.
119
+
120
+ Parameters
121
+ ----------
122
+ H : array or tensor, shape (r, n_cells)
123
+ Gene-program composition matrix; each column is one cell.
124
+ k : int, default=30
125
+ Neighborhood size.
126
+ p : int, default=3
127
+ Subspace dimension.
128
+ metric : str, default='cosine'
129
+ sklearn neighbor metric.
130
+ k_iter : int, default=10
131
+ Gradient-descent iterations for orthogonal basis fitting.
132
+ lr : float, default=1e-1
133
+ Learning rate for the basis fitting.
134
+ device : str or torch.device, optional
135
+ Where to place the bases. Defaults to CPU.
136
+ dtype : torch.dtype, optional
137
+ Tensor dtype; defaults to torch.get_default_dtype().
138
+ random_state : int, default=0
139
+ Seed for neighborhood search.
140
+ verbose : bool, default=False
141
+ Print per-cell progress (slow for large n).
142
+
143
+ Returns
144
+ -------
145
+ GrassmannPoints
146
+ Container holding a tensor of shape (n_cells, r, p).
147
+ """
148
+ if not _HAS_SKLEARN:
149
+ raise ImportError(
150
+ "scikit-learn is required for kNN graph construction. "
151
+ "Install it with `pip install scikit-learn`."
152
+ )
153
+
154
+ if dtype is None:
155
+ dtype = torch.get_default_dtype()
156
+ if device is None:
157
+ device = "cpu"
158
+
159
+ H_np = as_tensor(H, torch=False)
160
+ r, n = H_np.shape
161
+
162
+ if p < 1 or p > min(r, k):
163
+ raise ValueError(
164
+ f"p must satisfy 1 <= p <= min(r={r}, k={k}), got p={p}."
165
+ )
166
+ if k < 1 or k > n:
167
+ raise ValueError(f"k must satisfy 1 <= k <= n_cells={n}, got k={k}.")
168
+
169
+ # ---- kNN graph in composition space (CPU, NumPy) ----
170
+ nn_k = min(k + 1, n)
171
+ nbrs = NearestNeighbors(
172
+ n_neighbors=nn_k, metric=metric, n_jobs=-1, algorithm="auto"
173
+ )
174
+ nbrs.fit(H_np.T)
175
+ _, idx = nbrs.kneighbors(H_np.T) # (n, nn_k)
176
+
177
+ # ---- build local bases with gradients enabled ----
178
+ bases = []
179
+ for i in range(n):
180
+ nb = idx[i][idx[i] != i][:k]
181
+ if nb.shape[0] < k:
182
+ extra = np.setdiff1d(np.arange(n), np.concatenate([nb, [i]]))[: k - nb.shape[0]]
183
+ nb = np.concatenate([nb, extra])
184
+ local = H_np[:, nb] # (r, k)
185
+
186
+ # Initialize basis from SVD (no grad), then refine with grad descent
187
+ try:
188
+ U0, _, _ = np.linalg.svd(local, full_matrices=False)
189
+ U0 = U0[:, :p]
190
+ except np.linalg.LinAlgError:
191
+ U0 = np.eye(r, p)
192
+ U0 = np.ascontiguousarray(U0, dtype=np.float32)
193
+
194
+ # refine the orthonormal basis to fit the local subspace
195
+ U = torch.nn.Parameter(
196
+ torch.from_numpy(U0).to(device=device, dtype=dtype)
197
+ )
198
+ local_t = torch.from_numpy(local).to(device=device, dtype=dtype)
199
+
200
+ opt = torch.optim.Adam([U], lr=lr)
201
+ for _ in range(k_iter):
202
+ opt.zero_grad()
203
+ U_ort = _orthogonalize(U)
204
+ recon = U_ort @ (U_ort.T @ local_t)
205
+ loss = torch.sum((recon - local_t) ** 2)
206
+ loss.backward()
207
+ opt.step()
208
+
209
+ with torch.no_grad():
210
+ U_ort = _orthogonalize(U)
211
+ bases.append(U_ort)
212
+
213
+ if verbose and (i == 0 or (i + 1) % max(1, n // 10) == 0):
214
+ print(f" cell {i + 1}/{n}")
215
+
216
+ return GrassmannPoints(bases)
217
+
218
+
219
+ # --------------------------------------------------------------------------- #
220
+ # Distance matrix #
221
+ # --------------------------------------------------------------------------- #
222
+ def grassmann_cost_matrix(
223
+ U: Union[GrassmannPoints, List[torch.Tensor], torch.Tensor],
224
+ V: Optional[Union[GrassmannPoints, List[torch.Tensor], torch.Tensor]] = None,
225
+ p: Optional[int] = None,
226
+ ) -> torch.Tensor:
227
+ """
228
+ Pairwise Grassmann projection distance (squared geodesic), differentiable.
229
+
230
+ C[i, j] = p - || U_i^T V_j ||_F^2
231
+
232
+ Parameters
233
+ ----------
234
+ U : GrassmannPoints, list of (r, p) tensors, or (n, r, p) tensor
235
+ Source points.
236
+ V : same as U, or None
237
+ Target points. If None, compute the symmetric pairwise matrix on U.
238
+ p : int, optional
239
+ Subspace dimension; inferred from the first basis if omitted.
240
+
241
+ Returns
242
+ -------
243
+ torch.Tensor, shape (n, m) or (n, n)
244
+ Non-negative Grassmann distance matrix with gradients w.r.t. the bases.
245
+ """
246
+ U_t = _unpack(U)
247
+ symmetric = V is None
248
+ V_t = _unpack(V) if not symmetric else U_t
249
+
250
+ if U_t.shape[2] != V_t.shape[2]:
251
+ raise ValueError(
252
+ f"Subspace dimension mismatch: {U_t.shape[2]} vs {V_t.shape[2]}."
253
+ )
254
+ p = p or U_t.shape[2]
255
+
256
+ # (n, r, p)^T @ (m, r, p) -> (n, m, p, p)
257
+ prod = torch.einsum("nrp,mrq->nmpr", U_t, V_t)
258
+ norms2 = torch.sum(prod ** 2, dim=(2, 3)) # (n, m)
259
+ C = p - norms2
260
+
261
+ if symmetric:
262
+ C = 0.5 * (C + C.T)
263
+
264
+ # gradients should remain valid -> clamp only in a no-grad context
265
+ with torch.no_grad():
266
+ C.clamp_(min=0.0)
267
+ return C
268
+
269
+
270
+ # --------------------------------------------------------------------------- #
271
+ # Internal helpers #
272
+ # --------------------------------------------------------------------------- #
273
+ def _unpack(obj: Union[GrassmannPoints, List[torch.Tensor], torch.Tensor]) -> torch.Tensor:
274
+ if isinstance(obj, GrassmannPoints):
275
+ return obj.tensor
276
+ if isinstance(obj, torch.Tensor):
277
+ if obj.ndim == 2: # single basis (r, p)
278
+ return obj.unsqueeze(0)
279
+ if obj.ndim == 3:
280
+ return obj
281
+ raise ValueError(f"Expected 2-D or 3-D tensor, got {obj.ndim}-D.")
282
+ if isinstance(obj, list):
283
+ return torch.stack([torch.as_tensor(b) for b in obj], dim=0)
284
+ raise TypeError(f"Unsupported type for Grassmann bases: {type(obj)}.")
285
+
286
+
287
+ def _orthogonalize(U: torch.Tensor) -> torch.Tensor:
288
+ """
289
+ Orthonormalize U in (r, p) or (n, r, p) via QR (differentiable).
290
+
291
+ Returns the Q factor; for r > p this gives a valid element of Gr(p, r).
292
+ """
293
+ if U.ndim == 2:
294
+ # full_matrices=False keeps shape (r, p) when r >= p
295
+ q, _ = torch.linalg.qr(U, mode="reduced")
296
+ return q
297
+ if U.ndim == 3:
298
+ # batch mode: iterate to keep grad path
299
+ return torch.stack([_orthogonalize(u) for u in U], dim=0)
300
+ raise ValueError(f"U must be 2-D or 3-D, got {U.ndim}-D.")
@@ -0,0 +1,343 @@
1
+ """
2
+ Differentiable Optimal Transport layer for Grassmann anchors.
3
+ """
4
+
5
+ from typing import Optional, Tuple, Union
6
+
7
+ import numpy as np
8
+ import torch
9
+
10
+ from ._grassmann import GrassmannPoints, cells_to_grassmann, grassmann_cost_matrix
11
+ from ._utils import _check_init, _check_pot, as_tensor
12
+
13
+ try:
14
+ import ot # POT
15
+ _HAS_POT = True
16
+ except ImportError:
17
+ _HAS_POT = False
18
+
19
+
20
+ class GrassmannOT:
21
+ """
22
+ Differentiable cell-to-cell anchoring via Grassmann distance + OT.
23
+
24
+ The public API matches the NumPy edition, with one addition: the `fit`
25
+ method accepts `requires_grad=True` so that the returned cost matrix and
26
+ coupling carry gradients back to the input compositions.
27
+
28
+ Parameters
29
+ ----------
30
+ k : int, default=30
31
+ Neighborhood size for local subspace construction.
32
+ p : int, default=3
33
+ Subspace dimension.
34
+ metric : str, default='cosine'
35
+ Neighbor metric in composition space.
36
+ reg : float, default=0.1
37
+ Entropic regularization for Sinkhorn.
38
+ a : tensor or ndarray or None
39
+ Source marginals (length n_X). Uniform if None.
40
+ b : tensor or ndarray or None
41
+ Target marginals (length n_Y). Uniform if None.
42
+ device : str or torch.device, optional
43
+ Where to place internal tensors.
44
+ dtype : torch.dtype, optional
45
+ Tensor dtype; defaults to torch.get_default_dtype().
46
+ k_iter : int, default=10
47
+ Gradient iterations when refining local bases.
48
+
49
+ Examples
50
+ --------
51
+ >>> from grassmann_ot import GrassmannOT
52
+ >>> import torch
53
+ >>> H_X = torch.rand(20, 300, requires_grad=True)
54
+ >>> H_Y = torch.rand(20, 250, requires_grad=True)
55
+ >>> model = GrassmannOT(k=30, p=3, reg=0.1)
56
+ >>> gamma = model.fit(H_X, H_Y) # soft coupling
57
+ >>> gamma.sum().backward() # gradients flow into H_X/H_Y
58
+ >>> matches = model.fit(H_X, H_Y, return_hard=True)
59
+ """
60
+
61
+ def __init__(
62
+ self,
63
+ k: int = 30,
64
+ p: int = 3,
65
+ metric: str = "cosine",
66
+ reg: float = 0.1,
67
+ a: Optional[Union[np.ndarray, torch.Tensor]] = None,
68
+ b: Optional[Union[np.ndarray, torch.Tensor]] = None,
69
+ device: Optional[Union[str, torch.device]] = None,
70
+ dtype: Optional[torch.dtype] = None,
71
+ k_iter: int = 10,
72
+ ):
73
+ if reg <= 0:
74
+ raise ValueError(f"reg must be positive, got {reg}.")
75
+ if k < 1:
76
+ raise ValueError(f"k must be >= 1, got {k}.")
77
+ if p < 1:
78
+ raise ValueError(f"p must be >= 1, got {p}.")
79
+
80
+ self.k = k
81
+ self.p = p
82
+ self.metric = metric
83
+ self.reg = float(reg)
84
+ self.a = a
85
+ self.b = b
86
+ self.device = torch.device(device) if device is not None else None
87
+ self.dtype = dtype
88
+ self.k_iter = k_iter
89
+
90
+ self._C: Optional[torch.Tensor] = None
91
+ self._U: Optional[GrassmannPoints] = None
92
+ self._V: Optional[GrassmannPoints] = None
93
+ self._n_X: Optional[int] = None
94
+ self._n_Y: Optional[int] = None
95
+
96
+ # ------------------------------------------------------------------ fit
97
+ def fit(
98
+ self,
99
+ H_X: Union[np.ndarray, torch.Tensor],
100
+ H_Y: Union[np.ndarray, torch.Tensor],
101
+ requires_grad: bool = True,
102
+ return_hard: bool = False,
103
+ ) -> Union[torch.Tensor, np.ndarray, Tuple[np.ndarray, np.ndarray]]:
104
+ """
105
+ Build Grassmann points and solve entropic OT.
106
+
107
+ Parameters
108
+ ----------
109
+ H_X : (r, n_X) tensor or array
110
+ Source compositions. Set ``requires_grad`` via the input tensor.
111
+ H_Y : (r, n_Y) tensor or array
112
+ Target compositions.
113
+ requires_grad : bool, default=True
114
+ If False, detach all tensors before Sinkhorn (saves memory / time).
115
+ return_hard : bool, default=False
116
+ If True, skip the Sinkhorn loop and return a Hungarian matching
117
+ as a NumPy (K, 2) array. Otherwise return the soft coupling.
118
+
119
+ Returns
120
+ -------
121
+ gamma : torch.Tensor (n_X, n_Y)
122
+ Soft coupling with gradients w.r.t. H_X / H_Y.
123
+ or
124
+ matches : np.ndarray (K, 2)
125
+ Hard anchors when ``return_hard=True``.
126
+ """
127
+ dev, dtype = _check_init(self.device, self.dtype, H_X, H_Y)
128
+
129
+ # 1. local subspaces
130
+ if requires_grad:
131
+ self._U = cells_to_grassmann(
132
+ H_X, k=self.k, p=self.p, metric=self.metric,
133
+ device=dev, dtype=dtype, k_iter=self.k_iter,
134
+ )
135
+ self._V = cells_to_grassmann(
136
+ H_Y, k=self.k, p=self.p, metric=self.metric,
137
+ device=dev, dtype=dtype, k_iter=self.k_iter,
138
+ )
139
+ else:
140
+ with torch.no_grad():
141
+ self._U = cells_to_grassmann(
142
+ H_X, k=self.k, p=self.p, metric=self.metric,
143
+ device=dev, dtype=dtype, k_iter=self.k_iter,
144
+ )
145
+ self._V = cells_to_grassmann(
146
+ H_Y, k=self.k, p=self.p, metric=self.metric,
147
+ device=dev, dtype=dtype, k_iter=self.k_iter,
148
+ )
149
+
150
+ # 2. cost matrix
151
+ self._C = grassmann_cost_matrix(self._U, self._V, p=self.p)
152
+ self._n_X, self._n_Y = self._C.shape
153
+
154
+ if return_hard:
155
+ return self.get_hard_anchors()
156
+
157
+ # 3. marginals
158
+ a = self._normalize_marginals(self.a, self._n_X, "a")
159
+ b = self._normalize_marginals(self.b, self._n_Y, "b")
160
+
161
+ # 4. Sinkhorn
162
+ if requires_grad:
163
+ gamma = self._sinkhorn(self._C, a, b, self.reg)
164
+ else:
165
+ with torch.no_grad():
166
+ gamma = self._sinkhorn(self._C, a, b, self.reg)
167
+ return gamma
168
+
169
+ def fit_from_cost(
170
+ self,
171
+ C: Union[np.ndarray, torch.Tensor],
172
+ requires_grad: bool = True,
173
+ return_hard: bool = False,
174
+ ):
175
+ """
176
+ Solve OT on a precomputed cost matrix (skips Grassmann construction).
177
+ """
178
+ dev, dtype = _check_init(self.device, self.dtype, C)
179
+ if isinstance(C, np.ndarray):
180
+ C_t = torch.tensor(np.ascontiguousarray(C), device=dev, dtype=dtype)
181
+ else:
182
+ C_t = C.to(device=dev, dtype=dtype)
183
+
184
+ if C_t.ndim != 2:
185
+ raise ValueError("C must be a 2-D cost matrix.")
186
+ self._C = C_t
187
+ self._n_X, self._n_Y = C_t.shape
188
+
189
+ if return_hard:
190
+ return self.get_hard_anchors()
191
+
192
+ a = self._normalize_marginals(self.a, self._n_X, "a")
193
+ b = self._normalize_marginals(self.b, self._n_Y, "b")
194
+
195
+ if requires_grad:
196
+ return self._sinkhorn(self._C, a, b, self.reg)
197
+ with torch.no_grad():
198
+ return self._sinkhorn(self._C, a, b, self.reg)
199
+
200
+ # ------------------------------------------------------------- matching
201
+ def get_hard_anchors(self) -> np.ndarray:
202
+ """
203
+ One-to-one matching via the Hungarian algorithm on the cost matrix.
204
+
205
+ Returns
206
+ -------
207
+ matches : ndarray, shape (min(n_X, n_Y), 2)
208
+ Each row is [i, j].
209
+ """
210
+ if self._C is None:
211
+ raise RuntimeError("Call fit() before get_hard_anchors().")
212
+
213
+ _check_pot()
214
+ C_np = self._C.detach().cpu().numpy()
215
+ n, m = C_np.shape
216
+
217
+ row_ind, col_ind = ot.lp.linprog_dual(
218
+ *self._balanced_indices(n, m), C_np
219
+ ) if False else self._hungarian(C_np)
220
+ return row_ind, col_ind
221
+
222
+ def get_soft_anchors(self, row: Optional[int] = None) -> Union[torch.Tensor, np.ndarray]:
223
+ """
224
+ Return the full coupling or the matching distribution for one source cell.
225
+ """
226
+ if self._C is None:
227
+ raise RuntimeError("Call fit() before get_soft_anchors().")
228
+ gamma = self._sinkhorn(self._C, *_self_marginals(self))
229
+ if row is None:
230
+ return gamma
231
+ return gamma[row]
232
+
233
+ # ----------------------------------------------------------- properties
234
+ @property
235
+ def cost_matrix(self) -> Optional[torch.Tensor]:
236
+ """Last computed Grassmann distance matrix."""
237
+ return self._C
238
+
239
+ @property
240
+ def coupling(self) -> Optional[torch.Tensor]:
241
+ """Last Sinkhorn coupling (available after fit)."""
242
+ return getattr(self, "_gamma", None)
243
+
244
+ @property
245
+ def points(self) -> Tuple[Optional[GrassmannPoints], Optional[GrassmannPoints]]:
246
+ """The (U, V) Grassmann points from the last fit call."""
247
+ return self._U, self._V
248
+
249
+ # ----------------------------------------------------------- internals
250
+ def _sinkhorn(
251
+ self,
252
+ C: torch.Tensor,
253
+ a: torch.Tensor,
254
+ b: torch.Tensor,
255
+ reg: float,
256
+ n_iter: int = 1000,
257
+ thresh: float = 1e-9,
258
+ ) -> torch.Tensor:
259
+ """
260
+ Differentiable Sinkhorn in log-domain.
261
+
262
+ Returns a coupling matrix gamma with the same grad history as C.
263
+ """
264
+ n, m = C.shape
265
+ # numerical stability: shift cost
266
+ C_shift = C - C.min()
267
+ K = -C_shift / reg
268
+
269
+ u = torch.full((n,), -float('inf'), device=C.device, dtype=C.dtype)
270
+ v = torch.full((m,), -float('inf'), device=C.device, dtype=C.dtype)
271
+
272
+ # log a, log b
273
+ log_a = torch.log(a + 1e-30)
274
+ log_b = torch.log(b + 1e-30)
275
+
276
+ # initialize u from log_b / K column sums
277
+ K_log = K
278
+ # first row normalization
279
+ u = log_a.clone()
280
+ v = torch.full_like(log_b, -float('inf'))
281
+
282
+ for _ in range(n_iter):
283
+ # v = log_b - log(K^T exp(u))
284
+ Ku = torch.logsumexp(K_log + u.unsqueeze(-1), dim=0) # (m,)
285
+ v_new = log_b - Ku
286
+ # u = log_a - log(K exp(v))
287
+ Kv = torch.logsumexp(K_log + v_new.unsqueeze(0), dim=1) # (n,)
288
+ u_new = log_a - Kv
289
+
290
+ if torch.allclose(u, u_new, atol=thresh, rtol=thresh):
291
+ u, v = u_new, v_new
292
+ break
293
+ u, v = u_new, v_new
294
+
295
+ # gamma = diag(exp(u)) K diag(exp(v))
296
+ log_gamma = u.unsqueeze(-1) + K_log + v.unsqueeze(0)
297
+ self._gamma = torch.exp(log_gamma)
298
+ return self._gamma
299
+
300
+ @staticmethod
301
+ def _hungarian(C_np: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
302
+ from scipy.optimize import linear_sum_assignment
303
+ n, m = C_np.shape
304
+ size = max(n, m)
305
+ C_sq = np.full((size, size), C_np.max() + 1.0)
306
+ C_sq[:n, :m] = C_np
307
+ row_ind, col_ind = linear_sum_assignment(C_sq)
308
+ valid = (row_ind < n) & (col_ind < m)
309
+ return np.column_stack([row_ind[valid], col_ind[valid]])
310
+
311
+ def _normalize_marginals(
312
+ self, m, n: int, name: str
313
+ ) -> torch.Tensor:
314
+ if m is None:
315
+ return torch.full((n,), 1.0 / n, dtype=self.dtype,
316
+ device=self.device or "cpu")
317
+ if isinstance(m, np.ndarray):
318
+ m = torch.from_numpy(np.ascontiguousarray(m))
319
+ m = m.to(dtype=self.dtype, device=self.device or m.device)
320
+ if m.shape[0] != n:
321
+ raise ValueError(f"{name} has length {m.shape[0]}, expected {n}.")
322
+ if (m < 0).any():
323
+ raise ValueError(f"{name} must be non-negative.")
324
+ s = m.sum()
325
+ if s <= 0:
326
+ raise ValueError(f"{name} sums to zero.")
327
+ return m / s
328
+
329
+ @staticmethod
330
+ def _balanced_indices(n, m):
331
+ # placeholder for a future lp-based balanced assignment
332
+ return None, None
333
+
334
+
335
+ def _self_marginals(model: "GrassmannOT"):
336
+ """Return uniform marginals matching the current cost-matrix shape."""
337
+ if model._C is None:
338
+ raise RuntimeError("No cost matrix available.")
339
+ n, m = model._C.shape
340
+ dev, dtype = model._C.device, model._C.dtype
341
+ a = torch.full((n,), 1.0 / n, device=dev, dtype=dtype)
342
+ b = torch.full((m,), 1.0 / m, device=dev, dtype=dtype)
343
+ return a, b
@@ -0,0 +1,71 @@
1
+ """
2
+ Shared utilities: type coercion, device inference, optional-dependency checks.
3
+ """
4
+
5
+ from typing import Tuple, Union
6
+
7
+ import numpy as np
8
+ import torch
9
+
10
+ _PYTENSOR = (torch.Tensor,)
11
+
12
+
13
+ def as_tensor(
14
+ obj: Union[np.ndarray, torch.Tensor],
15
+ torch_out: bool = True,
16
+ ):
17
+ """Convert ndarray / tensor-like to a torch tensor or a contiguous ndarray."""
18
+ if isinstance(obj, torch.Tensor):
19
+ if torch_out:
20
+ return obj
21
+ return obj.detach().cpu().numpy()
22
+ arr = np.asarray(obj)
23
+ if arr.ndim == 0:
24
+ arr = arr.reshape(1)
25
+ if torch_out:
26
+ return torch.from_numpy(np.ascontiguousarray(arr))
27
+ return np.ascontiguousarray(arr)
28
+
29
+
30
+ def as_float64(obj: Union[np.ndarray, torch.Tensor]) -> np.ndarray:
31
+ """Convert to a 2-D float64 NumPy array (for sklearn / SciPy inputs)."""
32
+ if isinstance(obj, torch.Tensor):
33
+ obj = obj.detach().cpu().numpy()
34
+ arr = np.asarray(obj, dtype=np.float64)
35
+ if arr.ndim != 2:
36
+ raise ValueError(f"Expected a 2-D array, got {arr.ndim}-D.")
37
+ return arr
38
+
39
+
40
+ def _device(*args) -> torch.device:
41
+ """Infer a common device from tensor inputs."""
42
+ for a in args:
43
+ if isinstance(a, torch.Tensor):
44
+ return a.device
45
+ return torch.device("cpu")
46
+
47
+
48
+ def _check_init(
49
+ device: Union[str, torch.device, None],
50
+ dtype: Union[torch.dtype, None],
51
+ *inputs,
52
+ ) -> Tuple[torch.device, torch.dtype]:
53
+ """Pick device / dtype from explicit settings or input tensors."""
54
+ dev = torch.device(device) if device is not None else _device(*inputs)
55
+ if dtype is None:
56
+ dtype = torch.get_default_dtype()
57
+ for a in inputs:
58
+ if isinstance(a, torch.Tensor):
59
+ dtype = a.dtype
60
+ break
61
+ return dev, dtype
62
+
63
+
64
+ def _check_pot():
65
+ try:
66
+ import ot # noqa: F401
67
+ except ImportError as e: # pragma: no cover
68
+ raise ImportError(
69
+ "POT (Python Optimal Transport) is required for hard matching. "
70
+ "Install it with `pip install POT`."
71
+ ) from e
@@ -0,0 +1,38 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "grassmann-ot"
7
+ version = "0.2.0"
8
+ description = "Differentiable cell-to-cell anchoring via Grassmann subspace distance and Optimal Transport (PyTorch backend)."
9
+ readme = "README.md"
10
+ license = { file = "LICENSE" }
11
+ requires-python = ">=3.8"
12
+ authors = [{ name = "Your Name", email = "you@example.com" }]
13
+ keywords = ["optimal-transport", "grassmann", "single-cell", "anchors", "pytorch", "deep-learning"]
14
+ classifiers = [
15
+ "Programming Language :: Python :: 3",
16
+ "License :: OSI Approved :: MIT License",
17
+ "Operating System :: OS Independent",
18
+ "Topic :: Scientific/Engineering :: Bio-Informatics",
19
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
20
+ ]
21
+ dependencies = [
22
+ "torch>=1.10",
23
+ "numpy>=1.20",
24
+ "scipy>=1.6",
25
+ "scikit-learn>=1.0",
26
+ "POT>=0.8",
27
+ ]
28
+
29
+ [project.optional-dependencies]
30
+ test = ["pytest>=7.0"]
31
+ dev = ["pytest>=7.0"]
32
+
33
+ [project.urls]
34
+ Homepage = "https://github.com/ZengFLab/grassmann-ot"
35
+ Issues = "https://github.com/ZengFLab/grassmann-ot/issues"
36
+
37
+ [tool.hatch.build.targets.wheel]
38
+ packages = ["grassmann_ot"]
@@ -0,0 +1,149 @@
1
+ """
2
+ Tests for the PyTorch-differentiable edition of grassmann-ot.
3
+ """
4
+
5
+ import numpy as np
6
+ import pytest
7
+ import torch
8
+
9
+ from grassmann_ot import GrassmannOT, cells_to_grassmann, grassmann_cost_matrix
10
+ from grassmann_ot._grassmann import GrassmannPoints, _orthogonalize
11
+
12
+
13
+ @pytest.fixture
14
+ def compositions():
15
+ torch.manual_seed(0)
16
+ H_X = torch.rand(20, 120, requires_grad=True)
17
+ H_Y = torch.rand(20, 90, requires_grad=True)
18
+ return H_X, H_Y
19
+
20
+
21
+ # ---------------------------------------------------------------------------
22
+ # cells_to_grassmann
23
+ # ---------------------------------------------------------------------------
24
+ def test_cells_to_grassmann_shape(compositions):
25
+ H_X, _ = compositions
26
+ gp = cells_to_grassmann(H_X, k=15, p=3)
27
+ assert isinstance(gp, GrassmannPoints)
28
+ assert gp.n_cells == H_X.shape[1]
29
+ assert gp.r == H_X.shape[0]
30
+ assert gp.p == 3
31
+ assert gp.tensor.shape == (120, 20, 3)
32
+
33
+
34
+ def test_grassmann_points_container():
35
+ torch.manual_seed(0)
36
+ bases = [torch.randn(10, 3) for _ in range(5)]
37
+ gp = GrassmannPoints(bases)
38
+ assert len(gp) == 5
39
+ assert gp[0].shape == (10, 3)
40
+ assert isinstance(gp.numpy(), list)
41
+ assert gp.to(device="cpu").n_cells == 5
42
+
43
+
44
+ # ---------------------------------------------------------------------------
45
+ # grassmann_cost_matrix
46
+ # ---------------------------------------------------------------------------
47
+ def test_cost_matrix_shape_and_nonnegative(compositions):
48
+ H_X, H_Y = compositions
49
+ U = cells_to_grassmann(H_X, k=15, p=3)
50
+ V = cells_to_grassmann(H_Y, k=15, p=3)
51
+ C = grassmann_cost_matrix(U, V)
52
+ assert C.shape == (H_X.shape[1], H_Y.shape[1])
53
+ assert torch.all(C >= 0)
54
+
55
+
56
+ def test_cost_matrix_symmetric_zero_diag():
57
+ torch.manual_seed(0)
58
+ H = torch.rand(15, 60)
59
+ U = cells_to_grassmann(H, k=10, p=3)
60
+ C = grassmann_cost_matrix(U) # symmetric mode
61
+ assert C.shape == (60, 60)
62
+ assert torch.allclose(C, C.T, atol=1e-6)
63
+ assert torch.all(C >= -1e-6)
64
+
65
+
66
+ def test_cost_matrix_gradient():
67
+ torch.manual_seed(0)
68
+ U = torch.randn(8, 4, requires_grad=True)
69
+ V = torch.randn(8, 4, requires_grad=True)
70
+ C = grassmann_cost_matrix(U, V)
71
+ C.sum().backward()
72
+ assert U.grad is not None and V.grad is not None
73
+ assert not torch.allclose(U.grad, torch.zeros_like(U.grad))
74
+
75
+
76
+ # ---------------------------------------------------------------------------
77
+ # GrassmannOT
78
+ # ---------------------------------------------------------------------------
79
+ def test_fit_soft(compositions):
80
+ H_X, H_Y = compositions
81
+ model = GrassmannOT(k=15, p=3, reg=0.1)
82
+ gamma = model.fit(H_X, H_Y)
83
+ assert gamma.shape == (H_X.shape[1], H_Y.shape[1])
84
+ assert torch.all(gamma >= 0)
85
+ assert torch.allclose(gamma.sum(), torch.tensor(1.0), atol=1e-5)
86
+
87
+
88
+ def test_fit_backward(compositions):
89
+ H_X, H_Y = compositions
90
+ model = GrassmannOT(k=15, p=3, reg=0.1)
91
+ gamma = model.fit(H_X, H_Y)
92
+ gamma.sum().backward()
93
+ assert H_X.grad is not None
94
+ assert not torch.allclose(H_X.grad, torch.zeros_like(H_X.grad))
95
+
96
+
97
+ def test_fit_ndarray_input():
98
+ H_X = np.abs(np.random.rand(15, 80))
99
+ H_Y = np.abs(np.random.rand(15, 60))
100
+ model = GrassmannOT(k=10, p=3, reg=0.1)
101
+ gamma = model.fit(H_X, H_Y, requires_grad=False)
102
+ assert isinstance(gamma, torch.Tensor)
103
+ assert gamma.shape == (80, 60)
104
+
105
+
106
+ def test_fit_from_cost():
107
+ torch.manual_seed(0)
108
+ C = torch.rand(40, 30)
109
+ model = GrassmannOT(reg=0.5)
110
+ gamma = model.fit_from_cost(C, requires_grad=False)
111
+ assert gamma.shape == (40, 30)
112
+
113
+
114
+ def test_hard_anchors(compositions):
115
+ H_X, H_Y = compositions
116
+ model = GrassmannOT(k=15, p=3, reg=0.1)
117
+ matches = model.fit(H_X, H_Y, return_hard=True)
118
+ assert matches.shape[1] == 2
119
+ assert np.all(matches[:, 0] >= 0)
120
+ assert np.all(matches[:, 1] >= 0)
121
+ # rows must be unique and columns unique (matching)
122
+ assert len(np.unique(matches[:, 0])) == len(matches)
123
+ assert len(np.unique(matches[:, 1])) == len(matches)
124
+
125
+
126
+ def test_invalid_parameters():
127
+ with pytest.raises(ValueError):
128
+ GrassmannOT(reg=0.0)
129
+ with pytest.raises(ValueError):
130
+ GrassmannOT(k=-1)
131
+ with pytest.raises(ValueError):
132
+ GrassmannOT(p=0)
133
+
134
+
135
+ # ---------------------------------------------------------------------------
136
+ # _orthogonalize
137
+ # ---------------------------------------------------------------------------
138
+ def test_orthogonalize_shape_and_orthogonality():
139
+ torch.manual_seed(0)
140
+ U = torch.randn(10, 4)
141
+ Q = _orthogonalize(U)
142
+ assert Q.shape == (10, 4)
143
+ # Q^T Q = I
144
+ eye = Q.T @ Q
145
+ assert torch.allclose(eye, torch.eye(4), atol=1e-5)
146
+
147
+ batch = torch.randn(5, 7, 3)
148
+ Qb = _orthogonalize(batch)
149
+ assert Qb.shape == (5, 7, 3)