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 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())