mccvae 0.0.1__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 (72) hide show
  1. mccvae-0.0.1/LICENSE +21 -0
  2. mccvae-0.0.1/PKG-INFO +185 -0
  3. mccvae-0.0.1/README.md +144 -0
  4. mccvae-0.0.1/mccvae/__init__.py +5 -0
  5. mccvae-0.0.1/mccvae/agent.py +288 -0
  6. mccvae-0.0.1/mccvae/distributions/EuclideanNormal/__init__.py +15 -0
  7. mccvae-0.0.1/mccvae/distributions/EuclideanNormal/arguments.py +3 -0
  8. mccvae-0.0.1/mccvae/distributions/EuclideanNormal/distribution.py +26 -0
  9. mccvae-0.0.1/mccvae/distributions/EuclideanNormal/layers.py +35 -0
  10. mccvae-0.0.1/mccvae/distributions/EuclideanNormal/prior.py +18 -0
  11. mccvae-0.0.1/mccvae/distributions/HWNormal/__init__.py +15 -0
  12. mccvae-0.0.1/mccvae/distributions/HWNormal/arguments.py +3 -0
  13. mccvae-0.0.1/mccvae/distributions/HWNormal/distribution.py +56 -0
  14. mccvae-0.0.1/mccvae/distributions/HWNormal/layers.py +44 -0
  15. mccvae-0.0.1/mccvae/distributions/HWNormal/prior.py +24 -0
  16. mccvae-0.0.1/mccvae/distributions/LearnablePGMNormal/__init__.py +24 -0
  17. mccvae-0.0.1/mccvae/distributions/LearnablePGMNormal/arguments.py +4 -0
  18. mccvae-0.0.1/mccvae/distributions/LearnablePGMNormal/distribution.py +81 -0
  19. mccvae-0.0.1/mccvae/distributions/LearnablePGMNormal/layers.py +218 -0
  20. mccvae-0.0.1/mccvae/distributions/LearnablePGMNormal/prior.py +18 -0
  21. mccvae-0.0.1/mccvae/distributions/PGMNormal/__init__.py +24 -0
  22. mccvae-0.0.1/mccvae/distributions/PGMNormal/arguments.py +4 -0
  23. mccvae-0.0.1/mccvae/distributions/PGMNormal/distribution.py +71 -0
  24. mccvae-0.0.1/mccvae/distributions/PGMNormal/layers.py +82 -0
  25. mccvae-0.0.1/mccvae/distributions/PGMNormal/prior.py +18 -0
  26. mccvae-0.0.1/mccvae/distributions/PoincareNormal/__init__.py +16 -0
  27. mccvae-0.0.1/mccvae/distributions/PoincareNormal/arguments.py +4 -0
  28. mccvae-0.0.1/mccvae/distributions/PoincareNormal/ars.py +133 -0
  29. mccvae-0.0.1/mccvae/distributions/PoincareNormal/distribution.py +58 -0
  30. mccvae-0.0.1/mccvae/distributions/PoincareNormal/hyperbolic_radius.py +371 -0
  31. mccvae-0.0.1/mccvae/distributions/PoincareNormal/hyperbolic_uniform.py +43 -0
  32. mccvae-0.0.1/mccvae/distributions/PoincareNormal/layers.py +48 -0
  33. mccvae-0.0.1/mccvae/distributions/PoincareNormal/prior.py +18 -0
  34. mccvae-0.0.1/mccvae/distributions/__init__.py +0 -0
  35. mccvae-0.0.1/mccvae/distributions/utils.py +21 -0
  36. mccvae-0.0.1/mccvae/environment.py +361 -0
  37. mccvae-0.0.1/mccvae/mixin.py +671 -0
  38. mccvae-0.0.1/mccvae/model.py +480 -0
  39. mccvae-0.0.1/mccvae/module.py +519 -0
  40. mccvae-0.0.1/mccvae/palantir/__init__.py +28 -0
  41. mccvae-0.0.1/mccvae/palantir/core.py +289 -0
  42. mccvae-0.0.1/mccvae/palantir/diffusion.py +254 -0
  43. mccvae-0.0.1/mccvae/palantir/magic.py +50 -0
  44. mccvae-0.0.1/mccvae/palantir/pseudotime.py +431 -0
  45. mccvae-0.0.1/mccvae/palantir/test_palantir.py +140 -0
  46. mccvae-0.0.1/mccvae/palantir/utils.py +193 -0
  47. mccvae-0.0.1/mccvae/unified_models/__init__.py +67 -0
  48. mccvae-0.0.1/mccvae/unified_models/base_model.py +361 -0
  49. mccvae-0.0.1/mccvae/unified_models/cellblast_model.py +349 -0
  50. mccvae-0.0.1/mccvae/unified_models/clear_model.py +258 -0
  51. mccvae-0.0.1/mccvae/unified_models/gmvae_model.py +560 -0
  52. mccvae-0.0.1/mccvae/unified_models/scagcl_model.py +486 -0
  53. mccvae-0.0.1/mccvae/unified_models/scalex_model.py +352 -0
  54. mccvae-0.0.1/mccvae/unified_models/scdac_model.py +269 -0
  55. mccvae-0.0.1/mccvae/unified_models/scdeepcluster_model.py +300 -0
  56. mccvae-0.0.1/mccvae/unified_models/scdhmap_model.py +454 -0
  57. mccvae-0.0.1/mccvae/unified_models/scdiffusion_model.py +479 -0
  58. mccvae-0.0.1/mccvae/unified_models/scgcc_model.py +374 -0
  59. mccvae-0.0.1/mccvae/unified_models/scgnn_model.py +210 -0
  60. mccvae-0.0.1/mccvae/unified_models/scgpcl_model.py +665 -0
  61. mccvae-0.0.1/mccvae/unified_models/schsc_model.py +626 -0
  62. mccvae-0.0.1/mccvae/unified_models/scsimgcl_model.py +471 -0
  63. mccvae-0.0.1/mccvae/unified_models/scsmd_model.py +387 -0
  64. mccvae-0.0.1/mccvae/unified_models/sivae_model.py +460 -0
  65. mccvae-0.0.1/mccvae/utils.py +228 -0
  66. mccvae-0.0.1/mccvae.egg-info/PKG-INFO +185 -0
  67. mccvae-0.0.1/mccvae.egg-info/SOURCES.txt +70 -0
  68. mccvae-0.0.1/mccvae.egg-info/dependency_links.txt +1 -0
  69. mccvae-0.0.1/mccvae.egg-info/requires.txt +24 -0
  70. mccvae-0.0.1/mccvae.egg-info/top_level.txt +1 -0
  71. mccvae-0.0.1/pyproject.toml +45 -0
  72. mccvae-0.0.1/setup.cfg +4 -0
mccvae-0.0.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Zeyu Fu
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.
mccvae-0.0.1/PKG-INFO ADDED
@@ -0,0 +1,185 @@
1
+ Metadata-Version: 2.4
2
+ Name: mccvae
3
+ Version: 0.0.1
4
+ Summary: MCCVAE: momentum contrastive coupling unifies discrete and continuous structure in single-cell omics
5
+ Author: Zeyu Fu
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/PeterPonyu/MCCVAE
8
+ Project-URL: Repository, https://github.com/PeterPonyu/MCCVAE
9
+ Keywords: single-cell,variational autoencoder,contrastive learning,scRNA-seq,scATAC-seq
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
16
+ Requires-Python: >=3.9
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: torch
20
+ Requires-Dist: torchdiffeq
21
+ Requires-Dist: geoopt
22
+ Requires-Dist: numpy
23
+ Requires-Dist: scipy
24
+ Requires-Dist: pandas
25
+ Requires-Dist: scikit-learn
26
+ Requires-Dist: anndata
27
+ Requires-Dist: scanpy
28
+ Requires-Dist: tqdm
29
+ Provides-Extra: metrics
30
+ Requires-Dist: scib; extra == "metrics"
31
+ Requires-Dist: python-igraph; extra == "metrics"
32
+ Requires-Dist: leidenalg; extra == "metrics"
33
+ Provides-Extra: baselines
34
+ Requires-Dist: torch-geometric; extra == "baselines"
35
+ Provides-Extra: all
36
+ Requires-Dist: scib; extra == "all"
37
+ Requires-Dist: python-igraph; extra == "all"
38
+ Requires-Dist: leidenalg; extra == "all"
39
+ Requires-Dist: torch-geometric; extra == "all"
40
+ Dynamic: license-file
41
+
42
+
43
+ <div align="center">
44
+ <a href="https://peterponyu.github.io/">
45
+ <img src="https://peterponyu.github.io/assets/badges/MCCVAE.svg" width="64" alt="ZF Lab · MCCVAE">
46
+ </a>
47
+ </div>
48
+
49
+ # MCC: Momentum Contrastive Coupling
50
+
51
+ [![GitHub Pages](https://img.shields.io/badge/Web%20Portal-Live-brightgreen)](https://peterponyu.github.io/MCCVAE/)
52
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
53
+
54
+ **Interactive Benchmarking Portal:** [https://peterponyu.github.io/MCCVAE/](https://peterponyu.github.io/MCCVAE/)
55
+
56
+ **Publication status:** Published in *Biomedical Signal Processing and Control*.
57
+
58
+ **Fu, Z.**, Chen, C., Zhang, K. (2026). Islands and bridges: Momentum contrastive coupling unifies discrete and continuous structure in single-cell omics. *Biomedical Signal Processing and Control*, 122, 110376. [DOI](https://doi.org/10.1016/j.bspc.2026.110376) · [ScienceDirect](https://www.sciencedirect.com/science/article/pii/S1746809426009304)
59
+
60
+ MCC is a deep learning framework for single-cell genomics analysis. It combines a Momentum Contrastive (MoCo) module with an information-bottleneck coupling within a Variational Autoencoder (VAE) framework.
61
+
62
+ ## Features
63
+
64
+ - **Momentum Contrastive Learning:** Uses MoCo with InfoNCE loss, momentum-updated encoders, and memory queues for contrastive representation learning.
65
+ - **Information Bottleneck Coupling:** Compresses and refines latent codes through a low-dimensional bottleneck layer.
66
+ - **Dual Reconstruction Pathways:** Two reconstruction paths - direct from primary latent representation and through the information bottleneck.
67
+ - **Multiple Modalities:** Supports scRNA-seq and scATAC-seq data.
68
+
69
+ ## Installation
70
+
71
+ Install the package from PyPI:
72
+
73
+ ```bash
74
+ pip install mccvae
75
+ # benchmark metrics and graph baselines
76
+ pip install "mccvae[all]"
77
+ ```
78
+
79
+ To run the web interface, install from source:
80
+
81
+ 1. **Clone the repository:**
82
+ ```bash
83
+ git clone https://github.com/PeterPonyu/MCCVAE.git
84
+ cd MCCVAE
85
+ ```
86
+ 2. **Install the required dependencies:**
87
+ ```bash
88
+ pip install -r requirements.txt
89
+ ```
90
+
91
+ ## UI
92
+
93
+ Visualization training
94
+
95
+ ```bash
96
+ python start_servers.py
97
+ ```
98
+
99
+ ## Usage
100
+
101
+ Use the `Agent` class to train models and extract latent representations.
102
+
103
+ ```python
104
+ import scanpy as sc
105
+ from mccvae import Agent
106
+
107
+ # Load data
108
+ adata = sc.read_h5ad("your_data.h5ad")
109
+
110
+ # Initialize agent
111
+ agent = Agent(
112
+ adata=adata,
113
+ layer="counts",
114
+ latent_dim=10,
115
+ use_moco=True,
116
+ irecon=1.
117
+ )
118
+
119
+ # Train
120
+ agent.fit(epochs=1000)
121
+
122
+ # Extract representations
123
+ latent_representations = agent.get_latent() # Shape: (n_cells, latent_dim)
124
+ bottleneck_embeddings = agent.get_bottleneck() # Shape: (n_cells, i_dim)
125
+ refined_embeddings = agent.get_refined() # Shape: (n_cells, latent_dim)
126
+ ```
127
+
128
+ **Embeddings:**
129
+ - `get_latent()`: Primary latent representations (z) with dimension `latent_dim`
130
+ - `get_bottleneck()` or `get_iembed()`: Compressed bottleneck (l_e) with dimension `i_dim`
131
+ - `get_refined()`: Refined representations (l_d) with dimension `latent_dim`
132
+
133
+ ## Architecture
134
+
135
+ The framework consists of three components:
136
+
137
+ ### VAE Backbone
138
+ - **Query Encoder**: Maps input to latent representation z
139
+ - **Decoder**: Reconstructs data from latent representations
140
+ - **Loss**: Negative binomial reconstruction + KL divergence
141
+
142
+ ### MoCo Component
143
+ - **Momentum Encoder**: Parameters updated via exponential moving average
144
+ - **Memory Queue**: FIFO mechanism for negative samples
145
+ - **InfoNCE Loss**: Contrastive loss with L2-normalized embeddings
146
+
147
+ ### Coupling Component
148
+ - **Information Bottleneck**: z → l_e → l_d pathway
149
+ - l_e: Compressed representation via `bottleneck_encoder` (dimension: `i_dim`)
150
+ - l_d: Refined representation via `bottleneck_decoder` (dimension: `latent_dim`)
151
+ - **Secondary Reconstruction**: Reconstruction through l_d
152
+
153
+ ## Loss Function
154
+
155
+ The MCC objective combines four loss components:
156
+
157
+ ```
158
+ L_MCC = L_NB + β·L_KLD + α·L_MoCo + γ·L_Cou
159
+ ```
160
+
161
+ - **L_NB**: Negative binomial reconstruction loss (z → reconstruction)
162
+ - **L_KLD**: KL divergence regularization
163
+ - **L_MoCo**: InfoNCE contrastive loss
164
+ - **L_Cou**: Coupling reconstruction loss (z → l_e → l_d → reconstruction)
165
+
166
+
167
+ ## Citation
168
+
169
+ If you use MCCVAE or the MCC benchmark portal, please cite:
170
+
171
+ ```bibtex
172
+ @article{fu2026islands,
173
+ title = {Islands and bridges: Momentum contrastive coupling unifies discrete and continuous structure in single-cell omics},
174
+ author = {Fu, Zeyu and Chen, Chunlin and Zhang, Keyang},
175
+ journal = {Biomedical Signal Processing and Control},
176
+ volume = {122},
177
+ pages = {110376},
178
+ year = {2026},
179
+ doi = {10.1016/j.bspc.2026.110376}
180
+ }
181
+ ```
182
+
183
+ ## License
184
+
185
+ This project is licensed under the MIT License - see the LICENSE file for details.
mccvae-0.0.1/README.md ADDED
@@ -0,0 +1,144 @@
1
+
2
+ <div align="center">
3
+ <a href="https://peterponyu.github.io/">
4
+ <img src="https://peterponyu.github.io/assets/badges/MCCVAE.svg" width="64" alt="ZF Lab · MCCVAE">
5
+ </a>
6
+ </div>
7
+
8
+ # MCC: Momentum Contrastive Coupling
9
+
10
+ [![GitHub Pages](https://img.shields.io/badge/Web%20Portal-Live-brightgreen)](https://peterponyu.github.io/MCCVAE/)
11
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
12
+
13
+ **Interactive Benchmarking Portal:** [https://peterponyu.github.io/MCCVAE/](https://peterponyu.github.io/MCCVAE/)
14
+
15
+ **Publication status:** Published in *Biomedical Signal Processing and Control*.
16
+
17
+ **Fu, Z.**, Chen, C., Zhang, K. (2026). Islands and bridges: Momentum contrastive coupling unifies discrete and continuous structure in single-cell omics. *Biomedical Signal Processing and Control*, 122, 110376. [DOI](https://doi.org/10.1016/j.bspc.2026.110376) · [ScienceDirect](https://www.sciencedirect.com/science/article/pii/S1746809426009304)
18
+
19
+ MCC is a deep learning framework for single-cell genomics analysis. It combines a Momentum Contrastive (MoCo) module with an information-bottleneck coupling within a Variational Autoencoder (VAE) framework.
20
+
21
+ ## Features
22
+
23
+ - **Momentum Contrastive Learning:** Uses MoCo with InfoNCE loss, momentum-updated encoders, and memory queues for contrastive representation learning.
24
+ - **Information Bottleneck Coupling:** Compresses and refines latent codes through a low-dimensional bottleneck layer.
25
+ - **Dual Reconstruction Pathways:** Two reconstruction paths - direct from primary latent representation and through the information bottleneck.
26
+ - **Multiple Modalities:** Supports scRNA-seq and scATAC-seq data.
27
+
28
+ ## Installation
29
+
30
+ Install the package from PyPI:
31
+
32
+ ```bash
33
+ pip install mccvae
34
+ # benchmark metrics and graph baselines
35
+ pip install "mccvae[all]"
36
+ ```
37
+
38
+ To run the web interface, install from source:
39
+
40
+ 1. **Clone the repository:**
41
+ ```bash
42
+ git clone https://github.com/PeterPonyu/MCCVAE.git
43
+ cd MCCVAE
44
+ ```
45
+ 2. **Install the required dependencies:**
46
+ ```bash
47
+ pip install -r requirements.txt
48
+ ```
49
+
50
+ ## UI
51
+
52
+ Visualization training
53
+
54
+ ```bash
55
+ python start_servers.py
56
+ ```
57
+
58
+ ## Usage
59
+
60
+ Use the `Agent` class to train models and extract latent representations.
61
+
62
+ ```python
63
+ import scanpy as sc
64
+ from mccvae import Agent
65
+
66
+ # Load data
67
+ adata = sc.read_h5ad("your_data.h5ad")
68
+
69
+ # Initialize agent
70
+ agent = Agent(
71
+ adata=adata,
72
+ layer="counts",
73
+ latent_dim=10,
74
+ use_moco=True,
75
+ irecon=1.
76
+ )
77
+
78
+ # Train
79
+ agent.fit(epochs=1000)
80
+
81
+ # Extract representations
82
+ latent_representations = agent.get_latent() # Shape: (n_cells, latent_dim)
83
+ bottleneck_embeddings = agent.get_bottleneck() # Shape: (n_cells, i_dim)
84
+ refined_embeddings = agent.get_refined() # Shape: (n_cells, latent_dim)
85
+ ```
86
+
87
+ **Embeddings:**
88
+ - `get_latent()`: Primary latent representations (z) with dimension `latent_dim`
89
+ - `get_bottleneck()` or `get_iembed()`: Compressed bottleneck (l_e) with dimension `i_dim`
90
+ - `get_refined()`: Refined representations (l_d) with dimension `latent_dim`
91
+
92
+ ## Architecture
93
+
94
+ The framework consists of three components:
95
+
96
+ ### VAE Backbone
97
+ - **Query Encoder**: Maps input to latent representation z
98
+ - **Decoder**: Reconstructs data from latent representations
99
+ - **Loss**: Negative binomial reconstruction + KL divergence
100
+
101
+ ### MoCo Component
102
+ - **Momentum Encoder**: Parameters updated via exponential moving average
103
+ - **Memory Queue**: FIFO mechanism for negative samples
104
+ - **InfoNCE Loss**: Contrastive loss with L2-normalized embeddings
105
+
106
+ ### Coupling Component
107
+ - **Information Bottleneck**: z → l_e → l_d pathway
108
+ - l_e: Compressed representation via `bottleneck_encoder` (dimension: `i_dim`)
109
+ - l_d: Refined representation via `bottleneck_decoder` (dimension: `latent_dim`)
110
+ - **Secondary Reconstruction**: Reconstruction through l_d
111
+
112
+ ## Loss Function
113
+
114
+ The MCC objective combines four loss components:
115
+
116
+ ```
117
+ L_MCC = L_NB + β·L_KLD + α·L_MoCo + γ·L_Cou
118
+ ```
119
+
120
+ - **L_NB**: Negative binomial reconstruction loss (z → reconstruction)
121
+ - **L_KLD**: KL divergence regularization
122
+ - **L_MoCo**: InfoNCE contrastive loss
123
+ - **L_Cou**: Coupling reconstruction loss (z → l_e → l_d → reconstruction)
124
+
125
+
126
+ ## Citation
127
+
128
+ If you use MCCVAE or the MCC benchmark portal, please cite:
129
+
130
+ ```bibtex
131
+ @article{fu2026islands,
132
+ title = {Islands and bridges: Momentum contrastive coupling unifies discrete and continuous structure in single-cell omics},
133
+ author = {Fu, Zeyu and Chen, Chunlin and Zhang, Keyang},
134
+ journal = {Biomedical Signal Processing and Control},
135
+ volume = {122},
136
+ pages = {110376},
137
+ year = {2026},
138
+ doi = {10.1016/j.bspc.2026.110376}
139
+ }
140
+ ```
141
+
142
+ ## License
143
+
144
+ This project is licensed under the MIT License - see the LICENSE file for details.
@@ -0,0 +1,5 @@
1
+ from .agent import Agent
2
+
3
+ __all__ = ['Agent']
4
+
5
+ __version__ = '0.0.1'
@@ -0,0 +1,288 @@
1
+
2
+ """
3
+ Agent Class for MCCVAE Training and Analysis
4
+
5
+ This module provides a high-level interface for training and analyzing MCCVAE models.
6
+ It includes comprehensive functionality for:
7
+ - Model training with progress tracking
8
+ - Latent representation extraction for biological correlation learning
9
+ - Information bottleneck analysis for coupled representations
10
+ - Visualization and analysis utilities for single-cell genomics
11
+ """
12
+
13
+ from .environment import Env
14
+ from anndata import AnnData
15
+ import torch
16
+ import tqdm
17
+ from typing import Literal
18
+ import numpy as np
19
+ import warnings
20
+
21
+
22
+
23
+ class Agent(Env):
24
+ """
25
+ High-level agent for MCCVAE model training and analysis.
26
+
27
+ This class provides a comprehensive interface for training MoCo Coupling Variational
28
+ Autoencoders with contrastive learning capabilities designed for single-cell genomics.
29
+ It offers methods for:
30
+
31
+ - Model training with automatic progress tracking
32
+ - Latent representation and embedding extraction
33
+ - Information bottleneck analysis for coupled biological representations
34
+ - Visualization-ready outputs for single-cell analysis
35
+
36
+ The agent integrates seamlessly with AnnData objects commonly used in
37
+ single-cell analysis and focuses on learning coupled latent representations
38
+ that capture biological correlations intrinsic to single-cell data.
39
+
40
+ The information bottleneck component specifically learns compressed
41
+ representations that preserve essential biological correlations while
42
+ filtering out technical noise, enabling better understanding of cellular
43
+ states and biological processes.
44
+
45
+ Parameters
46
+ ----------
47
+ adata : AnnData
48
+ Annotated single-cell data object containing the dataset
49
+ layer : str, default="counts"
50
+ Layer name in adata to use for training data
51
+ percent : float, default=0.01
52
+ Fraction of dataset to use per batch (0.0 to 1.0)
53
+ recon : float, default=1.0
54
+ Weight for reconstruction loss
55
+ irecon : float, default=0.0
56
+ Weight for information bottleneck reconstruction loss
57
+ beta : float, default=1.0
58
+ Weight for KL divergence regularization (β-VAE)
59
+ dip : float, default=0.0
60
+ Weight for DIP regularization
61
+ tc : float, default=0.0
62
+ Weight for total correlation regularization
63
+ info : float, default=0.0
64
+ Weight for InfoVAE MMD regularization
65
+ hidden_dim : int, default=128
66
+ Dimension of hidden layers in the network
67
+ latent_dim : int, default=10
68
+ Dimension of the latent space
69
+ i_dim : int, default=2
70
+ Dimension of information bottleneck for coupled biological representations
71
+ use_moco : bool, default=False
72
+ Whether to enable Momentum Contrast learning
73
+ loss_mode : Literal["mse", "nb", "zinb"], default="nb"
74
+ Loss function mode for reconstruction
75
+ lr : float, default=1e-4
76
+ Learning rate for optimization
77
+ vae_reg : float, default=0.5
78
+ Regularization weight for VAE latent representations
79
+ moco_weight : float, default=1.0
80
+ Weight for contrastive learning loss
81
+ moco_T : float, default=0.2
82
+ Temperature parameter for MoCo contrastive loss
83
+ aug_prob : float, default=0.5
84
+ Probability of applying data augmentation
85
+ mask_prob : float, default=0.2
86
+ Probability of masking each gene during augmentation
87
+ noise_prob : float, default=0.7
88
+ Probability of adding noise to each gene during augmentation
89
+ use_qm : bool, default=True
90
+ Whether to use mean (True) or samples (False) for latent representations
91
+ device : torch.device
92
+ Computation device (automatically selects CUDA if available)
93
+ """
94
+
95
+ def __init__(
96
+ self,
97
+ adata: AnnData,
98
+ layer: str = "counts",
99
+ percent: float = 0.01,
100
+ recon: float = 1.0,
101
+ irecon: float = 0.0,
102
+ beta: float = 1.0,
103
+ dip: float = 0.0,
104
+ tc: float = 0.0,
105
+ info: float = 0.0,
106
+ hidden_dim: int = 128,
107
+ latent_dim: int = 10,
108
+ i_dim: int = 2,
109
+ use_moco: bool = False,
110
+ use_bn: bool = True,
111
+ loss_mode: Literal["mse", "nb", "zinb"] = "nb",
112
+ lr: float = 1e-4,
113
+ vae_reg: float = 0.5,
114
+ moco_weight: float = 1.0,
115
+ moco_T: float = 0.2,
116
+ aug_prob: float = 0.5,
117
+ mask_prob: float = 0.2,
118
+ noise_prob: float = 0.7,
119
+ use_qm: bool = True,
120
+ device: torch.device = torch.device("cuda") if torch.cuda.is_available() else torch.device("cpu"),
121
+ ):
122
+ # Initialize the parent environment with all parameters
123
+ super().__init__(
124
+ adata=adata,
125
+ layer=layer,
126
+ percent=percent,
127
+ recon=recon,
128
+ irecon=irecon,
129
+ beta=beta,
130
+ dip=dip,
131
+ tc=tc,
132
+ info=info,
133
+ hidden_dim=hidden_dim,
134
+ latent_dim=latent_dim,
135
+ i_dim=i_dim,
136
+ use_moco=use_moco,
137
+ use_bn=use_bn,
138
+ loss_mode=loss_mode,
139
+ lr=lr,
140
+ vae_reg=vae_reg,
141
+ moco_weight=moco_weight,
142
+ moco_T=moco_T,
143
+ aug_prob=aug_prob,
144
+ mask_prob=mask_prob,
145
+ noise_prob=noise_prob,
146
+ use_qm=use_qm,
147
+ device=device,
148
+ )
149
+
150
+ def fit(self, epochs: int = 1000) -> 'Agent':
151
+ """
152
+ Train the MCCVAE model with progress tracking.
153
+
154
+ This method performs the complete training loop with:
155
+ - Automatic batch sampling and data loading
156
+ - Progress bar with real-time metrics display
157
+ - Periodic evaluation metric computation
158
+ - Loss and performance tracking
159
+ - Learning of coupled biological representations
160
+
161
+ The training progress shows key metrics including:
162
+ - Total loss value
163
+ - ARI (Adjusted Rand Index) for clustering accuracy
164
+ - NMI (Normalized Mutual Information) for clustering quality
165
+ - ASW (Average Silhouette Width) for cluster separation
166
+ - C_H (Calinski-Harabasz Index) for cluster validity
167
+ - D_B (Davies-Bouldin Index) for cluster compactness
168
+ - P_C (Pearson Correlation) for disentanglement measure
169
+
170
+ Parameters
171
+ ----------
172
+ epochs : int, default=1000
173
+ Number of training epochs to perform
174
+
175
+ Returns
176
+ -------
177
+ Agent
178
+ Self (for method chaining)
179
+ """
180
+ with tqdm.tqdm(total=int(epochs), desc="Training MCCVAE", ncols=150) as progress_bar:
181
+ for epoch in range(int(epochs)):
182
+ # Load batch data (with augmentation if using MoCo)
183
+ primary_data, query_data, key_data = self.load_data()
184
+
185
+ # Perform training step
186
+ if self.use_moco:
187
+ self.step(primary_data, query_data, key_data)
188
+ else:
189
+ self.step(primary_data)
190
+
191
+ # Update progress display every 10 epochs
192
+ if (epoch + 1) % 10 == 0:
193
+ latest_loss = self.training_losses[-1]
194
+ latest_scores = self.evaluation_scores[-1]
195
+
196
+ progress_bar.set_postfix({
197
+ "Loss": f"{latest_loss[0]:.2f}",
198
+ "ARI": f"{latest_scores[0]:.2f}",
199
+ "NMI": f"{latest_scores[1]:.2f}",
200
+ "ASW": f"{latest_scores[2]:.2f}",
201
+ "C_H": f"{latest_scores[3]:.2f}",
202
+ "D_B": f"{latest_scores[4]:.2f}",
203
+ "P_C": f"{latest_scores[5]:.2f}",
204
+ })
205
+
206
+ progress_bar.update(1)
207
+
208
+ return self
209
+
210
+ def get_iembed(self) -> np.ndarray:
211
+ """
212
+ Extract information bottleneck embeddings from the full dataset.
213
+
214
+ These embeddings represent the coupled latent representations learned
215
+ through the information bottleneck layer, specifically designed to capture
216
+ biological correlations intrinsic to single-cell data. They provide a
217
+ compressed view of the latent space that preserves essential biological
218
+ relationships while filtering out technical noise.
219
+
220
+ Returns
221
+ -------
222
+ np.ndarray
223
+ Information bottleneck embeddings with shape (n_cells, i_dim)
224
+ representing coupled biological correlations
225
+ """
226
+ information_embeddings = self.take_iembed(self.dataset)
227
+ return information_embeddings
228
+
229
+ def get_latent(self) -> np.ndarray:
230
+ """
231
+ Extract latent representations from the full dataset.
232
+
233
+ These are the primary latent space representations learned by the MCCVAE,
234
+ capturing the underlying biological structure and cellular relationships
235
+ in single-cell data. They provide a comprehensive view of cellular states
236
+ encoded in the gene expression patterns.
237
+
238
+ Returns
239
+ -------
240
+ np.ndarray
241
+ Latent representations with shape (n_cells, latent_dim)
242
+ """
243
+ latent_representations = self.take_latent(self.dataset)
244
+ return latent_representations
245
+
246
+ def get_bottleneck(self) -> np.ndarray:
247
+ """
248
+ Extract the compressed bottleneck embeddings (l_e) from the full dataset.
249
+
250
+ This is an alias for get_iembed() provided for consistency with the README
251
+ documentation. The bottleneck embeddings represent the compressed information
252
+ bottleneck layer that captures biological correlations.
253
+
254
+ Returns
255
+ -------
256
+ np.ndarray
257
+ Bottleneck embeddings with shape (n_cells, i_dim)
258
+ """
259
+ return self.get_iembed()
260
+
261
+ def get_refined(self) -> np.ndarray:
262
+ """
263
+ Extract the refined latent representations (l_d) from the full dataset.
264
+
265
+ The refined representations are obtained by passing the primary latent
266
+ representations through the information bottleneck:
267
+ 1. Encoding data to latent space (z)
268
+ 2. Compressing through bottleneck encoder to get l_e
269
+ 3. Expanding through bottleneck decoder to get l_d
270
+ 4. l_d is used for secondary reconstruction in the coupling component
271
+
272
+ These refined representations (l_d) have the same dimensionality as the
273
+ original latent space (latent_dim) but have been refined through the
274
+ information bottleneck, capturing essential biological correlations
275
+ while filtering out technical noise.
276
+
277
+ Returns
278
+ -------
279
+ np.ndarray
280
+ Refined latent representations (l_d) with shape (n_cells, latent_dim)
281
+
282
+ See Also
283
+ --------
284
+ get_iembed : Get information bottleneck embeddings (l_e) - the compressed representation
285
+ get_bottleneck : Alias for get_iembed()
286
+ get_latent : Get primary latent representations (z)
287
+ """
288
+ return self.take_refined(self.dataset)
@@ -0,0 +1,15 @@
1
+ """
2
+ Euclidean Normal Distribution
3
+ Standard Gaussian distribution in Euclidean space
4
+ """
5
+
6
+ from .distribution import Distribution
7
+ from .layers import VanillaEncoderLayer, VanillaDecoderLayer
8
+ from .prior import get_prior
9
+
10
+ __all__ = [
11
+ 'Distribution',
12
+ 'VanillaEncoderLayer',
13
+ 'VanillaDecoderLayer',
14
+ 'get_prior',
15
+ ]
@@ -0,0 +1,3 @@
1
+ def add_distribution_args(parser):
2
+ group = parser.add_argument_group('EuclideanNormal')
3
+ group.add_argument('--layer', type=str, choices=['Vanilla', 'Geo'], default='Vanilla')
@@ -0,0 +1,26 @@
1
+ import torch
2
+ from torch.distributions import Normal
3
+
4
+ from ..utils import euclidean_kl_div
5
+
6
+
7
+ class Distribution():
8
+ def __init__(self, mean, logvar) -> None:
9
+ self.mean = mean
10
+ self.logvar = logvar
11
+
12
+ self.base = Normal(self.mean, (self.logvar * 0.5).exp())
13
+
14
+ def log_prob(self, z):
15
+ return self.base.log_prob(z)
16
+
17
+ def rsample(self, N):
18
+ return self.base.rsample([N])
19
+
20
+ def sample(self, N):
21
+ with torch.no_grad():
22
+ return self.rsample(N)
23
+
24
+ def kl_div(self, target_dist):
25
+ return euclidean_kl_div(self.mean, self.logvar, target_dist.mean, target_dist.logvar)
26
+