scnmf-gpu 0.4.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_gpu-0.4.0/LICENSE +21 -0
- scnmf_gpu-0.4.0/PKG-INFO +82 -0
- scnmf_gpu-0.4.0/README.md +37 -0
- scnmf_gpu-0.4.0/pyproject.toml +62 -0
- scnmf_gpu-0.4.0/src/scnmf/__init__.py +61 -0
- scnmf_gpu-0.4.0/src/scnmf/_version.py +24 -0
- scnmf_gpu-0.4.0/src/scnmf/cli.py +163 -0
- scnmf_gpu-0.4.0/src/scnmf/config.py +102 -0
- scnmf_gpu-0.4.0/src/scnmf/data/__init__.py +0 -0
- scnmf_gpu-0.4.0/src/scnmf/data/anndata_io.py +167 -0
- scnmf_gpu-0.4.0/src/scnmf/data/batch_sampler.py +171 -0
- scnmf_gpu-0.4.0/src/scnmf/data/sparse_csr.py +169 -0
- scnmf_gpu-0.4.0/src/scnmf/evaluation/__init__.py +3 -0
- scnmf_gpu-0.4.0/src/scnmf/evaluation/batch_metrics.py +82 -0
- scnmf_gpu-0.4.0/src/scnmf/evaluation/reconstruction.py +26 -0
- scnmf_gpu-0.4.0/src/scnmf/models/__init__.py +0 -0
- scnmf_gpu-0.4.0/src/scnmf/models/cluster_head.py +94 -0
- scnmf_gpu-0.4.0/src/scnmf/models/conditional_nmf.py +533 -0
- scnmf_gpu-0.4.0/src/scnmf/models/factors.py +890 -0
- scnmf_gpu-0.4.0/src/scnmf/models/factors_numpy.py +180 -0
- scnmf_gpu-0.4.0/src/scnmf/models/likelihoods.py +76 -0
- scnmf_gpu-0.4.0/src/scnmf/models/torch_trainer.py +393 -0
- scnmf_gpu-0.4.0/src/scnmf/online.py +755 -0
- scnmf_gpu-0.4.0/src/scnmf/training/__init__.py +0 -0
- scnmf_gpu-0.4.0/src/scnmf/training/logging.py +97 -0
- scnmf_gpu-0.4.0/src/scnmf/training/losses.py +106 -0
- scnmf_gpu-0.4.0/src/scnmf/training/trainer.py +285 -0
scnmf_gpu-0.4.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024-2026 scnmf-gpu 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.
|
scnmf_gpu-0.4.0/PKG-INFO
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: scnmf-gpu
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: Sparse conditional joint NMF for single-cell RNA-seq integration, dimensionality reduction, and interpretable metagene discovery. PyTorch GPU backend.
|
|
5
|
+
Project-URL: Homepage, https://github.com/ZengFLab/scnmf-gpu
|
|
6
|
+
Project-URL: Issues, https://github.com/ZengFLab/scnmf-gpu/issues
|
|
7
|
+
Author: SCNMF Developers
|
|
8
|
+
License: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: AnnData,CUDA,GPU,NMF,PyTorch,batch-correction,integration,single-cell
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Requires-Dist: numpy>=1.21
|
|
19
|
+
Requires-Dist: scipy>=1.7
|
|
20
|
+
Requires-Dist: torch>=2.0
|
|
21
|
+
Provides-Extra: all
|
|
22
|
+
Requires-Dist: anndata>=0.10; extra == 'all'
|
|
23
|
+
Requires-Dist: build>=0.10; extra == 'all'
|
|
24
|
+
Requires-Dist: pytest-cov>=4; extra == 'all'
|
|
25
|
+
Requires-Dist: pytest>=7.2; extra == 'all'
|
|
26
|
+
Requires-Dist: scanpy>=1.9; extra == 'all'
|
|
27
|
+
Requires-Dist: torch>=2.0; extra == 'all'
|
|
28
|
+
Requires-Dist: twine>=4; extra == 'all'
|
|
29
|
+
Provides-Extra: anndata
|
|
30
|
+
Requires-Dist: anndata>=0.10; extra == 'anndata'
|
|
31
|
+
Provides-Extra: cuda
|
|
32
|
+
Requires-Dist: torch>=2.0; extra == 'cuda'
|
|
33
|
+
Provides-Extra: dev
|
|
34
|
+
Requires-Dist: anndata>=0.10; extra == 'dev'
|
|
35
|
+
Requires-Dist: build>=0.10; extra == 'dev'
|
|
36
|
+
Requires-Dist: pytest-cov>=4; extra == 'dev'
|
|
37
|
+
Requires-Dist: pytest>=7.2; extra == 'dev'
|
|
38
|
+
Requires-Dist: scanpy>=1.9; extra == 'dev'
|
|
39
|
+
Requires-Dist: twine>=4; extra == 'dev'
|
|
40
|
+
Provides-Extra: online
|
|
41
|
+
Provides-Extra: scanpy
|
|
42
|
+
Requires-Dist: anndata>=0.10; extra == 'scanpy'
|
|
43
|
+
Requires-Dist: scanpy>=1.9; extra == 'scanpy'
|
|
44
|
+
Description-Content-Type: text/markdown
|
|
45
|
+
|
|
46
|
+
# scnmf-gpu 0.4.0
|
|
47
|
+
|
|
48
|
+
Sparse Conditional Joint NMF for single-cell RNA-seq — **PyTorch GPU backend**.
|
|
49
|
+
|
|
50
|
+
## Install
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
pip install torch --index-url https://download.pytorch.org/whl/cu126
|
|
54
|
+
pip install scnmf-gpu
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Quick start
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from scnmf import SparseConditionalNMF
|
|
61
|
+
model = SparseConditionalNMF(n_shared=30, n_conditional=8, device="cuda")
|
|
62
|
+
model.fit_from_matrix(matrix, batch_labels, max_epochs=100)
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Online learning
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
# Project (frozen reference)
|
|
69
|
+
from scnmf import OnlineProjector
|
|
70
|
+
loadings = OnlineProjector(model).project(new_matrix, batch_labels)
|
|
71
|
+
|
|
72
|
+
# Refine (incremental update)
|
|
73
|
+
from scnmf import IncrementalTrainer
|
|
74
|
+
loadings = IncrementalTrainer(model).online_update(
|
|
75
|
+
new_matrix, batch_labels, new_batch_id="batch_3",
|
|
76
|
+
w_lr=1e-4, v_lr=1e-3, stability_penalty=0.1,
|
|
77
|
+
)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## License
|
|
81
|
+
|
|
82
|
+
MIT
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# scnmf-gpu 0.4.0
|
|
2
|
+
|
|
3
|
+
Sparse Conditional Joint NMF for single-cell RNA-seq — **PyTorch GPU backend**.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pip install torch --index-url https://download.pytorch.org/whl/cu126
|
|
9
|
+
pip install scnmf-gpu
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Quick start
|
|
13
|
+
|
|
14
|
+
```python
|
|
15
|
+
from scnmf import SparseConditionalNMF
|
|
16
|
+
model = SparseConditionalNMF(n_shared=30, n_conditional=8, device="cuda")
|
|
17
|
+
model.fit_from_matrix(matrix, batch_labels, max_epochs=100)
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Online learning
|
|
21
|
+
|
|
22
|
+
```python
|
|
23
|
+
# Project (frozen reference)
|
|
24
|
+
from scnmf import OnlineProjector
|
|
25
|
+
loadings = OnlineProjector(model).project(new_matrix, batch_labels)
|
|
26
|
+
|
|
27
|
+
# Refine (incremental update)
|
|
28
|
+
from scnmf import IncrementalTrainer
|
|
29
|
+
loadings = IncrementalTrainer(model).online_update(
|
|
30
|
+
new_matrix, batch_labels, new_batch_id="batch_3",
|
|
31
|
+
w_lr=1e-4, v_lr=1e-3, stability_penalty=0.1,
|
|
32
|
+
)
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## License
|
|
36
|
+
|
|
37
|
+
MIT
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.18"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "scnmf-gpu"
|
|
7
|
+
version = "0.4.0"
|
|
8
|
+
description = "Sparse conditional joint NMF for single-cell RNA-seq integration, dimensionality reduction, and interpretable metagene discovery. PyTorch GPU backend."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "MIT" }
|
|
11
|
+
requires-python = ">=3.10"
|
|
12
|
+
authors = [{ name = "SCNMF Developers" }]
|
|
13
|
+
keywords = ["single-cell", "NMF", "PyTorch", "GPU", "CUDA", "integration", "batch-correction", "AnnData"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 4 - Beta",
|
|
16
|
+
"Intended Audience :: Science/Research",
|
|
17
|
+
"License :: OSI Approved :: MIT License",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
20
|
+
"Topic :: Scientific/Engineering :: Bio-Informatics",
|
|
21
|
+
]
|
|
22
|
+
dependencies = [
|
|
23
|
+
"numpy>=1.21",
|
|
24
|
+
"scipy>=1.7",
|
|
25
|
+
"torch>=2.0",
|
|
26
|
+
]
|
|
27
|
+
|
|
28
|
+
[project.optional-dependencies]
|
|
29
|
+
cuda = ["torch>=2.0"]
|
|
30
|
+
anndata = ["anndata>=0.10"]
|
|
31
|
+
scanpy = ["anndata>=0.10", "scanpy>=1.9"]
|
|
32
|
+
online = []
|
|
33
|
+
all = ["scnmf-gpu[cuda,anndata,scanpy,dev]"]
|
|
34
|
+
dev = [
|
|
35
|
+
"anndata>=0.10",
|
|
36
|
+
"scanpy>=1.9",
|
|
37
|
+
"pytest>=7.2",
|
|
38
|
+
"pytest-cov>=4",
|
|
39
|
+
"build>=0.10",
|
|
40
|
+
"twine>=4",
|
|
41
|
+
]
|
|
42
|
+
|
|
43
|
+
[project.scripts]
|
|
44
|
+
scnmf-gpu = "scnmf.cli:main"
|
|
45
|
+
|
|
46
|
+
[project.urls]
|
|
47
|
+
Homepage = "https://github.com/ZengFLab/scnmf-gpu"
|
|
48
|
+
Issues = "https://github.com/ZengFLab/scnmf-gpu/issues"
|
|
49
|
+
|
|
50
|
+
[tool.hatch.build.targets.wheel]
|
|
51
|
+
packages = ["src/scnmf"]
|
|
52
|
+
|
|
53
|
+
[tool.hatch.version]
|
|
54
|
+
path = "src/scnmf/__init__.py"
|
|
55
|
+
|
|
56
|
+
[tool.pytest.ini_options]
|
|
57
|
+
testpaths = ["tests"]
|
|
58
|
+
addopts = ["-q", "--strict-markers"]
|
|
59
|
+
filterwarnings = ["error::RuntimeWarning"]
|
|
60
|
+
markers = [
|
|
61
|
+
"large: tests with elevated memory or runtime requirements",
|
|
62
|
+
]
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
"""Sparse conditional joint NMF for single-cell RNA-seq (PyTorch GPU backend)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
__version__ = "0.4.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
|
+
# The online / incremental-learning module requires PyTorch at runtime and
|
|
12
|
+
# is therefore imported lazily: environments that do not need online updates
|
|
13
|
+
# (and may not have those dependencies installed) should not pay the import
|
|
14
|
+
# cost, nor should their import fail because of it. Accessing any of the names
|
|
15
|
+
# below triggers ``__getattr__``, which imports the submodule on demand and
|
|
16
|
+
# raises a clear error if the PyTorch dependency is missing.
|
|
17
|
+
_online_names = (
|
|
18
|
+
"OnlineConfig",
|
|
19
|
+
"OnlineHistory",
|
|
20
|
+
"OnlineProjector",
|
|
21
|
+
"IncrementalTrainer",
|
|
22
|
+
"project_loadings",
|
|
23
|
+
"refine_with_new_batch",
|
|
24
|
+
)
|
|
25
|
+
|
|
26
|
+
__all__ = [
|
|
27
|
+
"__version__",
|
|
28
|
+
"SCNMFConfig",
|
|
29
|
+
"SparseConditionalNMF",
|
|
30
|
+
"SparseExpressionMatrix",
|
|
31
|
+
"SparseBatch",
|
|
32
|
+
"partition_from_labels",
|
|
33
|
+
"setup_anndata",
|
|
34
|
+
*_online_names,
|
|
35
|
+
]
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def __getattr__(name: str):
|
|
39
|
+
if name == "SparseConditionalNMF":
|
|
40
|
+
from scnmf.models.conditional_nmf import SparseConditionalNMF
|
|
41
|
+
return SparseConditionalNMF
|
|
42
|
+
if name == "setup_anndata":
|
|
43
|
+
from scnmf.data.anndata_io import setup_anndata
|
|
44
|
+
return setup_anndata
|
|
45
|
+
if name in _online_names:
|
|
46
|
+
try:
|
|
47
|
+
import torch # noqa: F401 -- fail fast with a helpful message
|
|
48
|
+
except ImportError as exc: # pragma: no cover - import-time guard
|
|
49
|
+
raise ImportError(
|
|
50
|
+
f"{name} requires PyTorch, which is not installed. "
|
|
51
|
+
"Install scnmf-gpu with the 'cuda' extra or run "
|
|
52
|
+
"'pip install torch' before using online learning."
|
|
53
|
+
) from exc
|
|
54
|
+
from scnmf import online as _online
|
|
55
|
+
try:
|
|
56
|
+
return getattr(_online, name)
|
|
57
|
+
except AttributeError as exc: # pragma: no cover
|
|
58
|
+
raise AttributeError(
|
|
59
|
+
f"module 'scnmf.online' has no attribute {name!r}"
|
|
60
|
+
) from exc
|
|
61
|
+
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.4.0'
|
|
22
|
+
__version_tuple__ = version_tuple = (0, 4, 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.npz 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())
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
"""Typed, serializable configuration for :class:`scnmf.models.conditional_nmf.SparseConditionalNMF`."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import dataclasses
|
|
6
|
+
import json
|
|
7
|
+
from dataclasses import dataclass, field, fields
|
|
8
|
+
from typing import Any, Dict, Optional
|
|
9
|
+
|
|
10
|
+
LIKELIHOODS = {"gaussian", "kl", "poisson"}
|
|
11
|
+
CONSTRAINTS = {"softplus", "exp", "clamp"}
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def _positive_integer(name: str, value: int) -> None:
|
|
15
|
+
if not isinstance(value, int) or isinstance(value, bool) or value < 1:
|
|
16
|
+
raise ValueError(f"{name} must be a positive integer, got {value!r}")
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def _nonnegative_float(name: str, value: float) -> None:
|
|
20
|
+
if not isinstance(value, (int, float)) or isinstance(value, bool) or value < 0:
|
|
21
|
+
raise ValueError(f"{name} must be a non-negative real number, got {value!r}")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
@dataclass
|
|
25
|
+
class SCNMFConfig:
|
|
26
|
+
"""Training and model configuration.
|
|
27
|
+
|
|
28
|
+
Attributes are deliberately simple JSON types so that configurations can be
|
|
29
|
+
written to model manifests and reused from command-line tools.
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
n_shared: int = 30
|
|
33
|
+
n_conditional: int = 8
|
|
34
|
+
likelihood: str = "poisson"
|
|
35
|
+
constraint: str = "softplus"
|
|
36
|
+
library: str = "fixed"
|
|
37
|
+
use_batch_norm: bool = True
|
|
38
|
+
shared_l1: float = 0.0
|
|
39
|
+
conditional_l1: float = 0.0
|
|
40
|
+
loading_l2: float = 0.01
|
|
41
|
+
batch_size: int = 2048
|
|
42
|
+
max_epochs: int = 200
|
|
43
|
+
learning_rate: float = 0.005
|
|
44
|
+
optimizer: str = "adamw"
|
|
45
|
+
weight_decay: float = 0.0
|
|
46
|
+
warmup_epochs: int = 0
|
|
47
|
+
grad_clip: Optional[float] = 1.0
|
|
48
|
+
batch_balance: str = "stratified"
|
|
49
|
+
min_cells_per_batch: int = 16
|
|
50
|
+
max_cells_per_batch: Optional[int] = None
|
|
51
|
+
use_sparse_tensor: bool = False
|
|
52
|
+
eps: float = 1e-8
|
|
53
|
+
seed: int = 0
|
|
54
|
+
verbose: bool = True
|
|
55
|
+
log_interval: int = 25
|
|
56
|
+
extra: Dict[str, Any] = field(default_factory=dict)
|
|
57
|
+
|
|
58
|
+
def __post_init__(self) -> None:
|
|
59
|
+
_positive_integer("n_shared", self.n_shared)
|
|
60
|
+
if self.n_conditional < 0:
|
|
61
|
+
raise ValueError("n_conditional must be non-negative")
|
|
62
|
+
if self.likelihood not in LIKELIHOODS:
|
|
63
|
+
raise ValueError(f"likelihood must be one of {sorted(LIKELIHOODS)}")
|
|
64
|
+
if self.constraint not in CONSTRAINTS:
|
|
65
|
+
raise ValueError(f"constraint must be one of {sorted(CONSTRAINTS)}")
|
|
66
|
+
if self.library not in {"fixed", "shared", "cell"}:
|
|
67
|
+
raise ValueError("library must be 'fixed', 'shared', or 'cell'")
|
|
68
|
+
_positive_integer("batch_size", self.batch_size)
|
|
69
|
+
_positive_integer("max_epochs", self.max_epochs)
|
|
70
|
+
_nonnegative_float("learning_rate", self.learning_rate)
|
|
71
|
+
if self.optimizer not in {"adam", "adamw", "sgd"}:
|
|
72
|
+
raise ValueError("optimizer must be 'adam', 'adamw', or 'sgd'")
|
|
73
|
+
_nonnegative_float("weight_decay", self.weight_decay)
|
|
74
|
+
_nonnegative_float("loading_l2", self.loading_l2)
|
|
75
|
+
_positive_integer("log_interval", self.log_interval)
|
|
76
|
+
_nonnegative_float("eps", self.eps)
|
|
77
|
+
|
|
78
|
+
def to_dict(self) -> Dict[str, Any]:
|
|
79
|
+
return dataclasses.asdict(self)
|
|
80
|
+
|
|
81
|
+
def to_json(self) -> str:
|
|
82
|
+
return json.dumps(self.to_dict(), sort_keys=True, indent=2)
|
|
83
|
+
|
|
84
|
+
@classmethod
|
|
85
|
+
def from_dict(cls, data: Dict[str, Any]) -> "SCNMFConfig":
|
|
86
|
+
unknown = set(data) - {field.name for field in fields(cls)}
|
|
87
|
+
if unknown:
|
|
88
|
+
raise ValueError(f"Unknown configuration keys: {sorted(unknown)}")
|
|
89
|
+
return cls(**data)
|
|
90
|
+
|
|
91
|
+
def get(self, key: str, default: Any = None) -> Any:
|
|
92
|
+
if key in self.extra:
|
|
93
|
+
return self.extra[key]
|
|
94
|
+
if hasattr(self, key):
|
|
95
|
+
return getattr(self, key)
|
|
96
|
+
return default
|
|
97
|
+
|
|
98
|
+
def replace(self, **changes: Any) -> "SCNMFConfig":
|
|
99
|
+
values = self.to_dict()
|
|
100
|
+
values.update(changes)
|
|
101
|
+
values.pop("extra", None)
|
|
102
|
+
return SCNMFConfig.from_dict(values)
|
|
File without changes
|