scccvgben 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.
Files changed (96) hide show
  1. scccvgben-0.1.0/LICENSE +21 -0
  2. scccvgben-0.1.0/PKG-INFO +126 -0
  3. scccvgben-0.1.0/README.md +71 -0
  4. scccvgben-0.1.0/pyproject.toml +73 -0
  5. scccvgben-0.1.0/scccvgben/__init__.py +6 -0
  6. scccvgben-0.1.0/scccvgben/baselines/__init__.py +5 -0
  7. scccvgben-0.1.0/scccvgben/baselines/deep_methods.py +250 -0
  8. scccvgben-0.1.0/scccvgben/baselines/runner.py +207 -0
  9. scccvgben-0.1.0/scccvgben/baselines/sklearn_methods.py +86 -0
  10. scccvgben-0.1.0/scccvgben/biovalidation/__init__.py +29 -0
  11. scccvgben-0.1.0/scccvgben/biovalidation/case_definition.py +116 -0
  12. scccvgben-0.1.0/scccvgben/biovalidation/compose/__init__.py +11 -0
  13. scccvgben-0.1.0/scccvgben/biovalidation/compose/case_figure.py +186 -0
  14. scccvgben-0.1.0/scccvgben/biovalidation/compute/__init__.py +12 -0
  15. scccvgben-0.1.0/scccvgben/biovalidation/compute/case_run.py +170 -0
  16. scccvgben-0.1.0/scccvgben/biovalidation/compute/latent_gene_corr.py +100 -0
  17. scccvgben-0.1.0/scccvgben/biovalidation/compute/pathway.py +151 -0
  18. scccvgben-0.1.0/scccvgben/biovalidation/sidecar.py +270 -0
  19. scccvgben-0.1.0/scccvgben/biovalidation/visualize/__init__.py +19 -0
  20. scccvgben-0.1.0/scccvgben/biovalidation/visualize/case_style.py +34 -0
  21. scccvgben-0.1.0/scccvgben/biovalidation/visualize/dotplot.py +115 -0
  22. scccvgben-0.1.0/scccvgben/biovalidation/visualize/gene_grid.py +86 -0
  23. scccvgben-0.1.0/scccvgben/biovalidation/visualize/heatmap.py +84 -0
  24. scccvgben-0.1.0/scccvgben/biovalidation/visualize/panel.py +90 -0
  25. scccvgben-0.1.0/scccvgben/biovalidation/visualize/scatter.py +162 -0
  26. scccvgben-0.1.0/scccvgben/biovalidation/visualize/violin.py +79 -0
  27. scccvgben-0.1.0/scccvgben/config.py +22 -0
  28. scccvgben-0.1.0/scccvgben/data/__init__.py +5 -0
  29. scccvgben-0.1.0/scccvgben/data/datasets.csv +223 -0
  30. scccvgben-0.1.0/scccvgben/data/labels.py +58 -0
  31. scccvgben-0.1.0/scccvgben/data/loader.py +75 -0
  32. scccvgben-0.1.0/scccvgben/data/preprocessing.py +105 -0
  33. scccvgben-0.1.0/scccvgben/data/result_csv_normalizer.py +105 -0
  34. scccvgben-0.1.0/scccvgben/external/reference_core/__init__.py +15 -0
  35. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/CGVAE.py +180 -0
  36. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/CGVAE_agent.py +178 -0
  37. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/CGVAE_env.py +273 -0
  38. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/CGVAE_module.py +305 -0
  39. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/CGVAE_trainer.py +142 -0
  40. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/CODE/__init__.py +5 -0
  41. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/CODE/agent.py +338 -0
  42. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/CODE/environment.py +121 -0
  43. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/CODE/mixin.py +259 -0
  44. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/CODE/model.py +463 -0
  45. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/CODE/module.py +535 -0
  46. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/CODE/utils.py +140 -0
  47. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/__init__.py +5 -0
  48. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/mixin.py +356 -0
  49. scccvgben-0.1.0/scccvgben/external/reference_core/cgvae/utils.py +332 -0
  50. scccvgben-0.1.0/scccvgben/external/reference_core/dre.py +435 -0
  51. scccvgben-0.1.0/scccvgben/external/reference_core/lse.py +640 -0
  52. scccvgben-0.1.0/scccvgben/figures/__init__.py +75 -0
  53. scccvgben-0.1.0/scccvgben/figures/_long_form.py +150 -0
  54. scccvgben-0.1.0/scccvgben/figures/_naming.py +23 -0
  55. scccvgben-0.1.0/scccvgben/figures/_significance.py +248 -0
  56. scccvgben-0.1.0/scccvgben/figures/fonts.py +108 -0
  57. scccvgben-0.1.0/scccvgben/figures/metrics.py +318 -0
  58. scccvgben-0.1.0/scccvgben/figures/style.py +993 -0
  59. scccvgben-0.1.0/scccvgben/graphs/__init__.py +17 -0
  60. scccvgben-0.1.0/scccvgben/graphs/construction.py +205 -0
  61. scccvgben-0.1.0/scccvgben/models/__init__.py +4 -0
  62. scccvgben-0.1.0/scccvgben/models/decoders.py +82 -0
  63. scccvgben-0.1.0/scccvgben/models/encoder_registry.py +161 -0
  64. scccvgben-0.1.0/scccvgben/models/losses.py +65 -0
  65. scccvgben-0.1.0/scccvgben/models/scccvgben_model.py +173 -0
  66. scccvgben-0.1.0/scccvgben/stats/__init__.py +13 -0
  67. scccvgben-0.1.0/scccvgben/stats/tests.py +123 -0
  68. scccvgben-0.1.0/scccvgben/training/__init__.py +4 -0
  69. scccvgben-0.1.0/scccvgben/training/configs.py +47 -0
  70. scccvgben-0.1.0/scccvgben/training/dre.py +226 -0
  71. scccvgben-0.1.0/scccvgben/training/graph_sweep.py +158 -0
  72. scccvgben-0.1.0/scccvgben/training/lse.py +55 -0
  73. scccvgben-0.1.0/scccvgben/training/metrics.py +156 -0
  74. scccvgben-0.1.0/scccvgben/training/pair_sweep.py +174 -0
  75. scccvgben-0.1.0/scccvgben/training/prefetch.py +91 -0
  76. scccvgben-0.1.0/scccvgben/training/scccvgben_runner.py +239 -0
  77. scccvgben-0.1.0/scccvgben/training/trainer.py +91 -0
  78. scccvgben-0.1.0/scccvgben.egg-info/PKG-INFO +126 -0
  79. scccvgben-0.1.0/scccvgben.egg-info/SOURCES.txt +94 -0
  80. scccvgben-0.1.0/scccvgben.egg-info/dependency_links.txt +1 -0
  81. scccvgben-0.1.0/scccvgben.egg-info/requires.txt +38 -0
  82. scccvgben-0.1.0/scccvgben.egg-info/top_level.txt +1 -0
  83. scccvgben-0.1.0/setup.cfg +4 -0
  84. scccvgben-0.1.0/tests/test_audit_ai_tone.py +47 -0
  85. scccvgben-0.1.0/tests/test_audit_submission_ready.py +137 -0
  86. scccvgben-0.1.0/tests/test_dre_port.py +117 -0
  87. scccvgben-0.1.0/tests/test_encoder_registry.py +44 -0
  88. scccvgben-0.1.0/tests/test_fetch_geo_skeleton.py +269 -0
  89. scccvgben-0.1.0/tests/test_graph_constructions.py +52 -0
  90. scccvgben-0.1.0/tests/test_imports.py +12 -0
  91. scccvgben-0.1.0/tests/test_make_diff_vs_ccvgae.py +47 -0
  92. scccvgben-0.1.0/tests/test_public_surface_links.py +48 -0
  93. scccvgben-0.1.0/tests/test_scccvgben_model_forward.py +81 -0
  94. scccvgben-0.1.0/tests/test_smoke_pipelines.py +54 -0
  95. scccvgben-0.1.0/tests/test_stats.py +52 -0
  96. scccvgben-0.1.0/tests/test_symlinks.py +47 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 scCCVGBen 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,126 @@
1
+ Metadata-Version: 2.4
2
+ Name: scccvgben
3
+ Version: 0.1.0
4
+ Summary: Single-cell scCCVGBen Benchmark — multi-encoder, multi-graph, baseline comparison on 200 scRNA+scATAC datasets
5
+ Author: Zeyu Fu
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/PeterPonyu/scCCVGBen
8
+ Project-URL: Repository, https://github.com/PeterPonyu/scCCVGBen
9
+ Project-URL: Documentation, https://peterponyu.github.io/scCCVGBen/
10
+ Project-URL: Paper, https://doi.org/10.3389/fgene.2026.1822168
11
+ Keywords: single-cell,benchmark,graph neural network,variational autoencoder,scRNA-seq,scATAC-seq
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
18
+ Requires-Python: >=3.10
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: torch>=2.0
22
+ Requires-Dist: torch-geometric
23
+ Requires-Dist: scanpy
24
+ Requires-Dist: anndata
25
+ Requires-Dist: numpy
26
+ Requires-Dist: pandas
27
+ Requires-Dist: scipy
28
+ Requires-Dist: scikit-learn
29
+ Requires-Dist: matplotlib
30
+ Requires-Dist: gseapy
31
+ Requires-Dist: networkx
32
+ Requires-Dist: pyyaml
33
+ Requires-Dist: umap-learn
34
+ Requires-Dist: seaborn
35
+ Requires-Dist: psutil
36
+ Requires-Dist: tqdm
37
+ Provides-Extra: atac
38
+ Requires-Dist: episcanpy; extra == "atac"
39
+ Provides-Extra: geo
40
+ Requires-Dist: GEOparse>=2.0.3; extra == "geo"
41
+ Provides-Extra: dev
42
+ Requires-Dist: pytest; extra == "dev"
43
+ Requires-Dist: ruff; extra == "dev"
44
+ Requires-Dist: mypy; extra == "dev"
45
+ Provides-Extra: sparse
46
+ Requires-Dist: torch-sparse; extra == "sparse"
47
+ Provides-Extra: full
48
+ Requires-Dist: episcanpy; extra == "full"
49
+ Requires-Dist: GEOparse>=2.0.3; extra == "full"
50
+ Requires-Dist: torch-sparse; extra == "full"
51
+ Requires-Dist: scib; extra == "full"
52
+ Requires-Dist: scvi-tools; extra == "full"
53
+ Requires-Dist: torchdiffeq; extra == "full"
54
+ Dynamic: license-file
55
+
56
+ # scCCVGBen
57
+
58
+ A 200-dataset single-cell representation-learning benchmark and a Python
59
+ package for the centroid-coupled variational graph attention autoencoder
60
+ (100 scRNA-seq + 100 scATAC-seq, balanced).
61
+
62
+ The repository carries:
63
+
64
+ - the dataset catalogue with GEO-verified metadata,
65
+ - the method and metric registries,
66
+ - the Python package used to regenerate the benchmark,
67
+ - the Hugo source for the public site,
68
+ - the Next.js companion explorer (`webapp/`).
69
+
70
+ ## Install
71
+
72
+ ```bash
73
+ pip install scccvgben
74
+ ```
75
+
76
+ The reference graph model also needs `torch-sparse` (`pip install "scccvgben[sparse]"`, with a wheel that matches your PyTorch build). To regenerate the benchmark, clone the repository and run `pip install -e ".[dev,full]"`.
77
+
78
+ ## Reproduce
79
+
80
+ See [`REPRODUCE.md`](REPRODUCE.md). Sweep scripts are idempotent and resume
81
+ per `(dataset, method)` row.
82
+
83
+ ## Layout
84
+
85
+ - `scccvgben/` — Python package
86
+ - `scripts/` — data curation and sweep runners
87
+ - `data/` — dataset metadata CSVs
88
+ - `figures/` — generated figures (raw screenshots in `figures/site_shots/` stay local)
89
+ - `site/` — Hugo source for the public site
90
+ - `webapp/` — Next.js benchmark explorer
91
+ - `tests/` — smoke tests
92
+
93
+ ## Figures
94
+
95
+ - **Figure 1 — site and benchmark overview.** Render with `scripts/make_figure1_site.py`.
96
+ - **Figure 2 — model architecture and benchmark axes.** Render with `scripts/make_figure2_model_architecture.py`.
97
+ - Generated figure binaries are not committed by the figure-pipeline PR.
98
+
99
+ ## Sites
100
+
101
+ - Hugo public site: <https://peterponyu.github.io/scCCVGBen/>
102
+ - Next.js companion explorer: <https://peterponyu.github.io/scccvgben-next/>
103
+
104
+ ## Citation
105
+
106
+ If you use scCCVGBen, please cite the article:
107
+
108
+ > Fu Z, Fu J, Chen C, Zhang K, Wang J, Ran T, Wang S. scCCVGBen for benchmarking of single-cell representation learning anchored on a centroid-coupled variational graph attention autoencoder across scRNA-seq and scATAC-seq. *Frontiers in Genetics*. 2026;17:1822168. https://doi.org/10.3389/fgene.2026.1822168
109
+
110
+ ```bibtex
111
+ @article{fu2026scccvgben,
112
+ author = {Fu, Zeyu and Fu, Jiawei and Chen, Chunlin and Zhang, Keyang and Wang, Junping and Ran, Tianfei and Wang, Song},
113
+ title = {scCCVGBen for benchmarking of single-cell representation learning anchored on a centroid-coupled variational graph attention autoencoder across scRNA-seq and scATAC-seq},
114
+ journal = {Frontiers in Genetics},
115
+ volume = {17},
116
+ pages = {1822168},
117
+ year = {2026},
118
+ doi = {10.3389/fgene.2026.1822168}
119
+ }
120
+ ```
121
+
122
+ GitHub's "Cite this repository" button reads the same record from `CITATION.cff`.
123
+
124
+ ## License
125
+
126
+ MIT — see [`LICENSE`](LICENSE).
@@ -0,0 +1,71 @@
1
+ # scCCVGBen
2
+
3
+ A 200-dataset single-cell representation-learning benchmark and a Python
4
+ package for the centroid-coupled variational graph attention autoencoder
5
+ (100 scRNA-seq + 100 scATAC-seq, balanced).
6
+
7
+ The repository carries:
8
+
9
+ - the dataset catalogue with GEO-verified metadata,
10
+ - the method and metric registries,
11
+ - the Python package used to regenerate the benchmark,
12
+ - the Hugo source for the public site,
13
+ - the Next.js companion explorer (`webapp/`).
14
+
15
+ ## Install
16
+
17
+ ```bash
18
+ pip install scccvgben
19
+ ```
20
+
21
+ The reference graph model also needs `torch-sparse` (`pip install "scccvgben[sparse]"`, with a wheel that matches your PyTorch build). To regenerate the benchmark, clone the repository and run `pip install -e ".[dev,full]"`.
22
+
23
+ ## Reproduce
24
+
25
+ See [`REPRODUCE.md`](REPRODUCE.md). Sweep scripts are idempotent and resume
26
+ per `(dataset, method)` row.
27
+
28
+ ## Layout
29
+
30
+ - `scccvgben/` — Python package
31
+ - `scripts/` — data curation and sweep runners
32
+ - `data/` — dataset metadata CSVs
33
+ - `figures/` — generated figures (raw screenshots in `figures/site_shots/` stay local)
34
+ - `site/` — Hugo source for the public site
35
+ - `webapp/` — Next.js benchmark explorer
36
+ - `tests/` — smoke tests
37
+
38
+ ## Figures
39
+
40
+ - **Figure 1 — site and benchmark overview.** Render with `scripts/make_figure1_site.py`.
41
+ - **Figure 2 — model architecture and benchmark axes.** Render with `scripts/make_figure2_model_architecture.py`.
42
+ - Generated figure binaries are not committed by the figure-pipeline PR.
43
+
44
+ ## Sites
45
+
46
+ - Hugo public site: <https://peterponyu.github.io/scCCVGBen/>
47
+ - Next.js companion explorer: <https://peterponyu.github.io/scccvgben-next/>
48
+
49
+ ## Citation
50
+
51
+ If you use scCCVGBen, please cite the article:
52
+
53
+ > Fu Z, Fu J, Chen C, Zhang K, Wang J, Ran T, Wang S. scCCVGBen for benchmarking of single-cell representation learning anchored on a centroid-coupled variational graph attention autoencoder across scRNA-seq and scATAC-seq. *Frontiers in Genetics*. 2026;17:1822168. https://doi.org/10.3389/fgene.2026.1822168
54
+
55
+ ```bibtex
56
+ @article{fu2026scccvgben,
57
+ author = {Fu, Zeyu and Fu, Jiawei and Chen, Chunlin and Zhang, Keyang and Wang, Junping and Ran, Tianfei and Wang, Song},
58
+ title = {scCCVGBen for benchmarking of single-cell representation learning anchored on a centroid-coupled variational graph attention autoencoder across scRNA-seq and scATAC-seq},
59
+ journal = {Frontiers in Genetics},
60
+ volume = {17},
61
+ pages = {1822168},
62
+ year = {2026},
63
+ doi = {10.3389/fgene.2026.1822168}
64
+ }
65
+ ```
66
+
67
+ GitHub's "Cite this repository" button reads the same record from `CITATION.cff`.
68
+
69
+ ## License
70
+
71
+ MIT — see [`LICENSE`](LICENSE).
@@ -0,0 +1,73 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "scccvgben"
7
+ version = "0.1.0"
8
+ description = "Single-cell scCCVGBen Benchmark — multi-encoder, multi-graph, baseline comparison on 200 scRNA+scATAC datasets"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = {text = "MIT"}
12
+ authors = [{name = "Zeyu Fu"}]
13
+ keywords = ["single-cell", "benchmark", "graph neural network", "variational autoencoder", "scRNA-seq", "scATAC-seq"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Science/Research",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Operating System :: OS Independent",
19
+ "Programming Language :: Python :: 3",
20
+ "Topic :: Scientific/Engineering :: Bio-Informatics",
21
+ ]
22
+ dependencies = [
23
+ "torch>=2.0",
24
+ "torch-geometric",
25
+ "scanpy",
26
+ "anndata",
27
+ "numpy",
28
+ "pandas",
29
+ "scipy",
30
+ "scikit-learn",
31
+ "matplotlib",
32
+ "gseapy",
33
+ "networkx",
34
+ "pyyaml",
35
+ "umap-learn",
36
+ "seaborn",
37
+ "psutil",
38
+ "tqdm",
39
+ ]
40
+
41
+ [project.optional-dependencies]
42
+ atac = ["episcanpy"]
43
+ geo = ["GEOparse>=2.0.3"]
44
+ dev = ["pytest", "ruff", "mypy"]
45
+ sparse = ["torch-sparse"]
46
+ full = ["episcanpy", "GEOparse>=2.0.3", "torch-sparse", "scib", "scvi-tools", "torchdiffeq"]
47
+
48
+ [project.urls]
49
+ Homepage = "https://github.com/PeterPonyu/scCCVGBen"
50
+ Repository = "https://github.com/PeterPonyu/scCCVGBen"
51
+ Documentation = "https://peterponyu.github.io/scCCVGBen/"
52
+ Paper = "https://doi.org/10.3389/fgene.2026.1822168"
53
+
54
+ [tool.setuptools.packages.find]
55
+ where = ["."]
56
+ include = ["scccvgben*"]
57
+ exclude = ["tests*", "scripts*", "site*", "workspace*"]
58
+
59
+ [tool.setuptools.package-data]
60
+ scccvgben = ["data/*.csv"]
61
+
62
+ [tool.ruff]
63
+ line-length = 100
64
+ target-version = "py310"
65
+
66
+ [tool.pytest.ini_options]
67
+ markers = [
68
+ "integration: end-to-end pipeline smoke tests (skipped by default, use -m integration to run)",
69
+ ]
70
+
71
+ [tool.mypy]
72
+ python_version = "3.10"
73
+ ignore_missing_imports = true
@@ -0,0 +1,6 @@
1
+ __version__ = "0.1.0"
2
+
3
+ try:
4
+ from .models import ScCCVGBenModel, ENCODER_REGISTRY
5
+ except ImportError:
6
+ pass
@@ -0,0 +1,5 @@
1
+ """baselines — Classical and deep generative baseline methods for scCCVGBen."""
2
+
3
+ from scccvgben.baselines.runner import run_baseline, SUPPORTED_BASELINES
4
+
5
+ __all__ = ["run_baseline", "SUPPORTED_BASELINES"]
@@ -0,0 +1,250 @@
1
+ """deep_methods.py — Deep generative baselines with ELBO variants.
2
+
3
+ Each method follows the convention:
4
+ run_<method>(X: np.ndarray, n_components: int = 10) -> np.ndarray
5
+
6
+ Returns z_mean (latent mean) of shape (n_cells, n_components).
7
+ All tiny VAEs: encoder MLP → (mean, logvar) → decoder MLP.
8
+ Training: 50 epochs, Adam lr=1e-4, batch size = min(256, N).
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import logging
14
+
15
+ import numpy as np
16
+ import torch
17
+ import torch.nn as nn
18
+ import torch.nn.functional as F
19
+ from torch.utils.data import DataLoader, TensorDataset
20
+
21
+ log = logging.getLogger(__name__)
22
+
23
+ _EPOCHS = 200
24
+ _LR = 1e-4
25
+ _LATENT_DIM = 10
26
+ _HIDDEN = 128
27
+
28
+
29
+ # ──────────────────────────────────────────────────────────────────────────────
30
+ # Shared building blocks
31
+ # ──────────────────────────────────────────────────────────────────────────────
32
+
33
+ class _BaseVAE(nn.Module):
34
+ """Minimal VAE backbone shared by all deep baselines."""
35
+
36
+ def __init__(self, input_dim: int, hidden: int, latent_dim: int) -> None:
37
+ super().__init__()
38
+ self.encoder_fc = nn.Sequential(
39
+ nn.Linear(input_dim, hidden), nn.ReLU(),
40
+ nn.Linear(hidden, hidden), nn.ReLU(),
41
+ )
42
+ self.fc_mean = nn.Linear(hidden, latent_dim)
43
+ self.fc_logvar = nn.Linear(hidden, latent_dim)
44
+ self.decoder = nn.Sequential(
45
+ nn.Linear(latent_dim, hidden), nn.ReLU(),
46
+ nn.Linear(hidden, input_dim),
47
+ )
48
+
49
+ def encode(self, x: torch.Tensor):
50
+ h = self.encoder_fc(x)
51
+ return self.fc_mean(h), self.fc_logvar(h)
52
+
53
+ def reparameterise(self, mean: torch.Tensor, logvar: torch.Tensor) -> torch.Tensor:
54
+ std = torch.exp(0.5 * logvar)
55
+ return mean + std * torch.randn_like(std)
56
+
57
+ def decode(self, z: torch.Tensor) -> torch.Tensor:
58
+ return self.decoder(z)
59
+
60
+ def forward(self, x):
61
+ mean, logvar = self.encode(x)
62
+ z = self.reparameterise(mean, logvar)
63
+ x_hat = self.decode(z)
64
+ return x_hat, mean, logvar
65
+
66
+
67
+ def _standard_elbo(x, x_hat, mean, logvar):
68
+ recon = F.mse_loss(x_hat, x, reduction="sum")
69
+ kl = -0.5 * torch.sum(1 + logvar - mean.pow(2) - logvar.exp())
70
+ return recon + kl
71
+
72
+
73
+ def _train_vae(
74
+ model: _BaseVAE,
75
+ X: np.ndarray,
76
+ loss_fn,
77
+ epochs: int = _EPOCHS,
78
+ lr: float = _LR,
79
+ ) -> np.ndarray:
80
+ """Generic train loop; returns z_mean for all cells."""
81
+ torch.manual_seed(42)
82
+ device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
83
+ model = model.to(device)
84
+
85
+ Xt = torch.tensor(X, dtype=torch.float32)
86
+ bs = min(256, len(Xt))
87
+ loader = DataLoader(TensorDataset(Xt), batch_size=bs, shuffle=True)
88
+
89
+ opt = torch.optim.Adam(model.parameters(), lr=lr)
90
+ model.train()
91
+ for _ in range(epochs):
92
+ for (batch,) in loader:
93
+ batch = batch.to(device)
94
+ x_hat, mean, logvar = model(batch)
95
+ loss = loss_fn(batch, x_hat, mean, logvar)
96
+ opt.zero_grad()
97
+ loss.backward()
98
+ opt.step()
99
+
100
+ model.eval()
101
+ with torch.no_grad():
102
+ mean_all, _ = model.encode(Xt.to(device))
103
+ return mean_all.cpu().numpy()
104
+
105
+
106
+ # ──────────────────────────────────────────────────────────────────────────────
107
+ # DIPVAE (Disentangled Inferred Prior)
108
+ # ELBO + lambda * (off-diagonal covariance terms of E[z] penalised)
109
+ # ──────────────────────────────────────────────────────────────────────────────
110
+
111
+ def run_DIPVAE(X: np.ndarray, n_components: int = _LATENT_DIM) -> np.ndarray:
112
+ """DIPVAE: standard ELBO + DIP-II covariance penalty (lambda=10)."""
113
+ lam = 10.0
114
+
115
+ def loss_fn(x, x_hat, mean, logvar):
116
+ base = _standard_elbo(x, x_hat, mean, logvar)
117
+ # DIP-II: penalise off-diagonal entries of Cov[E[z]]
118
+ cov = torch.mm(mean.T, mean) / mean.shape[0]
119
+ off_diag = cov - torch.diag(torch.diag(cov))
120
+ dip = lam * off_diag.pow(2).sum()
121
+ return base + dip
122
+
123
+ model = _BaseVAE(X.shape[1], _HIDDEN, n_components)
124
+ return _train_vae(model, X, loss_fn)
125
+
126
+
127
+ # ──────────────────────────────────────────────────────────────────────────────
128
+ # InfoVAE (Mutual Information VAE / MMD-VAE)
129
+ # ELBO + alpha * MMD(q(z) || p(z))
130
+ # ──────────────────────────────────────────────────────────────────────────────
131
+
132
+ def _rbf_kernel(x: torch.Tensor, y: torch.Tensor, sigma: float = 1.0) -> torch.Tensor:
133
+ dist = torch.cdist(x, y).pow(2)
134
+ return torch.exp(-dist / (2 * sigma ** 2))
135
+
136
+
137
+ def _mmd(z: torch.Tensor) -> torch.Tensor:
138
+ n = z.shape[0]
139
+ z_prior = torch.randn_like(z)
140
+ kzz = _rbf_kernel(z, z).sum() / (n * n)
141
+ kpp = _rbf_kernel(z_prior, z_prior).sum() / (n * n)
142
+ kzp = _rbf_kernel(z, z_prior).sum() / (n * n)
143
+ return kzz + kpp - 2 * kzp
144
+
145
+
146
+ def run_InfoVAE(X: np.ndarray, n_components: int = _LATENT_DIM) -> np.ndarray:
147
+ """InfoVAE (MMD-VAE): ELBO + 100 * MMD(q(z)||N(0,I))."""
148
+ alpha = 100.0
149
+
150
+ def loss_fn(x, x_hat, mean, logvar):
151
+ z = mean + torch.exp(0.5 * logvar) * torch.randn_like(mean)
152
+ return _standard_elbo(x, x_hat, mean, logvar) + alpha * _mmd(z)
153
+
154
+ model = _BaseVAE(X.shape[1], _HIDDEN, n_components)
155
+ return _train_vae(model, X, loss_fn)
156
+
157
+
158
+ # ──────────────────────────────────────────────────────────────────────────────
159
+ # TCVAE (Total Correlation VAE)
160
+ # ELBO - beta * TC(q(z)) using minibatch-weighted estimator
161
+ # ──────────────────────────────────────────────────────────────────────────────
162
+
163
+ def run_TCVAE(X: np.ndarray, n_components: int = _LATENT_DIM) -> np.ndarray:
164
+ """TCVAE: decomposes ELBO; penalises total-correlation term (beta=6)."""
165
+ beta = 6.0
166
+ N = float(len(X))
167
+
168
+ def loss_fn(x, x_hat, mean, logvar):
169
+ recon = F.mse_loss(x_hat, x, reduction="sum")
170
+ # log q(z|x) per sample
171
+ log_q_zx = -0.5 * (logvar + (mean - mean).pow(2) / logvar.exp() + np.log(2 * np.pi)).sum(-1)
172
+ # log p(z)
173
+ log_pz = -0.5 * (mean.pow(2) + logvar.exp() + np.log(2 * np.pi)).sum(-1)
174
+ # minibatch TC approximation (subtract aggregate)
175
+ _z = mean + torch.exp(0.5 * logvar) * torch.randn_like(mean)
176
+ log_prod_qz = -0.5 * (
177
+ _z.unsqueeze(0) - mean.unsqueeze(1)
178
+ ).pow(2).div(logvar.exp().unsqueeze(1)).sum(-1).logsumexp(0) + np.log(N)
179
+ tc = (log_q_zx - log_prod_qz - log_pz).mean()
180
+ kl = -0.5 * (1 + logvar - mean.pow(2) - logvar.exp()).sum()
181
+ return recon + kl + (beta - 1) * tc
182
+
183
+ model = _BaseVAE(X.shape[1], _HIDDEN, n_components)
184
+ return _train_vae(model, X, loss_fn)
185
+
186
+
187
+ # ──────────────────────────────────────────────────────────────────────────────
188
+ # HighBetaVAE (beta-VAE with large beta)
189
+ # ELBO with beta=10 KL weight
190
+ # ──────────────────────────────────────────────────────────────────────────────
191
+
192
+ def run_HighBetaVAE(X: np.ndarray, n_components: int = _LATENT_DIM) -> np.ndarray:
193
+ """beta-VAE with beta=10: over-penalises KL to encourage disentanglement."""
194
+ beta = 10.0
195
+
196
+ def loss_fn(x, x_hat, mean, logvar):
197
+ recon = F.mse_loss(x_hat, x, reduction="sum")
198
+ kl = -0.5 * torch.sum(1 + logvar - mean.pow(2) - logvar.exp())
199
+ return recon + beta * kl
200
+
201
+ model = _BaseVAE(X.shape[1], _HIDDEN, n_components)
202
+ return _train_vae(model, X, loss_fn)
203
+
204
+
205
+ # ──────────────────────────────────────────────────────────────────────────────
206
+ # scVI wrapper
207
+ # ──────────────────────────────────────────────────────────────────────────────
208
+
209
+ def run_scVI(X: np.ndarray, n_components: int = _LATENT_DIM) -> np.ndarray:
210
+ """scVI latent via scvi-tools (requires scvi-tools installed).
211
+
212
+ X should be raw integer count matrix (n_cells × n_genes).
213
+ Returns z_mean of shape (n_cells, n_components).
214
+ """
215
+ try:
216
+ import scvi
217
+ import anndata as ad
218
+ except ImportError as exc:
219
+ raise NotImplementedError(
220
+ "scVI requires scvi-tools and anndata. "
221
+ "Install with: pip install scvi-tools anndata. "
222
+ f"Original error: {exc}"
223
+ ) from exc
224
+
225
+ import pandas as pd
226
+
227
+ n_cells, n_genes = X.shape
228
+ adata = ad.AnnData(
229
+ X=X.astype(np.float32),
230
+ obs=pd.DataFrame(index=[str(i) for i in range(n_cells)]),
231
+ var=pd.DataFrame(index=[str(j) for j in range(n_genes)]),
232
+ )
233
+ scvi.model.SCVI.setup_anndata(adata)
234
+ vae = scvi.model.SCVI(adata, n_latent=n_components)
235
+ vae.train(max_epochs=_EPOCHS, plan_kwargs={"lr": _LR})
236
+ latent = vae.get_latent_representation()
237
+ return np.array(latent, dtype=np.float32)
238
+
239
+
240
+ # ──────────────────────────────────────────────────────────────────────────────
241
+ # Dispatch registry
242
+ # ──────────────────────────────────────────────────────────────────────────────
243
+
244
+ DEEP_REGISTRY: dict[str, callable] = {
245
+ "scVI": run_scVI,
246
+ "DIP": run_DIPVAE,
247
+ "INFO": run_InfoVAE,
248
+ "TC": run_TCVAE,
249
+ "highBeta": run_HighBetaVAE,
250
+ }