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.
- grassmann_ot-0.2.0/LICENSE +1 -0
- grassmann_ot-0.2.0/PKG-INFO +112 -0
- grassmann_ot-0.2.0/README.md +85 -0
- grassmann_ot-0.2.0/examples/basic_usage.py +22 -0
- grassmann_ot-0.2.0/grassmann_ot/__init__.py +28 -0
- grassmann_ot-0.2.0/grassmann_ot/_grassmann.py +300 -0
- grassmann_ot-0.2.0/grassmann_ot/_ot.py +343 -0
- grassmann_ot-0.2.0/grassmann_ot/_utils.py +71 -0
- grassmann_ot-0.2.0/pyproject.toml +38 -0
- grassmann_ot-0.2.0/tests/test_grassmann.py +149 -0
|
@@ -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)
|