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.
@@ -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.
@@ -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,12 @@
1
+ numpy>=1.19
2
+ scipy>=1.5
3
+ scikit-learn>=0.24
4
+ torch>=1.10
5
+ tqdm>=4.0
6
+
7
+ [dev]
8
+ pytest>=6.0
9
+ matplotlib>=3.0
10
+
11
+ [docs]
12
+ sphinx>=4.0
@@ -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"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,2 @@
1
+ from setuptools import setup
2
+ setup()
@@ -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