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.
- mccvae-0.0.1/LICENSE +21 -0
- mccvae-0.0.1/PKG-INFO +185 -0
- mccvae-0.0.1/README.md +144 -0
- mccvae-0.0.1/mccvae/__init__.py +5 -0
- mccvae-0.0.1/mccvae/agent.py +288 -0
- mccvae-0.0.1/mccvae/distributions/EuclideanNormal/__init__.py +15 -0
- mccvae-0.0.1/mccvae/distributions/EuclideanNormal/arguments.py +3 -0
- mccvae-0.0.1/mccvae/distributions/EuclideanNormal/distribution.py +26 -0
- mccvae-0.0.1/mccvae/distributions/EuclideanNormal/layers.py +35 -0
- mccvae-0.0.1/mccvae/distributions/EuclideanNormal/prior.py +18 -0
- mccvae-0.0.1/mccvae/distributions/HWNormal/__init__.py +15 -0
- mccvae-0.0.1/mccvae/distributions/HWNormal/arguments.py +3 -0
- mccvae-0.0.1/mccvae/distributions/HWNormal/distribution.py +56 -0
- mccvae-0.0.1/mccvae/distributions/HWNormal/layers.py +44 -0
- mccvae-0.0.1/mccvae/distributions/HWNormal/prior.py +24 -0
- mccvae-0.0.1/mccvae/distributions/LearnablePGMNormal/__init__.py +24 -0
- mccvae-0.0.1/mccvae/distributions/LearnablePGMNormal/arguments.py +4 -0
- mccvae-0.0.1/mccvae/distributions/LearnablePGMNormal/distribution.py +81 -0
- mccvae-0.0.1/mccvae/distributions/LearnablePGMNormal/layers.py +218 -0
- mccvae-0.0.1/mccvae/distributions/LearnablePGMNormal/prior.py +18 -0
- mccvae-0.0.1/mccvae/distributions/PGMNormal/__init__.py +24 -0
- mccvae-0.0.1/mccvae/distributions/PGMNormal/arguments.py +4 -0
- mccvae-0.0.1/mccvae/distributions/PGMNormal/distribution.py +71 -0
- mccvae-0.0.1/mccvae/distributions/PGMNormal/layers.py +82 -0
- mccvae-0.0.1/mccvae/distributions/PGMNormal/prior.py +18 -0
- mccvae-0.0.1/mccvae/distributions/PoincareNormal/__init__.py +16 -0
- mccvae-0.0.1/mccvae/distributions/PoincareNormal/arguments.py +4 -0
- mccvae-0.0.1/mccvae/distributions/PoincareNormal/ars.py +133 -0
- mccvae-0.0.1/mccvae/distributions/PoincareNormal/distribution.py +58 -0
- mccvae-0.0.1/mccvae/distributions/PoincareNormal/hyperbolic_radius.py +371 -0
- mccvae-0.0.1/mccvae/distributions/PoincareNormal/hyperbolic_uniform.py +43 -0
- mccvae-0.0.1/mccvae/distributions/PoincareNormal/layers.py +48 -0
- mccvae-0.0.1/mccvae/distributions/PoincareNormal/prior.py +18 -0
- mccvae-0.0.1/mccvae/distributions/__init__.py +0 -0
- mccvae-0.0.1/mccvae/distributions/utils.py +21 -0
- mccvae-0.0.1/mccvae/environment.py +361 -0
- mccvae-0.0.1/mccvae/mixin.py +671 -0
- mccvae-0.0.1/mccvae/model.py +480 -0
- mccvae-0.0.1/mccvae/module.py +519 -0
- mccvae-0.0.1/mccvae/palantir/__init__.py +28 -0
- mccvae-0.0.1/mccvae/palantir/core.py +289 -0
- mccvae-0.0.1/mccvae/palantir/diffusion.py +254 -0
- mccvae-0.0.1/mccvae/palantir/magic.py +50 -0
- mccvae-0.0.1/mccvae/palantir/pseudotime.py +431 -0
- mccvae-0.0.1/mccvae/palantir/test_palantir.py +140 -0
- mccvae-0.0.1/mccvae/palantir/utils.py +193 -0
- mccvae-0.0.1/mccvae/unified_models/__init__.py +67 -0
- mccvae-0.0.1/mccvae/unified_models/base_model.py +361 -0
- mccvae-0.0.1/mccvae/unified_models/cellblast_model.py +349 -0
- mccvae-0.0.1/mccvae/unified_models/clear_model.py +258 -0
- mccvae-0.0.1/mccvae/unified_models/gmvae_model.py +560 -0
- mccvae-0.0.1/mccvae/unified_models/scagcl_model.py +486 -0
- mccvae-0.0.1/mccvae/unified_models/scalex_model.py +352 -0
- mccvae-0.0.1/mccvae/unified_models/scdac_model.py +269 -0
- mccvae-0.0.1/mccvae/unified_models/scdeepcluster_model.py +300 -0
- mccvae-0.0.1/mccvae/unified_models/scdhmap_model.py +454 -0
- mccvae-0.0.1/mccvae/unified_models/scdiffusion_model.py +479 -0
- mccvae-0.0.1/mccvae/unified_models/scgcc_model.py +374 -0
- mccvae-0.0.1/mccvae/unified_models/scgnn_model.py +210 -0
- mccvae-0.0.1/mccvae/unified_models/scgpcl_model.py +665 -0
- mccvae-0.0.1/mccvae/unified_models/schsc_model.py +626 -0
- mccvae-0.0.1/mccvae/unified_models/scsimgcl_model.py +471 -0
- mccvae-0.0.1/mccvae/unified_models/scsmd_model.py +387 -0
- mccvae-0.0.1/mccvae/unified_models/sivae_model.py +460 -0
- mccvae-0.0.1/mccvae/utils.py +228 -0
- mccvae-0.0.1/mccvae.egg-info/PKG-INFO +185 -0
- mccvae-0.0.1/mccvae.egg-info/SOURCES.txt +70 -0
- mccvae-0.0.1/mccvae.egg-info/dependency_links.txt +1 -0
- mccvae-0.0.1/mccvae.egg-info/requires.txt +24 -0
- mccvae-0.0.1/mccvae.egg-info/top_level.txt +1 -0
- mccvae-0.0.1/pyproject.toml +45 -0
- 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
|
+
[](https://peterponyu.github.io/MCCVAE/)
|
|
52
|
+
[](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
|
+
[](https://peterponyu.github.io/MCCVAE/)
|
|
11
|
+
[](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,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,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
|
+
|