bidictnmf 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.
- bidictnmf-0.2.0/LICENSE +21 -0
- bidictnmf-0.2.0/PKG-INFO +163 -0
- bidictnmf-0.2.0/README.md +130 -0
- bidictnmf-0.2.0/bidictnmf/__init__.py +26 -0
- bidictnmf-0.2.0/bidictnmf/model.py +464 -0
- bidictnmf-0.2.0/bidictnmf/py.typed +0 -0
- bidictnmf-0.2.0/bidictnmf.egg-info/PKG-INFO +163 -0
- bidictnmf-0.2.0/bidictnmf.egg-info/SOURCES.txt +14 -0
- bidictnmf-0.2.0/bidictnmf.egg-info/dependency_links.txt +1 -0
- bidictnmf-0.2.0/bidictnmf.egg-info/requires.txt +12 -0
- bidictnmf-0.2.0/bidictnmf.egg-info/top_level.txt +1 -0
- bidictnmf-0.2.0/pyproject.toml +56 -0
- bidictnmf-0.2.0/setup.cfg +4 -0
- bidictnmf-0.2.0/setup.py +2 -0
- bidictnmf-0.2.0/tests/test_bidictnmf.py +94 -0
bidictnmf-0.2.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 BiDictionaryNMF Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
bidictnmf-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: bidictnmf
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Differentiable Bi-Dictionary Non-negative Matrix Factorization for cross-batch gene-program integration.
|
|
5
|
+
Author: BiDictionaryNMF Contributors
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/ZengFLab/bidictnmf
|
|
8
|
+
Project-URL: Repository, https://github.com/ZengFLab/bidictnmf
|
|
9
|
+
Project-URL: Issues, https://github.com/ZengFLab/bidictnmf/issues
|
|
10
|
+
Keywords: nmf,non-negative-matrix-factorization,single-cell,batch-integration,pytorch,gene-programs,bioinformatics
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
19
|
+
Requires-Python: >=3.8
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: numpy>=1.19
|
|
23
|
+
Requires-Dist: scipy>=1.5
|
|
24
|
+
Requires-Dist: scikit-learn>=0.24
|
|
25
|
+
Requires-Dist: torch>=1.10
|
|
26
|
+
Requires-Dist: tqdm>=4.0
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: pytest>=6.0; extra == "dev"
|
|
29
|
+
Requires-Dist: matplotlib>=3.0; extra == "dev"
|
|
30
|
+
Provides-Extra: docs
|
|
31
|
+
Requires-Dist: sphinx>=4.0; extra == "docs"
|
|
32
|
+
Dynamic: license-file
|
|
33
|
+
|
|
34
|
+
# BiDictionaryNMF
|
|
35
|
+
|
|
36
|
+
> Differentiable **Bi-Dictionary Non-negative Matrix Factorization** for integrating
|
|
37
|
+
> two batches / datasets while separating shared biology from batch-specific effects.
|
|
38
|
+
|
|
39
|
+
`BiDictionaryNMF` factorizes two expression matrices **X** and **Y** as
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
X ≈ W_shared @ H_X_shared + W_X @ H_X_private
|
|
43
|
+
Y ≈ W_shared @ H_Y_shared + W_Y @ H_Y_private
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
where **W_shared** captures biology common to both batches, while **W_X / W_Y**
|
|
47
|
+
absorb batch-specific (technical) variation. The model is implemented in
|
|
48
|
+
**PyTorch** and is fully differentiable.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Features
|
|
53
|
+
|
|
54
|
+
- 🔬 Shared + private dictionaries for clean cross-batch integration
|
|
55
|
+
- ⚡ Fully differentiable (PyTorch `nn.Module`) — drop-in optimizable component
|
|
56
|
+
- 💾 `save` / `load` for model persistence (training or deployment)
|
|
57
|
+
- 📊 `tqdm` progress bar during fitting
|
|
58
|
+
- 🧬 Gene-program utilities: `get_shared_compositions`, `get_shared_genes`
|
|
59
|
+
- 🎯 Supports `n_private=0` (degenerate single-dictionary mode, equivalent to plain NMF)
|
|
60
|
+
- 📦 Standard Python package, installable via `pip install .` or from PyPI
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Installation
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
pip install bidictnmf
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
From source (development mode):
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
git clone https://github.com/your-org/bidictnmf.git
|
|
74
|
+
cd bidictnmf
|
|
75
|
+
pip install -e .
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Requirements: Python ≥ 3.8, NumPy, SciPy, scikit-learn, PyTorch, tqdm.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Quick Start
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
import numpy as np
|
|
86
|
+
from bidictnmf import BiDictionaryNMF
|
|
87
|
+
|
|
88
|
+
# X, Y: (n_cells, n_genes) expression matrices for two batches
|
|
89
|
+
model = BiDictionaryNMF(
|
|
90
|
+
n_shared=20,
|
|
91
|
+
n_private=10,
|
|
92
|
+
lam_private=0.05,
|
|
93
|
+
lr=5e-4,
|
|
94
|
+
max_iter=300,
|
|
95
|
+
verbose=True, # shows tqdm progress bar
|
|
96
|
+
)
|
|
97
|
+
|
|
98
|
+
model.fit(X, Y)
|
|
99
|
+
|
|
100
|
+
# Shared compositions (biology common to X and Y)
|
|
101
|
+
H_X_s, H_Y_s = model.get_shared_compositions()
|
|
102
|
+
|
|
103
|
+
# Map new cells onto the learned dictionaries
|
|
104
|
+
H_new = model.transform(Z, batch='X')
|
|
105
|
+
|
|
106
|
+
# Inspect gene programs
|
|
107
|
+
top_genes = model.get_shared_genes(gene_names=gene_names, top_k=10)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Pure shared dictionary (`n_private=0`)
|
|
111
|
+
|
|
112
|
+
Setting `n_private=0` reduces the model to a single shared dictionary
|
|
113
|
+
(equivalent to plain NMF). The private dictionaries `W_X`, `W_Y` become
|
|
114
|
+
empty `(n_genes, 0)` tensors, the private-term regularization is
|
|
115
|
+
automatically zeroed, and `transform` returns `H` of shape
|
|
116
|
+
`(n_shared, n_cells)`. This is useful when you only care about shared
|
|
117
|
+
biology and want no batch-specific component:
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
model = BiDictionaryNMF(n_shared=20, n_private=0)
|
|
121
|
+
model.fit(X, Y)
|
|
122
|
+
|
|
123
|
+
H_X_s, H_Y_s = model.get_shared_compositions() # (n_shared, n_cells) each
|
|
124
|
+
H_new = model.transform(Z, batch='X') # shape (n_shared, n_cells)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Save / Load
|
|
128
|
+
|
|
129
|
+
```python
|
|
130
|
+
model.save("my_model.pt") # export
|
|
131
|
+
model2 = BiDictionaryNMF.load("my_model.pt") # import (returns a fitted model)
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`load` accepts a `map_location` argument to control the device:
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
model_cpu = BiDictionaryNMF.load("my_model.pt", map_location="cpu")
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## API
|
|
143
|
+
|
|
144
|
+
The class mirrors the original script's interface. Key methods:
|
|
145
|
+
|
|
146
|
+
| Method | Description |
|
|
147
|
+
|--------|-------------|
|
|
148
|
+
| `fit(X, Y)` | Fit the model to two `(n_cells, n_genes)` matrices |
|
|
149
|
+
| `transform(Z, batch)` | Project new data onto the dictionaries (fixed W) |
|
|
150
|
+
| `get_shared_compositions()` | Shared H for X and Y |
|
|
151
|
+
| `get_shared_genes(top_k, gene_names)` | Top genes per shared gene program |
|
|
152
|
+
| `save(path)` | Persist model, config and loss history |
|
|
153
|
+
| `load(path, map_location)` | Restore a fitted model (classmethod) |
|
|
154
|
+
| `n_private=0` | Degenerate mode: no private dictionary, equivalent to plain NMF |
|
|
155
|
+
|
|
156
|
+
Properties `W_shared_np`, `W_X_np`, `W_Y_np`, `H_X_np`, `H_Y_np` return
|
|
157
|
+
parameters as NumPy arrays.
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## License
|
|
162
|
+
|
|
163
|
+
MIT © BiDictionaryNMF Contributors.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# BiDictionaryNMF
|
|
2
|
+
|
|
3
|
+
> Differentiable **Bi-Dictionary Non-negative Matrix Factorization** for integrating
|
|
4
|
+
> two batches / datasets while separating shared biology from batch-specific effects.
|
|
5
|
+
|
|
6
|
+
`BiDictionaryNMF` factorizes two expression matrices **X** and **Y** as
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
X ≈ W_shared @ H_X_shared + W_X @ H_X_private
|
|
10
|
+
Y ≈ W_shared @ H_Y_shared + W_Y @ H_Y_private
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
where **W_shared** captures biology common to both batches, while **W_X / W_Y**
|
|
14
|
+
absorb batch-specific (technical) variation. The model is implemented in
|
|
15
|
+
**PyTorch** and is fully differentiable.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Features
|
|
20
|
+
|
|
21
|
+
- 🔬 Shared + private dictionaries for clean cross-batch integration
|
|
22
|
+
- ⚡ Fully differentiable (PyTorch `nn.Module`) — drop-in optimizable component
|
|
23
|
+
- 💾 `save` / `load` for model persistence (training or deployment)
|
|
24
|
+
- 📊 `tqdm` progress bar during fitting
|
|
25
|
+
- 🧬 Gene-program utilities: `get_shared_compositions`, `get_shared_genes`
|
|
26
|
+
- 🎯 Supports `n_private=0` (degenerate single-dictionary mode, equivalent to plain NMF)
|
|
27
|
+
- 📦 Standard Python package, installable via `pip install .` or from PyPI
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Installation
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pip install bidictnmf
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
From source (development mode):
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
git clone https://github.com/your-org/bidictnmf.git
|
|
41
|
+
cd bidictnmf
|
|
42
|
+
pip install -e .
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Requirements: Python ≥ 3.8, NumPy, SciPy, scikit-learn, PyTorch, tqdm.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Quick Start
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
import numpy as np
|
|
53
|
+
from bidictnmf import BiDictionaryNMF
|
|
54
|
+
|
|
55
|
+
# X, Y: (n_cells, n_genes) expression matrices for two batches
|
|
56
|
+
model = BiDictionaryNMF(
|
|
57
|
+
n_shared=20,
|
|
58
|
+
n_private=10,
|
|
59
|
+
lam_private=0.05,
|
|
60
|
+
lr=5e-4,
|
|
61
|
+
max_iter=300,
|
|
62
|
+
verbose=True, # shows tqdm progress bar
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
model.fit(X, Y)
|
|
66
|
+
|
|
67
|
+
# Shared compositions (biology common to X and Y)
|
|
68
|
+
H_X_s, H_Y_s = model.get_shared_compositions()
|
|
69
|
+
|
|
70
|
+
# Map new cells onto the learned dictionaries
|
|
71
|
+
H_new = model.transform(Z, batch='X')
|
|
72
|
+
|
|
73
|
+
# Inspect gene programs
|
|
74
|
+
top_genes = model.get_shared_genes(gene_names=gene_names, top_k=10)
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Pure shared dictionary (`n_private=0`)
|
|
78
|
+
|
|
79
|
+
Setting `n_private=0` reduces the model to a single shared dictionary
|
|
80
|
+
(equivalent to plain NMF). The private dictionaries `W_X`, `W_Y` become
|
|
81
|
+
empty `(n_genes, 0)` tensors, the private-term regularization is
|
|
82
|
+
automatically zeroed, and `transform` returns `H` of shape
|
|
83
|
+
`(n_shared, n_cells)`. This is useful when you only care about shared
|
|
84
|
+
biology and want no batch-specific component:
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
model = BiDictionaryNMF(n_shared=20, n_private=0)
|
|
88
|
+
model.fit(X, Y)
|
|
89
|
+
|
|
90
|
+
H_X_s, H_Y_s = model.get_shared_compositions() # (n_shared, n_cells) each
|
|
91
|
+
H_new = model.transform(Z, batch='X') # shape (n_shared, n_cells)
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Save / Load
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
model.save("my_model.pt") # export
|
|
98
|
+
model2 = BiDictionaryNMF.load("my_model.pt") # import (returns a fitted model)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
`load` accepts a `map_location` argument to control the device:
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
model_cpu = BiDictionaryNMF.load("my_model.pt", map_location="cpu")
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## API
|
|
110
|
+
|
|
111
|
+
The class mirrors the original script's interface. Key methods:
|
|
112
|
+
|
|
113
|
+
| Method | Description |
|
|
114
|
+
|--------|-------------|
|
|
115
|
+
| `fit(X, Y)` | Fit the model to two `(n_cells, n_genes)` matrices |
|
|
116
|
+
| `transform(Z, batch)` | Project new data onto the dictionaries (fixed W) |
|
|
117
|
+
| `get_shared_compositions()` | Shared H for X and Y |
|
|
118
|
+
| `get_shared_genes(top_k, gene_names)` | Top genes per shared gene program |
|
|
119
|
+
| `save(path)` | Persist model, config and loss history |
|
|
120
|
+
| `load(path, map_location)` | Restore a fitted model (classmethod) |
|
|
121
|
+
| `n_private=0` | Degenerate mode: no private dictionary, equivalent to plain NMF |
|
|
122
|
+
|
|
123
|
+
Properties `W_shared_np`, `W_X_np`, `W_Y_np`, `H_X_np`, `H_Y_np` return
|
|
124
|
+
parameters as NumPy arrays.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## License
|
|
129
|
+
|
|
130
|
+
MIT © BiDictionaryNMF Contributors.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
"""
|
|
2
|
+
BiDictionaryNMF
|
|
3
|
+
================
|
|
4
|
+
|
|
5
|
+
A PyTorch-based differentiable Non-negative Matrix Factorization model with
|
|
6
|
+
*bi-directional dictionaries* (shared + private gene programs), designed for
|
|
7
|
+
integrating two batches / datasets while separating shared biology from
|
|
8
|
+
batch-specific effects.
|
|
9
|
+
|
|
10
|
+
Example
|
|
11
|
+
-------
|
|
12
|
+
|
|
13
|
+
>>> from bidictnmf import BiDictionaryNMF
|
|
14
|
+
>>> import numpy as np
|
|
15
|
+
>>>
|
|
16
|
+
>>> model = BiDictionaryNMF(n_shared=20, n_private=10)
|
|
17
|
+
>>> model.fit(X, Y) # X, Y: (n_cells, n_genes)
|
|
18
|
+
>>> H_X_s, H_Y_s = model.get_shared_compositions()
|
|
19
|
+
>>> H_new = model.transform(Z, batch='X')
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from .model import BiDictionaryNMF
|
|
23
|
+
|
|
24
|
+
__version__ = "0.2.0"
|
|
25
|
+
|
|
26
|
+
__all__ = ["BiDictionaryNMF"]
|
|
@@ -0,0 +1,464 @@
|
|
|
1
|
+
import os
|
|
2
|
+
import warnings
|
|
3
|
+
import numpy as np
|
|
4
|
+
import torch
|
|
5
|
+
from sklearn.decomposition import PCA
|
|
6
|
+
from torch.optim import Adam
|
|
7
|
+
from torch.optim.lr_scheduler import ReduceLROnPlateau
|
|
8
|
+
|
|
9
|
+
try:
|
|
10
|
+
from tqdm.auto import tqdm
|
|
11
|
+
_HAS_TQDM = True
|
|
12
|
+
except ImportError: # pragma: no cover - optional dependency
|
|
13
|
+
tqdm = None
|
|
14
|
+
_HAS_TQDM = False
|
|
15
|
+
|
|
16
|
+
warnings.filterwarnings('ignore')
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class BiDictionaryNMF(torch.nn.Module):
|
|
20
|
+
"""
|
|
21
|
+
双字典 NMF(PyTorch 可微版本)
|
|
22
|
+
|
|
23
|
+
接口与 sklearn 风格保持一致:
|
|
24
|
+
model = BiDictionaryNMF(n_shared=20, n_private=10)
|
|
25
|
+
model.fit(X, Y)
|
|
26
|
+
H_X_s, H_Y_s = model.get_shared_compositions()
|
|
27
|
+
H_new = model.transform(Z, batch='X')
|
|
28
|
+
model.save('model.pt')
|
|
29
|
+
model2 = BiDictionaryNMF.load('model.pt')
|
|
30
|
+
|
|
31
|
+
Parameters
|
|
32
|
+
----------
|
|
33
|
+
n_shared : int
|
|
34
|
+
共享 GP 数量,必须 >= 1。
|
|
35
|
+
n_private : int
|
|
36
|
+
私有 GP 数量,允许为 0(退化为单一共享字典,等价于普通 NMF)。
|
|
37
|
+
lam_shared : float
|
|
38
|
+
W_shared 的 L1 正则(鼓励稀疏可解释)
|
|
39
|
+
lam_private : float
|
|
40
|
+
W_X, W_Y 的 L1 正则(把批次效应压进私有字典)。
|
|
41
|
+
当 n_private=0 时该项恒为 0,不会报错。
|
|
42
|
+
lr : float
|
|
43
|
+
Adam 学习率
|
|
44
|
+
max_iter : int
|
|
45
|
+
最大迭代
|
|
46
|
+
tol : float
|
|
47
|
+
早停阈值
|
|
48
|
+
device : str
|
|
49
|
+
'cuda' or 'cpu'
|
|
50
|
+
verbose : bool
|
|
51
|
+
是否显示 tqdm 进度条。False 则静默训练
|
|
52
|
+
"""
|
|
53
|
+
|
|
54
|
+
# 需要随模型一起保存/加载的配置项
|
|
55
|
+
_CONFIG_KEYS = (
|
|
56
|
+
'n_shared', 'n_private', 'lam_shared', 'lam_private',
|
|
57
|
+
'lr', 'max_iter', 'tol', 'device',
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
def __init__(self, n_shared=20, n_private=10,
|
|
61
|
+
lam_shared=0.0, lam_private=0.1,
|
|
62
|
+
lr=1e-3, max_iter=500, tol=1e-5,
|
|
63
|
+
device=None, verbose=True):
|
|
64
|
+
super().__init__()
|
|
65
|
+
|
|
66
|
+
if n_shared < 1:
|
|
67
|
+
raise ValueError(f"n_shared must be >= 1, got {n_shared}.")
|
|
68
|
+
if n_private < 0:
|
|
69
|
+
raise ValueError(f"n_private must be >= 0, got {n_private}.")
|
|
70
|
+
|
|
71
|
+
self.n_shared = n_shared
|
|
72
|
+
self.n_private = n_private
|
|
73
|
+
self.n_total = n_shared + n_private
|
|
74
|
+
self.lam_shared = lam_shared
|
|
75
|
+
self.lam_private = lam_private
|
|
76
|
+
self.lr = lr
|
|
77
|
+
self.max_iter = max_iter
|
|
78
|
+
self.tol = tol
|
|
79
|
+
self.verbose = verbose
|
|
80
|
+
|
|
81
|
+
if device is None:
|
|
82
|
+
self.device = 'cuda' if torch.cuda.is_available() else 'cpu'
|
|
83
|
+
else:
|
|
84
|
+
self.device = device
|
|
85
|
+
|
|
86
|
+
self.loss_history = []
|
|
87
|
+
self._fitted = False
|
|
88
|
+
|
|
89
|
+
# ==================== 内部工具 ====================
|
|
90
|
+
def _has_private(self):
|
|
91
|
+
"""是否有私有字典。n_private=0 时为 False,此时退化为单一共享字典。"""
|
|
92
|
+
return self.n_private > 0
|
|
93
|
+
|
|
94
|
+
def _build_W(self, batch):
|
|
95
|
+
"""
|
|
96
|
+
按 batch 组装完整字典 W。
|
|
97
|
+
|
|
98
|
+
- n_private > 0:返回 torch.cat([W_shared, W_X 或 W_Y], dim=1)
|
|
99
|
+
- n_private = 0:直接返回 W_shared(避免对形状 (g, 0) 的空张量做 cat)
|
|
100
|
+
|
|
101
|
+
返回形状:(n_genes, n_total)
|
|
102
|
+
"""
|
|
103
|
+
if not self._has_private():
|
|
104
|
+
return self.W_shared
|
|
105
|
+
if batch == 'X':
|
|
106
|
+
return torch.cat([self.W_shared, self.W_X], dim=1)
|
|
107
|
+
elif batch == 'Y':
|
|
108
|
+
return torch.cat([self.W_shared, self.W_Y], dim=1)
|
|
109
|
+
else:
|
|
110
|
+
raise ValueError("batch must be 'X' or 'Y'.")
|
|
111
|
+
|
|
112
|
+
def _private_norm(self):
|
|
113
|
+
"""私有字典 L1 范数;n_private=0 时返回 0。"""
|
|
114
|
+
if not self._has_private():
|
|
115
|
+
return torch.tensor(0.0, device=self.device)
|
|
116
|
+
return torch.sum(torch.abs(self.W_X)) + torch.sum(torch.abs(self.W_Y))
|
|
117
|
+
|
|
118
|
+
# ==================== 参数初始化 ====================
|
|
119
|
+
def _init_params(self, X, Y):
|
|
120
|
+
g = X.shape[1]
|
|
121
|
+
|
|
122
|
+
# ---- 共享字典 W_shared ----
|
|
123
|
+
XY = torch.cat([X, Y], dim=0).cpu().numpy()
|
|
124
|
+
pca = PCA(n_components=min(self.n_shared, XY.shape[0], XY.shape[1]))
|
|
125
|
+
pca.fit(XY)
|
|
126
|
+
W_s_np = np.abs(pca.components_.T[:, :self.n_shared])
|
|
127
|
+
if W_s_np.shape[1] < self.n_shared:
|
|
128
|
+
extra = np.abs(np.random.randn(g, self.n_shared - W_s_np.shape[1])) * 0.01
|
|
129
|
+
W_s_np = np.hstack([W_s_np, extra])
|
|
130
|
+
|
|
131
|
+
self.W_shared = torch.nn.Parameter(
|
|
132
|
+
torch.tensor(W_s_np, dtype=torch.float32, device=self.device))
|
|
133
|
+
|
|
134
|
+
# ---- 私有字典(n_private=0 时为形状 (g, 0) 的空张量)----
|
|
135
|
+
# scale 用 max(n_private, 1) 兜底,避免 n_private=0 时除以 0。
|
|
136
|
+
scale = float(torch.mean(X).item()) / max(self.n_private, 1) * 0.1
|
|
137
|
+
self.W_X = torch.nn.Parameter(
|
|
138
|
+
torch.abs(torch.randn(g, self.n_private, device=self.device)) * scale)
|
|
139
|
+
self.W_Y = torch.nn.Parameter(
|
|
140
|
+
torch.abs(torch.randn(g, self.n_private, device=self.device)) * scale)
|
|
141
|
+
|
|
142
|
+
# ---- H 初始化 ----
|
|
143
|
+
# 通过 _build_W 组装完整字典,n_private=0 时即为 W_shared 本身。
|
|
144
|
+
with torch.no_grad():
|
|
145
|
+
Wx = self._build_W('X') # (g, n_total)
|
|
146
|
+
Wy = self._build_W('Y')
|
|
147
|
+
|
|
148
|
+
# pinv @ X.T -> (n_total, n)
|
|
149
|
+
H_X_init = torch.relu(torch.linalg.pinv(Wx) @ X.T)
|
|
150
|
+
H_Y_init = torch.relu(torch.linalg.pinv(Wy) @ Y.T)
|
|
151
|
+
|
|
152
|
+
self.H_X = torch.nn.Parameter(H_X_init)
|
|
153
|
+
self.H_Y = torch.nn.Parameter(H_Y_init)
|
|
154
|
+
|
|
155
|
+
# ==================== Forward / Loss ====================
|
|
156
|
+
def _reconstruct(self, which='both'):
|
|
157
|
+
if which == 'X':
|
|
158
|
+
return self._build_W('X') @ self.H_X # (g, n_X)
|
|
159
|
+
elif which == 'Y':
|
|
160
|
+
return self._build_W('Y') @ self.H_Y # (g, n_Y)
|
|
161
|
+
else:
|
|
162
|
+
return (self._build_W('X') @ self.H_X,
|
|
163
|
+
self._build_W('Y') @ self.H_Y)
|
|
164
|
+
|
|
165
|
+
def _loss(self, X, Y):
|
|
166
|
+
recon_X, recon_Y = self._reconstruct('both')
|
|
167
|
+
|
|
168
|
+
loss_X = torch.sum((X.T - recon_X) ** 2)
|
|
169
|
+
loss_Y = torch.sum((Y.T - recon_Y) ** 2)
|
|
170
|
+
|
|
171
|
+
# 共享字典正则(始终存在)
|
|
172
|
+
reg_shared = self.lam_shared * torch.sum(torch.abs(self.W_shared))
|
|
173
|
+
# 私有字典正则;n_private=0 时该项恒为 0
|
|
174
|
+
reg_private = self.lam_private * self._private_norm()
|
|
175
|
+
|
|
176
|
+
total = loss_X + loss_Y + reg_shared + reg_private
|
|
177
|
+
return total, {'recon_X': loss_X, 'recon_Y': recon_Y}
|
|
178
|
+
|
|
179
|
+
# ==================== Fit ====================
|
|
180
|
+
def fit(self, X, Y):
|
|
181
|
+
"""
|
|
182
|
+
X : (n_X, n_genes) numpy array
|
|
183
|
+
Y : (n_Y, n_genes) numpy array
|
|
184
|
+
"""
|
|
185
|
+
if isinstance(X, np.ndarray):
|
|
186
|
+
X_t = torch.tensor(X, dtype=torch.float32, device=self.device)
|
|
187
|
+
Y_t = torch.tensor(Y, dtype=torch.float32, device=self.device)
|
|
188
|
+
else:
|
|
189
|
+
X_t, Y_t = X, Y
|
|
190
|
+
|
|
191
|
+
self._init_params(X_t, Y_t)
|
|
192
|
+
|
|
193
|
+
optimizer = Adam(self.parameters(), lr=self.lr, betas=(0.9, 0.999))
|
|
194
|
+
scheduler = ReduceLROnPlateau(optimizer, mode='min', factor=0.5,
|
|
195
|
+
patience=30, min_lr=1e-6)
|
|
196
|
+
|
|
197
|
+
self.loss_history = []
|
|
198
|
+
prev_loss = float('inf')
|
|
199
|
+
|
|
200
|
+
iterator = range(self.max_iter)
|
|
201
|
+
if self.verbose:
|
|
202
|
+
if not _HAS_TQDM:
|
|
203
|
+
warnings.warn(
|
|
204
|
+
"verbose=True but tqdm is not installed. "
|
|
205
|
+
"Install with `pip install tqdm` for a progress bar.",
|
|
206
|
+
RuntimeWarning)
|
|
207
|
+
iterator = iterator
|
|
208
|
+
else:
|
|
209
|
+
iterator = tqdm(
|
|
210
|
+
iterator, desc='BiDictionaryNMF',
|
|
211
|
+
unit='iter', leave=True,
|
|
212
|
+
dynamic_ncols=True)
|
|
213
|
+
|
|
214
|
+
for it in iterator:
|
|
215
|
+
optimizer.zero_grad()
|
|
216
|
+
|
|
217
|
+
total_loss, details = self._loss(X_t, Y_t)
|
|
218
|
+
total_loss.backward()
|
|
219
|
+
optimizer.step()
|
|
220
|
+
|
|
221
|
+
with torch.no_grad():
|
|
222
|
+
self.W_shared.clamp_(min=0)
|
|
223
|
+
if self._has_private():
|
|
224
|
+
self.W_X.clamp_(min=0)
|
|
225
|
+
self.W_Y.clamp_(min=0)
|
|
226
|
+
self.H_X.clamp_(min=0)
|
|
227
|
+
self.H_Y.clamp_(min=0)
|
|
228
|
+
|
|
229
|
+
loss_val = total_loss.item()
|
|
230
|
+
self.loss_history.append(loss_val)
|
|
231
|
+
scheduler.step(loss_val)
|
|
232
|
+
|
|
233
|
+
if self.verbose and _HAS_TQDM:
|
|
234
|
+
iterator.set_postfix(
|
|
235
|
+
loss=f"{loss_val:.4e}",
|
|
236
|
+
X=f"{details['recon_X'].item():.2e}",
|
|
237
|
+
Y=f"{details['recon_Y'].item():.2e}",
|
|
238
|
+
lr=f"{optimizer.param_groups[0]['lr']:.1e}")
|
|
239
|
+
|
|
240
|
+
rel_improve = (prev_loss - loss_val) / max(abs(prev_loss), 1e-10)
|
|
241
|
+
if 0 < rel_improve < self.tol:
|
|
242
|
+
if self.verbose:
|
|
243
|
+
iterator.write(f"Early stop at iter {it} "
|
|
244
|
+
f"(rel_improve={rel_improve:.2e})")
|
|
245
|
+
break
|
|
246
|
+
prev_loss = loss_val
|
|
247
|
+
|
|
248
|
+
self._fitted = True
|
|
249
|
+
if self.verbose and _HAS_TQDM:
|
|
250
|
+
private_msg = (f"||W_X||_1={self.W_X.abs().sum():.1f} "
|
|
251
|
+
f"||W_Y||_1={self.W_Y.abs().sum():.1f}")
|
|
252
|
+
iterator.write(
|
|
253
|
+
f"Done. W_shared={tuple(self.W_shared.shape)} | "
|
|
254
|
+
f"{private_msg}")
|
|
255
|
+
elif self.verbose:
|
|
256
|
+
print("Done.")
|
|
257
|
+
print(f" W_shared: {self.W_shared.shape} | "
|
|
258
|
+
f"||W_X||_1={self.W_X.abs().sum():.1f} "
|
|
259
|
+
f"||W_Y||_1={self.W_Y.abs().sum():.1f}")
|
|
260
|
+
|
|
261
|
+
return self
|
|
262
|
+
|
|
263
|
+
# ==================== Transform ====================
|
|
264
|
+
def transform(self, Z, batch='X'):
|
|
265
|
+
"""
|
|
266
|
+
对新数据 Z 计算 compositions(不更新 W)
|
|
267
|
+
|
|
268
|
+
Parameters
|
|
269
|
+
----------
|
|
270
|
+
Z : (n_cells, n_genes) numpy array
|
|
271
|
+
batch : 'X' or 'Y'
|
|
272
|
+
|
|
273
|
+
Returns
|
|
274
|
+
-------
|
|
275
|
+
H : (n_total, n_cells) numpy array
|
|
276
|
+
"""
|
|
277
|
+
if not self._fitted:
|
|
278
|
+
raise ValueError("Model not fitted yet.")
|
|
279
|
+
|
|
280
|
+
if isinstance(Z, np.ndarray):
|
|
281
|
+
Z_t = torch.tensor(Z, dtype=torch.float32, device=self.device)
|
|
282
|
+
else:
|
|
283
|
+
Z_t = Z
|
|
284
|
+
|
|
285
|
+
with torch.no_grad():
|
|
286
|
+
W = self._build_W(batch)
|
|
287
|
+
|
|
288
|
+
H = torch.relu(torch.linalg.pinv(W) @ Z_t.T).clone().detach()
|
|
289
|
+
H.requires_grad_(True)
|
|
290
|
+
opt = Adam([H], lr=1e-2)
|
|
291
|
+
|
|
292
|
+
for _ in range(200):
|
|
293
|
+
opt.zero_grad()
|
|
294
|
+
recon = W @ H
|
|
295
|
+
loss = torch.sum((Z_t.T - recon) ** 2)
|
|
296
|
+
loss.backward()
|
|
297
|
+
opt.step()
|
|
298
|
+
H.clamp_(min=0)
|
|
299
|
+
|
|
300
|
+
return H.cpu().numpy()
|
|
301
|
+
|
|
302
|
+
# ==================== 获取共享部分 ====================
|
|
303
|
+
def get_shared_compositions(self):
|
|
304
|
+
"""
|
|
305
|
+
Returns
|
|
306
|
+
-------
|
|
307
|
+
H_X_shared : (n_shared, n_X) numpy
|
|
308
|
+
H_Y_shared : (n_shared, n_Y) numpy
|
|
309
|
+
"""
|
|
310
|
+
if not self._fitted:
|
|
311
|
+
raise ValueError("Model not fitted yet.")
|
|
312
|
+
|
|
313
|
+
with torch.no_grad():
|
|
314
|
+
H_X_s = self.H_X[:self.n_shared, :].cpu().numpy()
|
|
315
|
+
H_Y_s = self.H_Y[:self.n_shared, :].cpu().numpy()
|
|
316
|
+
return H_X_s, H_Y_s
|
|
317
|
+
|
|
318
|
+
def get_shared_genes(self, gene_names=None, top_k=10):
|
|
319
|
+
"""
|
|
320
|
+
返回每个共享 GP 的 top 基因索引或名称
|
|
321
|
+
"""
|
|
322
|
+
if not self._fitted:
|
|
323
|
+
raise ValueError("Model not fitted yet.")
|
|
324
|
+
|
|
325
|
+
with torch.no_grad():
|
|
326
|
+
W_s = self.W_shared.cpu().numpy()
|
|
327
|
+
|
|
328
|
+
results = []
|
|
329
|
+
for k in range(self.n_shared):
|
|
330
|
+
idx = np.argsort(W_s[:, k])[::-1][:top_k]
|
|
331
|
+
if gene_names is not None:
|
|
332
|
+
results.append([gene_names[i] for i in idx])
|
|
333
|
+
else:
|
|
334
|
+
results.append(idx)
|
|
335
|
+
return results
|
|
336
|
+
|
|
337
|
+
# ==================== 模型保存 / 加载 ====================
|
|
338
|
+
def save(self, path, save_optimizer=False):
|
|
339
|
+
"""
|
|
340
|
+
保存模型到文件。
|
|
341
|
+
|
|
342
|
+
保存内容:模型配置、学习到的参数(W_shared/W_X/W_Y/H_X/H_Y)、
|
|
343
|
+
loss 历史、拟合状态。默认不保存优化器状态(纯推理/部署用);
|
|
344
|
+
如需断点续训可设置 ``save_optimizer=True``(需在 fit 中额外保留
|
|
345
|
+
optimizer 引用,当前实现不默认保存)。
|
|
346
|
+
|
|
347
|
+
Parameters
|
|
348
|
+
----------
|
|
349
|
+
path : str
|
|
350
|
+
输出文件路径,建议以 ``.pt`` 结尾。
|
|
351
|
+
save_optimizer : bool
|
|
352
|
+
是否保存优化器状态(默认 False)。
|
|
353
|
+
"""
|
|
354
|
+
config = {k: getattr(self, k) for k in self._CONFIG_KEYS}
|
|
355
|
+
|
|
356
|
+
state = {
|
|
357
|
+
'config': config,
|
|
358
|
+
'model_state_dict': self.state_dict(),
|
|
359
|
+
'loss_history': self.loss_history,
|
|
360
|
+
'fitted': self._fitted,
|
|
361
|
+
'torch_version': torch.__version__,
|
|
362
|
+
}
|
|
363
|
+
if save_optimizer:
|
|
364
|
+
warnings.warn(
|
|
365
|
+
"save_optimizer=True but no optimizer reference is kept. "
|
|
366
|
+
"Ignoring.", RuntimeWarning)
|
|
367
|
+
|
|
368
|
+
os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
|
|
369
|
+
torch.save(state, path)
|
|
370
|
+
|
|
371
|
+
@classmethod
|
|
372
|
+
def load(cls, path, map_location=None, strict=True):
|
|
373
|
+
"""
|
|
374
|
+
从文件加载模型。
|
|
375
|
+
|
|
376
|
+
Parameters
|
|
377
|
+
----------
|
|
378
|
+
path : str
|
|
379
|
+
模型文件路径。
|
|
380
|
+
map_location : str or torch.device, optional
|
|
381
|
+
指定加载到的设备,例如 ``'cpu'``。为 None 时按保存时的 device
|
|
382
|
+
字段选择设备。
|
|
383
|
+
strict : bool
|
|
384
|
+
是否严格匹配 state_dict 的 keys(默认 True)。
|
|
385
|
+
|
|
386
|
+
Returns
|
|
387
|
+
-------
|
|
388
|
+
BiDictionaryNMF
|
|
389
|
+
已加载并切换到对应设备的模型实例。
|
|
390
|
+
"""
|
|
391
|
+
checkpoint = torch.load(path, map_location=map_location)
|
|
392
|
+
|
|
393
|
+
config = checkpoint['config']
|
|
394
|
+
device = config.get('device', None)
|
|
395
|
+
if map_location is not None:
|
|
396
|
+
device = map_location
|
|
397
|
+
|
|
398
|
+
model = cls(**config)
|
|
399
|
+
if device is not None:
|
|
400
|
+
model.device = device
|
|
401
|
+
|
|
402
|
+
# 重新构建参数容器:从 state_dict 中读出真实形状,用零张量占位,
|
|
403
|
+
# 随后由 load_state_dict 填入实际数值。
|
|
404
|
+
state_dict = checkpoint['model_state_dict']
|
|
405
|
+
g, _n_shared = state_dict['W_shared'].shape
|
|
406
|
+
n_X_samples = state_dict['H_X'].shape[1]
|
|
407
|
+
n_Y_samples = state_dict['H_Y'].shape[1]
|
|
408
|
+
|
|
409
|
+
if _n_shared != model.n_shared:
|
|
410
|
+
raise ValueError(
|
|
411
|
+
f"Saved W_shared has {_n_shared} columns but config "
|
|
412
|
+
f"n_shared={model.n_shared}.")
|
|
413
|
+
|
|
414
|
+
# 行数(基因数)与 H 的第一维(= n_total)必须自洽。
|
|
415
|
+
# 注意:n_private=0 时 W_X / W_Y 形状为 (g, 0),需单独按维度数判断。
|
|
416
|
+
def _cols(t):
|
|
417
|
+
return t.shape[1] if t.ndim >= 2 else t.shape[0]
|
|
418
|
+
|
|
419
|
+
assert _cols(state_dict['W_X']) == model.n_private
|
|
420
|
+
assert _cols(state_dict['W_Y']) == model.n_private
|
|
421
|
+
assert state_dict['H_X'].shape[0] == model.n_total
|
|
422
|
+
assert state_dict['H_Y'].shape[0] == model.n_total
|
|
423
|
+
|
|
424
|
+
model.W_shared = torch.nn.Parameter(
|
|
425
|
+
torch.zeros(g, model.n_shared, device=model.device))
|
|
426
|
+
model.W_X = torch.nn.Parameter(
|
|
427
|
+
torch.zeros(g, model.n_private, device=model.device))
|
|
428
|
+
model.W_Y = torch.nn.Parameter(
|
|
429
|
+
torch.zeros(g, model.n_private, device=model.device))
|
|
430
|
+
model.H_X = torch.nn.Parameter(
|
|
431
|
+
torch.zeros(model.n_total, n_X_samples, device=model.device))
|
|
432
|
+
model.H_Y = torch.nn.Parameter(
|
|
433
|
+
torch.zeros(model.n_total, n_Y_samples, device=model.device))
|
|
434
|
+
|
|
435
|
+
model.load_state_dict(state_dict, strict=strict)
|
|
436
|
+
|
|
437
|
+
model.loss_history = checkpoint.get('loss_history', [])
|
|
438
|
+
model._fitted = checkpoint.get('fitted', True)
|
|
439
|
+
|
|
440
|
+
if device is not None:
|
|
441
|
+
model.to(device)
|
|
442
|
+
|
|
443
|
+
return model
|
|
444
|
+
|
|
445
|
+
# ==================== 属性访问 ====================
|
|
446
|
+
@property
|
|
447
|
+
def W_shared_np(self):
|
|
448
|
+
return self.W_shared.detach().cpu().numpy()
|
|
449
|
+
|
|
450
|
+
@property
|
|
451
|
+
def W_X_np(self):
|
|
452
|
+
return self.W_X.detach().cpu().numpy()
|
|
453
|
+
|
|
454
|
+
@property
|
|
455
|
+
def W_Y_np(self):
|
|
456
|
+
return self.W_Y.detach().cpu().numpy()
|
|
457
|
+
|
|
458
|
+
@property
|
|
459
|
+
def H_X_np(self):
|
|
460
|
+
return self.H_X.detach().cpu().numpy()
|
|
461
|
+
|
|
462
|
+
@property
|
|
463
|
+
def H_Y_np(self):
|
|
464
|
+
return self.H_Y.detach().cpu().numpy()
|
|
File without changes
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: bidictnmf
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Differentiable Bi-Dictionary Non-negative Matrix Factorization for cross-batch gene-program integration.
|
|
5
|
+
Author: BiDictionaryNMF Contributors
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/ZengFLab/bidictnmf
|
|
8
|
+
Project-URL: Repository, https://github.com/ZengFLab/bidictnmf
|
|
9
|
+
Project-URL: Issues, https://github.com/ZengFLab/bidictnmf/issues
|
|
10
|
+
Keywords: nmf,non-negative-matrix-factorization,single-cell,batch-integration,pytorch,gene-programs,bioinformatics
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
19
|
+
Requires-Python: >=3.8
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: numpy>=1.19
|
|
23
|
+
Requires-Dist: scipy>=1.5
|
|
24
|
+
Requires-Dist: scikit-learn>=0.24
|
|
25
|
+
Requires-Dist: torch>=1.10
|
|
26
|
+
Requires-Dist: tqdm>=4.0
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: pytest>=6.0; extra == "dev"
|
|
29
|
+
Requires-Dist: matplotlib>=3.0; extra == "dev"
|
|
30
|
+
Provides-Extra: docs
|
|
31
|
+
Requires-Dist: sphinx>=4.0; extra == "docs"
|
|
32
|
+
Dynamic: license-file
|
|
33
|
+
|
|
34
|
+
# BiDictionaryNMF
|
|
35
|
+
|
|
36
|
+
> Differentiable **Bi-Dictionary Non-negative Matrix Factorization** for integrating
|
|
37
|
+
> two batches / datasets while separating shared biology from batch-specific effects.
|
|
38
|
+
|
|
39
|
+
`BiDictionaryNMF` factorizes two expression matrices **X** and **Y** as
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
X ≈ W_shared @ H_X_shared + W_X @ H_X_private
|
|
43
|
+
Y ≈ W_shared @ H_Y_shared + W_Y @ H_Y_private
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
where **W_shared** captures biology common to both batches, while **W_X / W_Y**
|
|
47
|
+
absorb batch-specific (technical) variation. The model is implemented in
|
|
48
|
+
**PyTorch** and is fully differentiable.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Features
|
|
53
|
+
|
|
54
|
+
- 🔬 Shared + private dictionaries for clean cross-batch integration
|
|
55
|
+
- ⚡ Fully differentiable (PyTorch `nn.Module`) — drop-in optimizable component
|
|
56
|
+
- 💾 `save` / `load` for model persistence (training or deployment)
|
|
57
|
+
- 📊 `tqdm` progress bar during fitting
|
|
58
|
+
- 🧬 Gene-program utilities: `get_shared_compositions`, `get_shared_genes`
|
|
59
|
+
- 🎯 Supports `n_private=0` (degenerate single-dictionary mode, equivalent to plain NMF)
|
|
60
|
+
- 📦 Standard Python package, installable via `pip install .` or from PyPI
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Installation
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
pip install bidictnmf
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
From source (development mode):
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
git clone https://github.com/your-org/bidictnmf.git
|
|
74
|
+
cd bidictnmf
|
|
75
|
+
pip install -e .
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Requirements: Python ≥ 3.8, NumPy, SciPy, scikit-learn, PyTorch, tqdm.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Quick Start
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
import numpy as np
|
|
86
|
+
from bidictnmf import BiDictionaryNMF
|
|
87
|
+
|
|
88
|
+
# X, Y: (n_cells, n_genes) expression matrices for two batches
|
|
89
|
+
model = BiDictionaryNMF(
|
|
90
|
+
n_shared=20,
|
|
91
|
+
n_private=10,
|
|
92
|
+
lam_private=0.05,
|
|
93
|
+
lr=5e-4,
|
|
94
|
+
max_iter=300,
|
|
95
|
+
verbose=True, # shows tqdm progress bar
|
|
96
|
+
)
|
|
97
|
+
|
|
98
|
+
model.fit(X, Y)
|
|
99
|
+
|
|
100
|
+
# Shared compositions (biology common to X and Y)
|
|
101
|
+
H_X_s, H_Y_s = model.get_shared_compositions()
|
|
102
|
+
|
|
103
|
+
# Map new cells onto the learned dictionaries
|
|
104
|
+
H_new = model.transform(Z, batch='X')
|
|
105
|
+
|
|
106
|
+
# Inspect gene programs
|
|
107
|
+
top_genes = model.get_shared_genes(gene_names=gene_names, top_k=10)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Pure shared dictionary (`n_private=0`)
|
|
111
|
+
|
|
112
|
+
Setting `n_private=0` reduces the model to a single shared dictionary
|
|
113
|
+
(equivalent to plain NMF). The private dictionaries `W_X`, `W_Y` become
|
|
114
|
+
empty `(n_genes, 0)` tensors, the private-term regularization is
|
|
115
|
+
automatically zeroed, and `transform` returns `H` of shape
|
|
116
|
+
`(n_shared, n_cells)`. This is useful when you only care about shared
|
|
117
|
+
biology and want no batch-specific component:
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
model = BiDictionaryNMF(n_shared=20, n_private=0)
|
|
121
|
+
model.fit(X, Y)
|
|
122
|
+
|
|
123
|
+
H_X_s, H_Y_s = model.get_shared_compositions() # (n_shared, n_cells) each
|
|
124
|
+
H_new = model.transform(Z, batch='X') # shape (n_shared, n_cells)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Save / Load
|
|
128
|
+
|
|
129
|
+
```python
|
|
130
|
+
model.save("my_model.pt") # export
|
|
131
|
+
model2 = BiDictionaryNMF.load("my_model.pt") # import (returns a fitted model)
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`load` accepts a `map_location` argument to control the device:
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
model_cpu = BiDictionaryNMF.load("my_model.pt", map_location="cpu")
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## API
|
|
143
|
+
|
|
144
|
+
The class mirrors the original script's interface. Key methods:
|
|
145
|
+
|
|
146
|
+
| Method | Description |
|
|
147
|
+
|--------|-------------|
|
|
148
|
+
| `fit(X, Y)` | Fit the model to two `(n_cells, n_genes)` matrices |
|
|
149
|
+
| `transform(Z, batch)` | Project new data onto the dictionaries (fixed W) |
|
|
150
|
+
| `get_shared_compositions()` | Shared H for X and Y |
|
|
151
|
+
| `get_shared_genes(top_k, gene_names)` | Top genes per shared gene program |
|
|
152
|
+
| `save(path)` | Persist model, config and loss history |
|
|
153
|
+
| `load(path, map_location)` | Restore a fitted model (classmethod) |
|
|
154
|
+
| `n_private=0` | Degenerate mode: no private dictionary, equivalent to plain NMF |
|
|
155
|
+
|
|
156
|
+
Properties `W_shared_np`, `W_X_np`, `W_Y_np`, `H_X_np`, `H_Y_np` return
|
|
157
|
+
parameters as NumPy arrays.
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## License
|
|
162
|
+
|
|
163
|
+
MIT © BiDictionaryNMF Contributors.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
setup.cfg
|
|
5
|
+
setup.py
|
|
6
|
+
bidictnmf/__init__.py
|
|
7
|
+
bidictnmf/model.py
|
|
8
|
+
bidictnmf/py.typed
|
|
9
|
+
bidictnmf.egg-info/PKG-INFO
|
|
10
|
+
bidictnmf.egg-info/SOURCES.txt
|
|
11
|
+
bidictnmf.egg-info/dependency_links.txt
|
|
12
|
+
bidictnmf.egg-info/requires.txt
|
|
13
|
+
bidictnmf.egg-info/top_level.txt
|
|
14
|
+
tests/test_bidictnmf.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
bidictnmf
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "bidictnmf"
|
|
7
|
+
version = "0.2.0"
|
|
8
|
+
description = "Differentiable Bi-Dictionary Non-negative Matrix Factorization for cross-batch gene-program integration."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = {text = "MIT"}
|
|
11
|
+
authors = [
|
|
12
|
+
{name = "BiDictionaryNMF Contributors"}
|
|
13
|
+
]
|
|
14
|
+
keywords = [
|
|
15
|
+
"nmf", "non-negative-matrix-factorization", "single-cell",
|
|
16
|
+
"batch-integration", "pytorch", "gene-programs", "bioinformatics"
|
|
17
|
+
]
|
|
18
|
+
classifiers = [
|
|
19
|
+
"Development Status :: 4 - Beta",
|
|
20
|
+
"Intended Audience :: Science/Research",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3.8",
|
|
23
|
+
"Programming Language :: Python :: 3.9",
|
|
24
|
+
"Programming Language :: Python :: 3.10",
|
|
25
|
+
"Programming Language :: Python :: 3.11",
|
|
26
|
+
"Topic :: Scientific/Engineering :: Bio-Informatics",
|
|
27
|
+
]
|
|
28
|
+
requires-python = ">=3.8"
|
|
29
|
+
dependencies = [
|
|
30
|
+
"numpy>=1.19",
|
|
31
|
+
"scipy>=1.5",
|
|
32
|
+
"scikit-learn>=0.24",
|
|
33
|
+
"torch>=1.10",
|
|
34
|
+
"tqdm>=4.0",
|
|
35
|
+
]
|
|
36
|
+
|
|
37
|
+
[project.optional-dependencies]
|
|
38
|
+
dev = [
|
|
39
|
+
"pytest>=6.0",
|
|
40
|
+
"matplotlib>=3.0",
|
|
41
|
+
]
|
|
42
|
+
docs = [
|
|
43
|
+
"sphinx>=4.0",
|
|
44
|
+
]
|
|
45
|
+
|
|
46
|
+
[project.urls]
|
|
47
|
+
Homepage = "https://github.com/ZengFLab/bidictnmf"
|
|
48
|
+
Repository = "https://github.com/ZengFLab/bidictnmf"
|
|
49
|
+
Issues = "https://github.com/ZengFLab/bidictnmf/issues"
|
|
50
|
+
|
|
51
|
+
[tool.setuptools.packages.find]
|
|
52
|
+
include = ["bidictnmf*"]
|
|
53
|
+
exclude = ["tests*", "examples*"]
|
|
54
|
+
|
|
55
|
+
[tool.setuptools.package-data]
|
|
56
|
+
bidictnmf = ["py.typed"]
|
bidictnmf-0.2.0/setup.py
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import os
|
|
2
|
+
import numpy as np
|
|
3
|
+
import pytest
|
|
4
|
+
|
|
5
|
+
from bidictnmf import BiDictionaryNMF
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
@pytest.fixture(scope="module")
|
|
9
|
+
def data():
|
|
10
|
+
np.random.seed(0)
|
|
11
|
+
n_genes, n_shared, n_private = 200, 6, 3
|
|
12
|
+
n_X, n_Y = 60, 50
|
|
13
|
+
|
|
14
|
+
W_true = np.abs(np.random.randn(n_genes, n_shared))
|
|
15
|
+
W_true /= np.linalg.norm(W_true, axis=0, keepdims=True)
|
|
16
|
+
Wx = np.abs(np.random.randn(n_genes, n_private)) * 0.5
|
|
17
|
+
Wy = np.abs(np.random.randn(n_genes, n_private)) * 0.5
|
|
18
|
+
|
|
19
|
+
Hx = np.abs(np.random.randn(n_shared + n_private, n_X))
|
|
20
|
+
Hy = np.abs(np.random.randn(n_shared + n_private, n_Y))
|
|
21
|
+
|
|
22
|
+
X = (W_true @ Hx[:n_shared] + Wx @ Hx[n_shared:]
|
|
23
|
+
+ 0.1 * np.random.randn(n_genes, n_X)).T
|
|
24
|
+
Y = (W_true @ Hy[:n_shared] + Wy @ Hy[n_shared:]
|
|
25
|
+
+ 0.1 * np.random.randn(n_genes, n_Y)).T
|
|
26
|
+
return X, Y, n_shared, n_private, n_X, n_Y
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def test_fit_runs(data):
|
|
30
|
+
X, Y, n_shared, n_private, *_ = data
|
|
31
|
+
model = BiDictionaryNMF(n_shared=n_shared, n_private=n_private,
|
|
32
|
+
max_iter=20, verbose=False)
|
|
33
|
+
model.fit(X, Y)
|
|
34
|
+
assert model._fitted
|
|
35
|
+
assert len(model.loss_history) > 0
|
|
36
|
+
# loss should be finite and generally decreasing
|
|
37
|
+
assert np.isfinite(model.loss_history[-1])
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def test_shared_compositions_shape(data):
|
|
41
|
+
X, Y, n_shared, n_private, n_X, n_Y = data
|
|
42
|
+
model = BiDictionaryNMF(n_shared=n_shared, n_private=n_private,
|
|
43
|
+
max_iter=20, verbose=False)
|
|
44
|
+
model.fit(X, Y)
|
|
45
|
+
HX, HY = model.get_shared_compositions()
|
|
46
|
+
assert HX.shape == (n_shared, n_X)
|
|
47
|
+
assert HY.shape == (n_shared, n_Y)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def test_transform(data):
|
|
51
|
+
X, Y, n_shared, n_private, n_X, n_Y = data
|
|
52
|
+
model = BiDictionaryNMF(n_shared=n_shared, n_private=n_private,
|
|
53
|
+
max_iter=20, verbose=False)
|
|
54
|
+
model.fit(X, Y)
|
|
55
|
+
Z = X[:10]
|
|
56
|
+
H = model.transform(Z, batch='X')
|
|
57
|
+
assert H.shape[0] == n_shared + n_private
|
|
58
|
+
assert H.shape[1] == Z.shape[0]
|
|
59
|
+
assert np.all(H >= 0)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def test_save_load_roundtrip(data, tmp_path):
|
|
63
|
+
X, Y, n_shared, n_private, n_X, n_Y = data
|
|
64
|
+
path = str(tmp_path / "model.pt")
|
|
65
|
+
|
|
66
|
+
m1 = BiDictionaryNMF(n_shared=n_shared, n_private=n_private,
|
|
67
|
+
max_iter=20, verbose=False)
|
|
68
|
+
m1.fit(X, Y)
|
|
69
|
+
W1 = m1.W_shared_np.copy()
|
|
70
|
+
HX1, HY1 = m1.get_shared_compositions()
|
|
71
|
+
|
|
72
|
+
m1.save(path)
|
|
73
|
+
assert os.path.exists(path)
|
|
74
|
+
|
|
75
|
+
m2 = BiDictionaryNMF.load(path)
|
|
76
|
+
assert m2._fitted
|
|
77
|
+
assert m2.n_shared == n_shared and m2.n_private == n_private
|
|
78
|
+
np.testing.assert_allclose(m2.W_shared_np, W1, atol=1e-6)
|
|
79
|
+
HX2, HY2 = m2.get_shared_compositions()
|
|
80
|
+
np.testing.assert_allclose(HX2, HX1, atol=1e-6)
|
|
81
|
+
np.testing.assert_allclose(HY2, HY1, atol=1e-6)
|
|
82
|
+
|
|
83
|
+
# transform still works after reload
|
|
84
|
+
H = m2.transform(X[:5], batch='X')
|
|
85
|
+
assert H.shape == (n_shared + n_private, 5)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def test_properties(data):
|
|
89
|
+
X, Y, n_shared, n_private, *_ = data
|
|
90
|
+
model = BiDictionaryNMF(n_shared=n_shared, n_private=n_private,
|
|
91
|
+
max_iter=10, verbose=False)
|
|
92
|
+
model.fit(X, Y)
|
|
93
|
+
for attr in ("W_shared_np", "W_X_np", "W_Y_np", "H_X_np", "H_Y_np"):
|
|
94
|
+
assert getattr(model, attr).ndim >= 1
|