scnmf 0.1.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.
- scnmf-0.1.0/PKG-INFO +142 -0
- scnmf-0.1.0/README.md +109 -0
- scnmf-0.1.0/docs/index.md +27 -0
- scnmf-0.1.0/docs/tutorial.md +1 -0
- scnmf-0.1.0/examples/basic_usage.py +54 -0
- scnmf-0.1.0/pyproject.toml +62 -0
- scnmf-0.1.0/src/scnmf/__init__.py +29 -0
- scnmf-0.1.0/src/scnmf/_version.py +24 -0
- scnmf-0.1.0/src/scnmf/cli.py +163 -0
- scnmf-0.1.0/src/scnmf/config.py +102 -0
- scnmf-0.1.0/src/scnmf/data/anndata_io.py +167 -0
- scnmf-0.1.0/src/scnmf/data/batch_sampler.py +171 -0
- scnmf-0.1.0/src/scnmf/data/sparse_csr.py +141 -0
- scnmf-0.1.0/src/scnmf/evaluation/batch_metrics.py +82 -0
- scnmf-0.1.0/src/scnmf/evaluation/reconstruction.py +26 -0
- scnmf-0.1.0/src/scnmf/models/cluster_head.py +94 -0
- scnmf-0.1.0/src/scnmf/models/conditional_nmf.py +364 -0
- scnmf-0.1.0/src/scnmf/models/factors.py +358 -0
- scnmf-0.1.0/src/scnmf/models/likelihoods.py +70 -0
- scnmf-0.1.0/src/scnmf/training/logging.py +97 -0
- scnmf-0.1.0/src/scnmf/training/losses.py +83 -0
- scnmf-0.1.0/src/scnmf/training/trainer.py +309 -0
- scnmf-0.1.0/tests/integration/test_end_to_end.py +90 -0
- scnmf-0.1.0/tests/unit/test_core_nopytorch.py +144 -0
- scnmf-0.1.0/tests/unit/test_model.py +144 -0
- scnmf-0.1.0/tests/unit/test_sparse_sampling.py +70 -0
scnmf-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: scnmf
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Sparse conditional joint NMF for single-cell RNA-seq integration, dimensionality reduction, and interpretable metagene discovery.
|
|
5
|
+
Project-URL: Homepage, https://github.com/ZengFLab/scnmf-py
|
|
6
|
+
Project-URL: Issues, https://github.com/ZengFLab/scnmf-py/issues
|
|
7
|
+
Author: SCNMF Developers
|
|
8
|
+
License: Apache-2.0
|
|
9
|
+
Keywords: AnnData,NMF,PyTorch,batch-correction,integration,single-cell
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Intended Audience :: Science/Research
|
|
12
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
15
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
16
|
+
Requires-Python: >=3.10
|
|
17
|
+
Requires-Dist: numpy>=1.23
|
|
18
|
+
Requires-Dist: scipy>=1.10
|
|
19
|
+
Requires-Dist: torch>=2.0
|
|
20
|
+
Provides-Extra: anndata
|
|
21
|
+
Requires-Dist: anndata>=0.10; extra == 'anndata'
|
|
22
|
+
Provides-Extra: dev
|
|
23
|
+
Requires-Dist: anndata>=0.10; extra == 'dev'
|
|
24
|
+
Requires-Dist: build>=0.10; extra == 'dev'
|
|
25
|
+
Requires-Dist: pytest-cov>=4; extra == 'dev'
|
|
26
|
+
Requires-Dist: pytest>=7.2; extra == 'dev'
|
|
27
|
+
Requires-Dist: scanpy>=1.9; extra == 'dev'
|
|
28
|
+
Requires-Dist: twine>=4; extra == 'dev'
|
|
29
|
+
Provides-Extra: scanpy
|
|
30
|
+
Requires-Dist: anndata>=0.10; extra == 'scanpy'
|
|
31
|
+
Requires-Dist: scanpy>=1.9; extra == 'scanpy'
|
|
32
|
+
Description-Content-Type: text/markdown
|
|
33
|
+
|
|
34
|
+
# scnmf
|
|
35
|
+
|
|
36
|
+
**Sparse conditional joint NMF for single-cell RNA-seq integration, dimensionality reduction, and metagene discovery.**
|
|
37
|
+
|
|
38
|
+
`scnmf` fits a nonnegative matrix factorization in which every batch shares a common
|
|
39
|
+
gene-program dictionary and additionally maintains batch-conditional programs:
|
|
40
|
+
|
|
41
|
+
\[
|
|
42
|
+
\hat{x}_{n,g}
|
|
43
|
+
=
|
|
44
|
+
\ell_n
|
|
45
|
+
\left(
|
|
46
|
+
[Wz_n]_g
|
|
47
|
+
+
|
|
48
|
+
[V_{b_n}a_{n,b_n}]_g
|
|
49
|
+
\right).
|
|
50
|
+
\]
|
|
51
|
+
|
|
52
|
+
The package trains on SciPy CSR mini-batches with PyTorch, supports CPU/GPU execution,
|
|
53
|
+
uses `tqdm` for progress reporting, and persists results to AnnData objects or
|
|
54
|
+
checkpoint directories.
|
|
55
|
+
|
|
56
|
+
## Installation
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
pip install "scnmf[anndata]"
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
For clustering and visualization, install the Scanpy extras:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
pip install "scnmf[scanpy]"
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
The core package only requires NumPy, SciPy, and PyTorch.
|
|
69
|
+
|
|
70
|
+
## Quick start
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
import scanpy as sc
|
|
74
|
+
from scnmf import SparseConditionalNMF
|
|
75
|
+
|
|
76
|
+
adata = sc.read_h5ad("pbmc.h5ad")
|
|
77
|
+
model = SparseConditionalNMF(
|
|
78
|
+
n_shared=30,
|
|
79
|
+
n_conditional=8,
|
|
80
|
+
batch_size=2048,
|
|
81
|
+
max_epochs=200,
|
|
82
|
+
learning_rate=5e-3,
|
|
83
|
+
likelihood="poisson",
|
|
84
|
+
seed=0,
|
|
85
|
+
)
|
|
86
|
+
model.fit(adata, batch_key="batch")
|
|
87
|
+
model.annotate(adata)
|
|
88
|
+
labels = model.predict_cluster(method="leiden", resolution=0.8)
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Command line
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
scnmf train \
|
|
95
|
+
--adata input.h5ad \
|
|
96
|
+
--batch-key batch \
|
|
97
|
+
--output runs/batch01 \
|
|
98
|
+
--n-shared 30 \
|
|
99
|
+
--n-conditional 8 \
|
|
100
|
+
--max-epochs 100
|
|
101
|
+
|
|
102
|
+
scnmf cluster \
|
|
103
|
+
--adata runs/batch01/annotated.h5ad \
|
|
104
|
+
--output runs/batch01 \
|
|
105
|
+
--method leiden \
|
|
106
|
+
--resolution 0.8
|
|
107
|
+
|
|
108
|
+
scnmf evaluate \
|
|
109
|
+
--adata runs/batch01/annotated.h5ad \
|
|
110
|
+
--batch-key batch \
|
|
111
|
+
--output runs/batch01
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Large data workflow
|
|
115
|
+
|
|
116
|
+
1. Store raw UMI counts in `adata.X` or a named `layer`.
|
|
117
|
+
2. Use a `batch_key` that represents the biological integration unit.
|
|
118
|
+
3. Train with stratified mini-batches; the default sampler allocates at least
|
|
119
|
+
`min_cells_per_batch` cells from every batch.
|
|
120
|
+
4. Project new cells with `model.transform(adata, update_factors=False)`.
|
|
121
|
+
5. Evaluate integration with batch ASW *and* biological labels—not ASW alone.
|
|
122
|
+
|
|
123
|
+
## Architecture
|
|
124
|
+
|
|
125
|
+
| Module | Responsibility |
|
|
126
|
+
| --- | --- |
|
|
127
|
+
| `scnmf.data` | CSR access, stratified sampling, AnnData validation |
|
|
128
|
+
| `scnmf.models` | Conditional factors, sparse losses, clustering |
|
|
129
|
+
| `scnmf.training` | Optimizer, mini-batch loop, checkpointing, progress |
|
|
130
|
+
| `scnmf.evaluation` | Reconstruction, batch mixing, clustering agreement |
|
|
131
|
+
|
|
132
|
+
## Reproducibility and limitations
|
|
133
|
+
|
|
134
|
+
`SparseConditionalNMF` records configuration, random seed, software version, batch
|
|
135
|
+
structure, and epoch-level metrics. Results are not guaranteed to be biologically
|
|
136
|
+
correct: shared and conditional factors are identifiable only up to permutation
|
|
137
|
+
and non-uniqueness common to NMF. Use synthetic controls and independent labels
|
|
138
|
+
when evaluating integration quality.
|
|
139
|
+
|
|
140
|
+
## License
|
|
141
|
+
|
|
142
|
+
Apache-2.0.
|
scnmf-0.1.0/README.md
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# scnmf
|
|
2
|
+
|
|
3
|
+
**Sparse conditional joint NMF for single-cell RNA-seq integration, dimensionality reduction, and metagene discovery.**
|
|
4
|
+
|
|
5
|
+
`scnmf` fits a nonnegative matrix factorization in which every batch shares a common
|
|
6
|
+
gene-program dictionary and additionally maintains batch-conditional programs:
|
|
7
|
+
|
|
8
|
+
\[
|
|
9
|
+
\hat{x}_{n,g}
|
|
10
|
+
=
|
|
11
|
+
\ell_n
|
|
12
|
+
\left(
|
|
13
|
+
[Wz_n]_g
|
|
14
|
+
+
|
|
15
|
+
[V_{b_n}a_{n,b_n}]_g
|
|
16
|
+
\right).
|
|
17
|
+
\]
|
|
18
|
+
|
|
19
|
+
The package trains on SciPy CSR mini-batches with PyTorch, supports CPU/GPU execution,
|
|
20
|
+
uses `tqdm` for progress reporting, and persists results to AnnData objects or
|
|
21
|
+
checkpoint directories.
|
|
22
|
+
|
|
23
|
+
## Installation
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pip install "scnmf[anndata]"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
For clustering and visualization, install the Scanpy extras:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
pip install "scnmf[scanpy]"
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The core package only requires NumPy, SciPy, and PyTorch.
|
|
36
|
+
|
|
37
|
+
## Quick start
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
import scanpy as sc
|
|
41
|
+
from scnmf import SparseConditionalNMF
|
|
42
|
+
|
|
43
|
+
adata = sc.read_h5ad("pbmc.h5ad")
|
|
44
|
+
model = SparseConditionalNMF(
|
|
45
|
+
n_shared=30,
|
|
46
|
+
n_conditional=8,
|
|
47
|
+
batch_size=2048,
|
|
48
|
+
max_epochs=200,
|
|
49
|
+
learning_rate=5e-3,
|
|
50
|
+
likelihood="poisson",
|
|
51
|
+
seed=0,
|
|
52
|
+
)
|
|
53
|
+
model.fit(adata, batch_key="batch")
|
|
54
|
+
model.annotate(adata)
|
|
55
|
+
labels = model.predict_cluster(method="leiden", resolution=0.8)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Command line
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
scnmf train \
|
|
62
|
+
--adata input.h5ad \
|
|
63
|
+
--batch-key batch \
|
|
64
|
+
--output runs/batch01 \
|
|
65
|
+
--n-shared 30 \
|
|
66
|
+
--n-conditional 8 \
|
|
67
|
+
--max-epochs 100
|
|
68
|
+
|
|
69
|
+
scnmf cluster \
|
|
70
|
+
--adata runs/batch01/annotated.h5ad \
|
|
71
|
+
--output runs/batch01 \
|
|
72
|
+
--method leiden \
|
|
73
|
+
--resolution 0.8
|
|
74
|
+
|
|
75
|
+
scnmf evaluate \
|
|
76
|
+
--adata runs/batch01/annotated.h5ad \
|
|
77
|
+
--batch-key batch \
|
|
78
|
+
--output runs/batch01
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Large data workflow
|
|
82
|
+
|
|
83
|
+
1. Store raw UMI counts in `adata.X` or a named `layer`.
|
|
84
|
+
2. Use a `batch_key` that represents the biological integration unit.
|
|
85
|
+
3. Train with stratified mini-batches; the default sampler allocates at least
|
|
86
|
+
`min_cells_per_batch` cells from every batch.
|
|
87
|
+
4. Project new cells with `model.transform(adata, update_factors=False)`.
|
|
88
|
+
5. Evaluate integration with batch ASW *and* biological labels—not ASW alone.
|
|
89
|
+
|
|
90
|
+
## Architecture
|
|
91
|
+
|
|
92
|
+
| Module | Responsibility |
|
|
93
|
+
| --- | --- |
|
|
94
|
+
| `scnmf.data` | CSR access, stratified sampling, AnnData validation |
|
|
95
|
+
| `scnmf.models` | Conditional factors, sparse losses, clustering |
|
|
96
|
+
| `scnmf.training` | Optimizer, mini-batch loop, checkpointing, progress |
|
|
97
|
+
| `scnmf.evaluation` | Reconstruction, batch mixing, clustering agreement |
|
|
98
|
+
|
|
99
|
+
## Reproducibility and limitations
|
|
100
|
+
|
|
101
|
+
`SparseConditionalNMF` records configuration, random seed, software version, batch
|
|
102
|
+
structure, and epoch-level metrics. Results are not guaranteed to be biologically
|
|
103
|
+
correct: shared and conditional factors are identifiable only up to permutation
|
|
104
|
+
and non-uniqueness common to NMF. Use synthetic controls and independent labels
|
|
105
|
+
when evaluating integration quality.
|
|
106
|
+
|
|
107
|
+
## License
|
|
108
|
+
|
|
109
|
+
Apache-2.0.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# scnmf documentation
|
|
2
|
+
|
|
3
|
+
## User guide
|
|
4
|
+
|
|
5
|
+
`scnmf` provides sparse conditional joint NMF for single-cell RNA-seq integration,
|
|
6
|
+
dimensionality reduction, and interpretable metagene discovery. It processes CSR
|
|
7
|
+
count matrices in mini-batches, supports CPU and CUDA, and reports training
|
|
8
|
+
progress with `tqdm`.
|
|
9
|
+
|
|
10
|
+
## API reference
|
|
11
|
+
|
|
12
|
+
- [`scnmf.SparseConditionalNMF`](python://scnmf.models.conditional_nmf.SparseConditionalNMF)
|
|
13
|
+
- [`scnmf.SCNMFConfig`](python://scnmf.config.SCNMFConfig)
|
|
14
|
+
- [`scnmf.setup_anndata`](python://scnmf.data.anndata_io.setup_anndata)
|
|
15
|
+
- [`scnmf.cli.main`](python://scnmf.cli.main)
|
|
16
|
+
|
|
17
|
+
## Examples
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
import scanpy as sc
|
|
21
|
+
from scnmf import SparseConditionalNMF
|
|
22
|
+
|
|
23
|
+
adata = sc.read_h5ad("pbmc.h5ad")
|
|
24
|
+
model = SparseConditionalNMF(n_shared=30, n_conditional=8, batch_size=2048)
|
|
25
|
+
model.fit(adata, batch_key="batch")
|
|
26
|
+
adata = model.annotate(adata)
|
|
27
|
+
```
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
# End-to-end tutorial: conditional joint NMF for 100k–1M cells 端到端教程:面向 10 万至 100 万细胞的联合 NMF 工作流 下面流程以一个伪计数矩阵演示如何从稀疏矩阵开始训练联合 NMF、保存检查点,并将共享载荷投影回原始对象。该示例不依赖真实生物学标签;生产环境中应额外使用批次混合、已知细胞标签以及 marker 基因稳定性来评估整合效果。 This example starts from a sparse count matrix, trains a conditional joint NMF model, saves the checkpoint, and projects the shared loadings back into the original object. It does not rely on real biological labels; production evaluations should additionally assess batch mixing, known-cell labels, and marker-gene stability. ## Create a sparse toy dataset 创建稀疏示例数据集 ```python from scipy import sparse import numpy as np from scnmf.data.sparse_csr import SparseExpressionMatrix from scnmf.data.batch_sampler import partition_from_labels def make_dataset(n_cells=10000, n_genes=2000, n_batches=3, seed=0): rng = np.random.default_rng(seed) programs = sparse.random(n_genes, 12, density=0.04, random_state=rng) loadings = sparse.random(n_cells, 12, density=0.08, random_state=rng) matrix = loadings @ programs.T matrix.data = np.abs(matrix.data) + rng.poisson(1, matrix.nnz).astype(np.float32) matrix.eliminate_zeros() return SparseExpressionMatrix( matrix.astype(np.float32), np.array([f"cell_{i}" for i in range(n_cells)]), np.array([f"gene_{j}" for j in range(n_genes)]), ), np.array([f"batch_{i % n_batches}" for i in range(n_cells)]) matrix, labels = make_dataset() partition = partition_from_labels(labels) print(matrix.n_cells, matrix.n_genes, partition.n_groups) ``` ## Configure and train the model 配置并训练模型 ```python from scnmf import SCNMFConfig, SparseConditionalNMF config = SCNMFConfig( n_shared=12, n_conditional=3, batch_size=1024, max_epochs=10, learning_rate=1e-2, likelihood="poisson", seed=0, verbose=True, ) model = SparseConditionalNMF(config=config, device="cpu") model.fit_from_matrix(matrix, batch_labels=labels) ``` `fit_from_matrix` 使用每批次的稀疏非零条目计算重建目标,并使用 `tqdm` 显示 epoch、损失、正则项与平均表达率。 The method computes the reconstruction objective using only observed nonzero entries per batch and shows epoch-level loss, regularization, and rate diagnostics through `tqdm`. ## Inspect programs and loadings 查看程序与载荷 ```python shared = model.get_loadings("shared") programs = model.get_programs("shared") top_genes = programs[:, 0].argsort()[-10:][::-1] print(shared.shape, programs.shape, top_genes) ``` Shared programs 应被解释为一组协同表达基因的非负权重;它们不是 p 值或严格意义上的“通路”。 Shared programs should be interpreted as nonnegative weights for co-expressed gene sets; they are not p-values or strictly defined pathways. ## Project or transform new cells 投影或转换新细胞 ```python projection = model.transform_from_matrix(matrix, labels) print(projection["shared"].shape, projection["conditional"].shape) ``` By default, `transform_from_matrix` freezes shared programs and conditional programs, making it suitable for reference mapping. If the new data should update the batch components, pass `update_factors=True`. 默认情况下,`transform_from_matrix` 会冻结共享程序和批次程序,适合作为参考映射使用。若希望新数据继续更新批次成分,可设置 `update_factors=True`。 ## Save and reload the model 保存并重新加载模型 ```python model.save("scnmf_tutorial") reloaded = SparseConditionalNMF(device="cpu").load("scnmf_tutorial") projected = reloaded.transform_from_matrix(matrix, labels) ``` Checkpoints record model tensors and a JSON manifest. They do not pickle arbitrary AnnData state, so downstream object attachment remains explicit. 检查点同时保存模型张量和 JSON 元数据,但不通过 pickle 保存任意 AnnData 状态,因此结果回写仍由用户显式控制。 ## Evaluate integration without overstating success 在不过度声称成功的前提下评估整合 ```python from scnmf.evaluation.batch_metrics import evaluate_loadings diagnostics = evaluate_loadings( shared, batch_labels=labels, true_labels=labels, # placeholder: replace with independent labels ) print(diagnostics) ``` A low batch ASW alone does not prove correct integration: it may indicate oversmoothing. Combine it with label preservation, reconstruction diagnostics, and marker consistency. 低批次 ASW 本身并不能证明整合正确,它可能意味着过度平滑。应将其与标签保留、重建指标及 marker 一致性联合使用。 ## Scaling guidance 扩展到更大规模数据 For 100k–1M cells: * store raw counts in CSR form rather than repeatedly densifying them; * use stratified mini-batches so that small batches remain represented; * train on CPU if sparse GPU transfer dominates computation; * delay neighbor graph, UMAP, and Leiden clustering until after full projection. 面向 10 万至 100 万细胞:应保留 CSR 格式的原始计数,避免反复稠密化;使用分层 mini-batch 保证小批次被采样;若 GPU 稀疏传输成本高于计算,则优先在 CPU 上训练;邻居图、UMAP 与 Leiden 聚类应延后至完整投影之后。
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
"""Basic usage example for sparse conditional joint NMF."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import numpy as np
|
|
6
|
+
from scipy import sparse
|
|
7
|
+
|
|
8
|
+
from scnmf import SCNMFConfig, SparseConditionalNMF
|
|
9
|
+
from scnmf.data.sparse_csr import SparseExpressionMatrix
|
|
10
|
+
from scnmf.data.batch_sampler import partition_from_labels
|
|
11
|
+
from scnmf.evaluation.batch_metrics import evaluate_loadings
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def make_toy_counts(n_cells: int = 2000, n_genes: int = 1000, n_batches: int = 3, seed: int = 0) -> SparseExpressionMatrix:
|
|
15
|
+
rng = np.random.default_rng(seed)
|
|
16
|
+
components = sparse.random(n_genes, 20, density=0.05, random_state=rng)
|
|
17
|
+
loadings = sparse.random(n_cells, 20, density=0.1, random_state=rng)
|
|
18
|
+
matrix = (loadings @ components.T).tocsr()
|
|
19
|
+
matrix.data = np.abs(matrix.data) + rng.poisson(1, size=matrix.nnz).astype(np.float32)
|
|
20
|
+
matrix.eliminate_zeros()
|
|
21
|
+
return SparseExpressionMatrix(
|
|
22
|
+
matrix.astype(np.float32),
|
|
23
|
+
row_names=np.array([f"cell_{i}" for i in range(n_cells)]),
|
|
24
|
+
col_names=np.array([f"gene_{j}" for j in range(n_genes)]),
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def main() -> None:
|
|
29
|
+
matrix = make_toy_counts()
|
|
30
|
+
batch_labels = partition_from_labels(np.array([f"batch_{i % 3}" for i in range(matrix.n_cells)]))
|
|
31
|
+
config = SCNMFConfig(n_shared=10, n_conditional=3, batch_size=256, max_epochs=5, verbose=True)
|
|
32
|
+
model = SparseConditionalNMF(config=config)
|
|
33
|
+
model.fit_from_matrix(matrix, batch_labels=batch_labels.labels)
|
|
34
|
+
shared = model.get_loadings("shared")
|
|
35
|
+
programs = model.get_programs("shared")
|
|
36
|
+
print("shared loadings:", shared.shape, "shared programs:", programs.shape)
|
|
37
|
+
|
|
38
|
+
projection = model.transform_from_matrix(matrix, batch_labels=batch_labels.labels)
|
|
39
|
+
print("projected shared:", projection["shared"].shape)
|
|
40
|
+
diagnostics = evaluate_loadings(
|
|
41
|
+
projection["shared"],
|
|
42
|
+
batch_labels=batch_labels.labels,
|
|
43
|
+
true_labels=batch_labels.labels,
|
|
44
|
+
)
|
|
45
|
+
print("diagnostics:", diagnostics)
|
|
46
|
+
|
|
47
|
+
clusters = model.predict_cluster(projection["shared"], n_clusters=5, method="kmeans")
|
|
48
|
+
print("clusters:", np.unique(clusters, return_counts=True))
|
|
49
|
+
|
|
50
|
+
model.save("scnmf_example_output")
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
if __name__ == "__main__":
|
|
54
|
+
main()
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.18", "hatch-vcs>=0.3"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "scnmf"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Sparse conditional joint NMF for single-cell RNA-seq integration, dimensionality reduction, and interpretable metagene discovery."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "Apache-2.0" }
|
|
11
|
+
requires-python = ">=3.10"
|
|
12
|
+
authors = [{ name = "SCNMF Developers" }]
|
|
13
|
+
keywords = ["single-cell", "NMF", "PyTorch", "integration", "batch-correction", "AnnData"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 4 - Beta",
|
|
16
|
+
"Intended Audience :: Science/Research",
|
|
17
|
+
"License :: OSI Approved :: Apache Software License",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
20
|
+
"Topic :: Scientific/Engineering :: Bio-Informatics",
|
|
21
|
+
]
|
|
22
|
+
dependencies = [
|
|
23
|
+
"numpy>=1.23",
|
|
24
|
+
"scipy>=1.10",
|
|
25
|
+
"torch>=2.0",
|
|
26
|
+
]
|
|
27
|
+
|
|
28
|
+
[project.optional-dependencies]
|
|
29
|
+
anndata = ["anndata>=0.10"]
|
|
30
|
+
scanpy = ["anndata>=0.10", "scanpy>=1.9"]
|
|
31
|
+
dev = [
|
|
32
|
+
"anndata>=0.10",
|
|
33
|
+
"scanpy>=1.9",
|
|
34
|
+
"pytest>=7.2",
|
|
35
|
+
"pytest-cov>=4",
|
|
36
|
+
"build>=0.10",
|
|
37
|
+
"twine>=4",
|
|
38
|
+
]
|
|
39
|
+
|
|
40
|
+
[project.scripts]
|
|
41
|
+
scnmf = "scnmf.cli:main"
|
|
42
|
+
|
|
43
|
+
[project.urls]
|
|
44
|
+
Homepage = "https://github.com/ZengFLab/scnmf-py"
|
|
45
|
+
Issues = "https://github.com/ZengFLab/scnmf-py/issues"
|
|
46
|
+
|
|
47
|
+
[tool.hatch.build.targets.wheel]
|
|
48
|
+
packages = ["src/scnmf"]
|
|
49
|
+
|
|
50
|
+
[tool.hatch.version]
|
|
51
|
+
path = "src/scnmf/__init__.py"
|
|
52
|
+
|
|
53
|
+
[tool.hatch.build.hooks.vcs]
|
|
54
|
+
version-file = "src/scnmf/_version.py"
|
|
55
|
+
|
|
56
|
+
[tool.pytest.ini_options]
|
|
57
|
+
testpaths = ["tests"]
|
|
58
|
+
addopts = ["-q", "--doctest-modules", "--strict-markers"]
|
|
59
|
+
filterwarnings = ["error::RuntimeWarning"]
|
|
60
|
+
markers = [
|
|
61
|
+
"large: tests with elevated memory or runtime requirements",
|
|
62
|
+
]
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"""Sparse conditional joint NMF for single-cell RNA-seq."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
__version__ = "0.1.0"
|
|
6
|
+
|
|
7
|
+
from scnmf.config import SCNMFConfig
|
|
8
|
+
from scnmf.data.batch_sampler import partition_from_labels
|
|
9
|
+
from scnmf.data.sparse_csr import SparseBatch, SparseExpressionMatrix
|
|
10
|
+
|
|
11
|
+
__all__ = [
|
|
12
|
+
"__version__",
|
|
13
|
+
"SCNMFConfig",
|
|
14
|
+
"SparseConditionalNMF",
|
|
15
|
+
"SparseExpressionMatrix",
|
|
16
|
+
"SparseBatch",
|
|
17
|
+
"partition_from_labels",
|
|
18
|
+
"setup_anndata",
|
|
19
|
+
]
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def __getattr__(name: str):
|
|
23
|
+
if name == "SparseConditionalNMF":
|
|
24
|
+
from scnmf.models.conditional_nmf import SparseConditionalNMF
|
|
25
|
+
return SparseConditionalNMF
|
|
26
|
+
if name == "setup_anndata":
|
|
27
|
+
from scnmf.data.anndata_io import setup_anndata
|
|
28
|
+
return setup_anndata
|
|
29
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# file generated by vcs-versioning
|
|
2
|
+
# don't change, don't track in version control
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
__all__ = [
|
|
6
|
+
"__version__",
|
|
7
|
+
"__version_tuple__",
|
|
8
|
+
"version",
|
|
9
|
+
"version_tuple",
|
|
10
|
+
"__commit_id__",
|
|
11
|
+
"commit_id",
|
|
12
|
+
]
|
|
13
|
+
|
|
14
|
+
version: str
|
|
15
|
+
__version__: str
|
|
16
|
+
__version_tuple__: tuple[int | str, ...]
|
|
17
|
+
version_tuple: tuple[int | str, ...]
|
|
18
|
+
commit_id: str | None
|
|
19
|
+
__commit_id__: str | None
|
|
20
|
+
|
|
21
|
+
__version__ = version = '0.1.0'
|
|
22
|
+
__version_tuple__ = version_tuple = (0, 1, 0)
|
|
23
|
+
|
|
24
|
+
__commit_id__ = commit_id = None
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
"""Command-line interface for the ``scnmf`` package."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import json
|
|
7
|
+
import os
|
|
8
|
+
import sys
|
|
9
|
+
from typing import Any, Dict, Optional
|
|
10
|
+
|
|
11
|
+
import numpy as np
|
|
12
|
+
|
|
13
|
+
from scnmf.config import SCNMFConfig
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def _read_json(path: str) -> Dict[str, Any]:
|
|
17
|
+
with open(path, "r", encoding="utf-8") as handle:
|
|
18
|
+
return json.load(handle)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
22
|
+
parser = argparse.ArgumentParser(
|
|
23
|
+
prog="scnmf",
|
|
24
|
+
description="Sparse conditional joint NMF for single-cell RNA-seq integration and analysis.",
|
|
25
|
+
)
|
|
26
|
+
subparsers = parser.add_subparsers(dest="command", required=True)
|
|
27
|
+
|
|
28
|
+
base = argparse.ArgumentParser(add_help=False)
|
|
29
|
+
base.add_argument("--adata", required=True, help="Input AnnData .h5ad file")
|
|
30
|
+
base.add_argument("--batch-key", default="batch", help="Column in adata.obs defining batches")
|
|
31
|
+
base.add_argument("--layer", default=None, help="Count layer to use; defaults to adata.X")
|
|
32
|
+
base.add_argument("--output", required=True, help="Output directory")
|
|
33
|
+
base.add_argument("--device", default="auto", help="Device: auto, cpu, or cuda")
|
|
34
|
+
base.add_argument("--seed", type=int, default=0)
|
|
35
|
+
|
|
36
|
+
train = subparsers.add_parser("train", parents=[base], help="Train a conditional joint NMF model")
|
|
37
|
+
train.add_argument("--config", help="JSON configuration file")
|
|
38
|
+
train.add_argument("--n-shared", type=int, default=30)
|
|
39
|
+
train.add_argument("--n-conditional", type=int, default=8)
|
|
40
|
+
train.add_argument("--batch-size", type=int, default=2048)
|
|
41
|
+
train.add_argument("--max-epochs", type=int, default=200)
|
|
42
|
+
train.add_argument("--learning-rate", type=float, default=0.005)
|
|
43
|
+
train.add_argument("--likelihood", default="poisson", choices=["poisson", "kl", "gaussian"])
|
|
44
|
+
train.add_argument("--verbose/--silent", default=True, action=argparse.BooleanOptionalAction)
|
|
45
|
+
|
|
46
|
+
transform = subparsers.add_parser("transform", parents=[base], help="Project cells with a trained model")
|
|
47
|
+
transform.add_argument("--checkpoint", required=True, help="Directory containing model.pt and metadata.json")
|
|
48
|
+
transform.add_argument("--chunk-size", type=int, default=4096)
|
|
49
|
+
|
|
50
|
+
cluster = subparsers.add_parser("cluster", parents=[base], help="Cluster shared loadings")
|
|
51
|
+
cluster.add_argument("--method", default="kmeans", choices=["kmeans", "leiden"])
|
|
52
|
+
cluster.add_argument("--n-clusters", type=int, default=20)
|
|
53
|
+
cluster.add_argument("--resolution", type=float, default=0.8)
|
|
54
|
+
cluster.add_argument("--key", default="scnmf_cluster")
|
|
55
|
+
|
|
56
|
+
evaluate = subparsers.add_parser("evaluate", parents=[base], help="Write evaluation metadata")
|
|
57
|
+
evaluate.add_argument("--metrics", default="integration", choices=["integration", "reconstruction", "all"])
|
|
58
|
+
evaluate.add_argument("--true-labels", default=None, help="Optional obs column with ground-truth labels")
|
|
59
|
+
|
|
60
|
+
return parser
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _load_anndata(path: str):
|
|
64
|
+
try:
|
|
65
|
+
from anndata import read_h5ad
|
|
66
|
+
except ImportError as exc: # pragma: no cover - environment-dependent
|
|
67
|
+
raise SystemExit("AnnData is required: pip install 'scnmf[anndata]'") from exc
|
|
68
|
+
return read_h5ad(path)
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def _build_config(args: argparse.Namespace) -> SCNMFConfig:
|
|
72
|
+
values: Dict[str, Any] = {}
|
|
73
|
+
if getattr(args, "config", None):
|
|
74
|
+
values.update(_read_json(args.config))
|
|
75
|
+
for key in {
|
|
76
|
+
"n_shared",
|
|
77
|
+
"n_conditional",
|
|
78
|
+
"likelihood",
|
|
79
|
+
"batch_size",
|
|
80
|
+
"max_epochs",
|
|
81
|
+
"learning_rate",
|
|
82
|
+
"seed",
|
|
83
|
+
"verbose",
|
|
84
|
+
}:
|
|
85
|
+
if hasattr(args, key):
|
|
86
|
+
values.setdefault(key, getattr(args, key))
|
|
87
|
+
return SCNMFConfig.from_dict(values)
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def command_train(args: argparse.Namespace) -> int:
|
|
91
|
+
from scnmf.models.conditional_nmf import SparseConditionalNMF
|
|
92
|
+
|
|
93
|
+
adata = _load_anndata(args.adata)
|
|
94
|
+
config = _build_config(args)
|
|
95
|
+
model = SparseConditionalNMF(config=config, device=args.device)
|
|
96
|
+
model.fit(
|
|
97
|
+
adata,
|
|
98
|
+
layer=args.layer,
|
|
99
|
+
batch_key=args.batch_key,
|
|
100
|
+
use_raw=False,
|
|
101
|
+
)
|
|
102
|
+
model.save(args.output)
|
|
103
|
+
model.annotate(adata).write(os.path.join(args.output, "annotated.h5ad"), compression="gzip")
|
|
104
|
+
return 0
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def command_transform(args: argparse.Namespace) -> int:
|
|
108
|
+
from scnmf.models.conditional_nmf import SparseConditionalNMF
|
|
109
|
+
|
|
110
|
+
model = SparseConditionalNMF(device=args.device).load(args.checkpoint)
|
|
111
|
+
adata = _load_anndata(args.adata)
|
|
112
|
+
result = model.transform(adata, layer=args.layer, chunk_size=args.chunk_size)
|
|
113
|
+
np.savez_compressed(os.path.join(args.output, "loadings.npz"), **{k: v for k, v in result.items() if isinstance(v, np.ndarray)})
|
|
114
|
+
return 0
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def command_cluster(args: argparse.Namespace) -> int:
|
|
118
|
+
adata = _load_anndata(args.adata)
|
|
119
|
+
key = "scnmf_shared"
|
|
120
|
+
if key not in adata.obsm:
|
|
121
|
+
raise SystemExit(f"{key} not found in adata.obsm; run train or transform first.")
|
|
122
|
+
loadings = np.asarray(adata.obsm[key], dtype=np.float32)
|
|
123
|
+
from scnmf.models.cluster_head import KMeansClusterHead, scanpy_leiden_labels
|
|
124
|
+
|
|
125
|
+
if args.method == "kmeans":
|
|
126
|
+
labels = KMeansClusterHead(n_clusters=args.n_clusters, random_state=args.seed).fit(loadings)
|
|
127
|
+
else:
|
|
128
|
+
labels = scanpy_leiden_labels(loadings, resolution=args.resolution, random_state=args.seed)
|
|
129
|
+
adata.obs[args.key] = np.asarray(labels, dtype=np.intp).astype("category")
|
|
130
|
+
adata.write(os.path.join(args.output, "clustered.h5ad"), compression="gzip")
|
|
131
|
+
return 0
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def command_evaluate(args: argparse.Namespace) -> int:
|
|
135
|
+
from scnmf.evaluation.batch_metrics import evaluate_loadings
|
|
136
|
+
|
|
137
|
+
adata = _load_anndata(args.adata)
|
|
138
|
+
if "scnmf_shared" not in adata.obsm:
|
|
139
|
+
raise SystemExit("scnmf_shared embedding is required for evaluation")
|
|
140
|
+
loadings = np.asarray(adata.obsm["scnmf_shared"], dtype=np.float32)
|
|
141
|
+
batch_labels = np.asarray(adata.obs[args.batch_key].astype(str)) if args.batch_key in adata.obs else None
|
|
142
|
+
true_labels = np.asarray(adata.obs[args.true_labels].astype(str)) if args.true_labels and args.true_labels in adata.obs else None
|
|
143
|
+
result = evaluate_loadings(loadings, batch_labels=batch_labels, true_labels=true_labels, predicted_labels=None)
|
|
144
|
+
os.makedirs(args.output, exist_ok=True)
|
|
145
|
+
with open(os.path.join(args.output, "evaluation.json"), "w", encoding="utf-8") as handle:
|
|
146
|
+
json.dump(result, handle, indent=2)
|
|
147
|
+
return 0
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def main(argv: Optional[Sequence[str]] = None) -> int:
|
|
151
|
+
parser = build_parser()
|
|
152
|
+
args = parser.parse_args(argv)
|
|
153
|
+
commands = {
|
|
154
|
+
"train": command_train,
|
|
155
|
+
"transform": command_transform,
|
|
156
|
+
"cluster": command_cluster,
|
|
157
|
+
"evaluate": command_evaluate,
|
|
158
|
+
}
|
|
159
|
+
return commands[args.command](args)
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
if __name__ == "__main__":
|
|
163
|
+
sys.exit(main())
|