livae-sc 0.2.3__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.
- livae_sc-0.2.3/LICENSE +21 -0
- livae_sc-0.2.3/MANIFEST.in +30 -0
- livae_sc-0.2.3/PKG-INFO +288 -0
- livae_sc-0.2.3/README.md +233 -0
- livae_sc-0.2.3/livae/__init__.py +5 -0
- livae_sc-0.2.3/livae/agent.py +209 -0
- livae_sc-0.2.3/livae/environment.py +188 -0
- livae_sc-0.2.3/livae/mixin.py +205 -0
- livae_sc-0.2.3/livae/model.py +192 -0
- livae_sc-0.2.3/livae/module.py +195 -0
- livae_sc-0.2.3/livae/utils.py +89 -0
- livae_sc-0.2.3/livae_sc.egg-info/PKG-INFO +288 -0
- livae_sc-0.2.3/livae_sc.egg-info/SOURCES.txt +18 -0
- livae_sc-0.2.3/livae_sc.egg-info/dependency_links.txt +1 -0
- livae_sc-0.2.3/livae_sc.egg-info/requires.txt +14 -0
- livae_sc-0.2.3/livae_sc.egg-info/top_level.txt +1 -0
- livae_sc-0.2.3/pyproject.toml +49 -0
- livae_sc-0.2.3/requirements.txt +29 -0
- livae_sc-0.2.3/setup.cfg +4 -0
- livae_sc-0.2.3/tests/test_import.py +16 -0
livae_sc-0.2.3/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.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Include essential files
|
|
2
|
+
include README.md
|
|
3
|
+
include LICENSE
|
|
4
|
+
include pyproject.toml
|
|
5
|
+
include requirements.txt
|
|
6
|
+
|
|
7
|
+
# Include package data
|
|
8
|
+
recursive-include livae *.py
|
|
9
|
+
|
|
10
|
+
# Include tests
|
|
11
|
+
recursive-include tests *.py
|
|
12
|
+
|
|
13
|
+
# Exclude everything else
|
|
14
|
+
global-exclude __pycache__
|
|
15
|
+
global-exclude *.py[cod]
|
|
16
|
+
global-exclude .DS_Store
|
|
17
|
+
global-exclude *.so
|
|
18
|
+
global-exclude .git*
|
|
19
|
+
|
|
20
|
+
# Explicitly exclude frontend, api, and other project files
|
|
21
|
+
prune frontend
|
|
22
|
+
prune api
|
|
23
|
+
prune scripts
|
|
24
|
+
prune .github
|
|
25
|
+
prune dist
|
|
26
|
+
prune build
|
|
27
|
+
prune downloads
|
|
28
|
+
exclude start_services.py
|
|
29
|
+
exclude uvicorn_pid.txt
|
|
30
|
+
exclude review-points.md
|
livae_sc-0.2.3/PKG-INFO
ADDED
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: livae-sc
|
|
3
|
+
Version: 0.2.3
|
|
4
|
+
Summary: Lorentzian Interpretable Variational Autoencoder for single-cell data
|
|
5
|
+
Author: LiVAE Contributors
|
|
6
|
+
License: MIT License
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2025 Zeyu Fu
|
|
9
|
+
|
|
10
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
11
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
12
|
+
in the Software without restriction, including without limitation the rights
|
|
13
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
14
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
15
|
+
furnished to do so, subject to the following conditions:
|
|
16
|
+
|
|
17
|
+
The above copyright notice and this permission notice shall be included in all
|
|
18
|
+
copies or substantial portions of the Software.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
24
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
25
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
26
|
+
SOFTWARE.
|
|
27
|
+
|
|
28
|
+
Project-URL: Homepage, https://github.com/PeterPonyu/LiVAE
|
|
29
|
+
Project-URL: Source, https://github.com/PeterPonyu/LiVAE
|
|
30
|
+
Project-URL: Issues, https://github.com/PeterPonyu/LiVAE/issues
|
|
31
|
+
Keywords: single-cell,variational-autoencoder,hyperbolic,lorentz,bioinformatics
|
|
32
|
+
Classifier: Programming Language :: Python :: 3
|
|
33
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
34
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
35
|
+
Classifier: Intended Audience :: Science/Research
|
|
36
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
37
|
+
Requires-Python: >=3.10
|
|
38
|
+
Description-Content-Type: text/markdown
|
|
39
|
+
License-File: LICENSE
|
|
40
|
+
Requires-Dist: torch<2.5.0,>=2.3.0
|
|
41
|
+
Requires-Dist: torchvision<0.20.0,>=0.18.0
|
|
42
|
+
Requires-Dist: scanpy<1.11.0,>=1.10.0
|
|
43
|
+
Requires-Dist: scvi-tools<1.2.0,>=1.1.0
|
|
44
|
+
Requires-Dist: anndata<0.11.0,>=0.10.0
|
|
45
|
+
Requires-Dist: scib>=1.0.0
|
|
46
|
+
Requires-Dist: numpy<1.27.0,>=1.26.0
|
|
47
|
+
Requires-Dist: pandas<2.3.0,>=2.2.0
|
|
48
|
+
Requires-Dist: scipy<1.13.0,>=1.12.0
|
|
49
|
+
Requires-Dist: scikit-learn<1.6.0,>=1.5.0
|
|
50
|
+
Requires-Dist: tqdm<5.0.0,>=4.66.0
|
|
51
|
+
Requires-Dist: fastapi<0.118.0,>=0.117.0
|
|
52
|
+
Requires-Dist: uvicorn[standard]<0.37.0,>=0.36.0
|
|
53
|
+
Requires-Dist: python-multipart>=0.0.6
|
|
54
|
+
Dynamic: license-file
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
# LiVAE: Lorentz-regularized Interpretable Variational Autoencoder
|
|
58
|
+
|
|
59
|
+
[](https://pypi.org/project/livae-sc/)
|
|
60
|
+
[](https://www.python.org/downloads/)
|
|
61
|
+
[](https://pytorch.org/)
|
|
62
|
+
[](https://github.com/PeterPonyu/LiVAE/actions/workflows/ci.yml)
|
|
63
|
+
[](LICENSE)
|
|
64
|
+
|
|
65
|
+
LiVAE (Lorentz-regularized Interpretable Variational Autoencoder) is a dual-pathway architecture for learning interpretable latent representations from single-cell transcriptomic and epigenomic data. It applies hyperbolic geometry as soft regularization over standard Euclidean latent spaces to balance local fidelity with global coherence.
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
## Installation
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# Install from PyPI (recommended)
|
|
72
|
+
pip install livae-sc
|
|
73
|
+
|
|
74
|
+
# Or install from source for development
|
|
75
|
+
git clone https://github.com/PeterPonyu/LiVAE.git
|
|
76
|
+
cd LiVAE
|
|
77
|
+
pip install -e .
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
From version 0.2.3 the package is published on PyPI as `livae-sc`; the import name is still `livae`. The earlier `livae` project on PyPI stays at 0.2.1 and is no longer updated.
|
|
81
|
+
|
|
82
|
+
### Core Requirements
|
|
83
|
+
|
|
84
|
+
```text
|
|
85
|
+
torch>=2.3.0,<2.5.0
|
|
86
|
+
torchvision>=0.18.0,<0.20.0
|
|
87
|
+
scanpy>=1.10.0,<1.11.0
|
|
88
|
+
scvi-tools>=1.1.0,<1.2.0
|
|
89
|
+
anndata>=0.10.0,<0.11.0
|
|
90
|
+
scib>=1.0.0
|
|
91
|
+
numpy>=1.26.0,<1.27.0
|
|
92
|
+
pandas>=2.2.0,<2.3.0
|
|
93
|
+
scipy>=1.12.0,<1.13.0
|
|
94
|
+
scikit-learn>=1.5.0,<1.6.0
|
|
95
|
+
tqdm>=4.66.0,<5.0.0
|
|
96
|
+
fastapi>=0.117.0,<0.118.0
|
|
97
|
+
uvicorn[standard]>=0.36.0,<0.37.0
|
|
98
|
+
python-multipart>=0.0.6
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Python Quick Start
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
import scanpy as sc
|
|
105
|
+
from livae import agent
|
|
106
|
+
|
|
107
|
+
# Load your single-cell data
|
|
108
|
+
adata = sc.read_h5ad('your_data.h5ad')
|
|
109
|
+
|
|
110
|
+
# Initialize LiVAE agent
|
|
111
|
+
model = agent(
|
|
112
|
+
adata=adata,
|
|
113
|
+
layer='counts', # Data layer to use
|
|
114
|
+
latent_dim=10, # Primary latent dimension
|
|
115
|
+
i_dim=2, # Interpretable latent dimension
|
|
116
|
+
hidden_dim=128, # Hidden layer dimension
|
|
117
|
+
lr=1e-4, # Learning rate
|
|
118
|
+
# Regularization weights
|
|
119
|
+
beta=1.0, # β-VAE weight
|
|
120
|
+
lorentz=1.0, # Lorentzian regularization
|
|
121
|
+
irecon=1.0, # Interpretable reconstruction
|
|
122
|
+
)
|
|
123
|
+
|
|
124
|
+
# Train the model
|
|
125
|
+
model.fit(epochs=100)
|
|
126
|
+
|
|
127
|
+
# Extract embeddings
|
|
128
|
+
latent = model.get_latent() # Primary latent representation
|
|
129
|
+
interpretable = model.get_iembed() # Interpretable embedding (i_dim)
|
|
130
|
+
|
|
131
|
+
# Access results
|
|
132
|
+
print(f"Latent shape: {latent.shape}")
|
|
133
|
+
print(f"Interpretable embedding shape: {interpretable.shape}")
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Web Interface
|
|
137
|
+
|
|
138
|
+
LiVAE includes an integrated web interface for interactive training and visualization.
|
|
139
|
+
|
|
140
|
+
### Launch the Application
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
# Start the FastAPI server (serves both API and frontend)
|
|
144
|
+
uvicorn api.main:app --host 0.0.0.0 --port 8000
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Access the web interface at `http://localhost:8000`
|
|
148
|
+
|
|
149
|
+
### Features
|
|
150
|
+
|
|
151
|
+
- **Data Upload**: Upload single-cell datasets (H5AD format)
|
|
152
|
+
- **Training Configuration**: Configure model parameters and hyperparameters
|
|
153
|
+
- **Real-time Monitoring**: Track loss curves and metrics during training
|
|
154
|
+
- **Results Visualization**: Download embeddings and view training summaries
|
|
155
|
+
|
|
156
|
+
### API Endpoints
|
|
157
|
+
|
|
158
|
+
- `POST /upload` - Upload dataset
|
|
159
|
+
- `POST /train/start` - Start training
|
|
160
|
+
- `GET /train/metrics` - Get training metrics
|
|
161
|
+
- `GET /embeddings/interpretable` - Get interpretable embeddings
|
|
162
|
+
- `GET /embeddings/latent` - Get latent embeddings
|
|
163
|
+
- `GET /download/embeddings/{type}` - Download embeddings as CSV
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
## Architecture Overview
|
|
167
|
+
|
|
168
|
+
LiVAE consists of three main components working in concert:
|
|
169
|
+
|
|
170
|
+
### 1. **Encoder Network**
|
|
171
|
+
|
|
172
|
+
```text
|
|
173
|
+
Input (gene expression) → Hidden → Hidden → μ, σ (latent parameters)
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
- Maps high-dimensional gene expression to latent distribution parameters
|
|
177
|
+
- Uses reparameterization trick for differentiable sampling
|
|
178
|
+
|
|
179
|
+
### 2. **Hyperbolic Transformation**
|
|
180
|
+
|
|
181
|
+
```text
|
|
182
|
+
Latent Sample → Tangent Space → Exponential Map → Lorentzian Manifold
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
- Projects latent vectors onto hyperbolic manifold
|
|
186
|
+
- Enables natural representation of hierarchical relationships
|
|
187
|
+
|
|
188
|
+
### 3. **Dual Decoder Pathway**
|
|
189
|
+
|
|
190
|
+
```text
|
|
191
|
+
Primary: Latent → Decoder → Reconstruction
|
|
192
|
+
Interpretable: Latent → Compress → Decompress → Decoder → Reconstruction
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
- Dual reconstruction paths for enhanced representation learning
|
|
196
|
+
- Compression bottleneck encourages essential feature extraction
|
|
197
|
+
|
|
198
|
+
## Loss Function
|
|
199
|
+
|
|
200
|
+
LiVAE optimizes a composite loss function:
|
|
201
|
+
|
|
202
|
+
```text
|
|
203
|
+
L_total = L_recon + L_irecon + L_lorentz + L_KL
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Where:
|
|
207
|
+
|
|
208
|
+
- **L_recon**: Negative binomial reconstruction loss
|
|
209
|
+
- **L_irecon**: Interpretable reconstruction loss
|
|
210
|
+
- **L_lorentz**: Lorentz distance regularization
|
|
211
|
+
- **L_KL**: KL divergence
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
## Evaluation Metrics
|
|
215
|
+
|
|
216
|
+
### Clustering Quality
|
|
217
|
+
|
|
218
|
+
- **ARI** (Adjusted Rand Index): Clustering agreement with ground truth
|
|
219
|
+
- **NMI** (Normalized Mutual Information): Information-theoretic clustering measure
|
|
220
|
+
- **ASW** (Average Silhouette Width): Cluster cohesion and separation
|
|
221
|
+
|
|
222
|
+
### Cluster Validity
|
|
223
|
+
|
|
224
|
+
- **C_H** (Calinski-Harabasz): Ratio of between to within cluster variance
|
|
225
|
+
- **D_B** (Davies-Bouldin): Average similarity between clusters
|
|
226
|
+
- **P_C** (Graph Connectivity): Connectivity within clusters
|
|
227
|
+
|
|
228
|
+
### Batch Integration
|
|
229
|
+
|
|
230
|
+
- **cLISI**: Cluster-specific Local Inverse Simpson Index
|
|
231
|
+
- **iLISI**: Integration LISI for batch mixing
|
|
232
|
+
- **bASW**: Batch-corrected Average Silhouette Width
|
|
233
|
+
|
|
234
|
+
## Performance Tips
|
|
235
|
+
|
|
236
|
+
### Memory Optimization
|
|
237
|
+
|
|
238
|
+
```python
|
|
239
|
+
# For large datasets, reduce batch size
|
|
240
|
+
model = agent(adata, percent=0.005) # Use 0.5% of data per batch (default is 1%)
|
|
241
|
+
|
|
242
|
+
# Use CPU if GPU memory is limited
|
|
243
|
+
import torch
|
|
244
|
+
model = agent(adata, device=torch.device('cpu'))
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
### Training Efficiency
|
|
248
|
+
|
|
249
|
+
```python
|
|
250
|
+
# Progressive training with increasing regularization
|
|
251
|
+
model = agent(adata, beta=0.1, lorentz=0.0)
|
|
252
|
+
model.fit(epochs=500)
|
|
253
|
+
|
|
254
|
+
# Increase regularization for fine-tuning
|
|
255
|
+
model.beta = 1.0
|
|
256
|
+
model.lorentz = 0.1
|
|
257
|
+
model.fit(epochs=500)
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
## Citation
|
|
261
|
+
|
|
262
|
+
If you use LiVAE in your research, please cite the following paper:
|
|
263
|
+
|
|
264
|
+
```bibtex
|
|
265
|
+
@ARTICLE{10.3389/fgene.2025.1713727,
|
|
266
|
+
AUTHOR={Fu, Zeyu and Fu, Jiawei and Chen, Chunlin and Zhang, Keyang and Wang, Song},
|
|
267
|
+
TITLE={Lorentz-regularized interpretable VAE for multi-scale single-cell transcriptomic and epigenomic embeddings},
|
|
268
|
+
JOURNAL={Frontiers in Genetics},
|
|
269
|
+
VOLUME={16},
|
|
270
|
+
PAGES={1713727},
|
|
271
|
+
YEAR={2026},
|
|
272
|
+
URL={https://www.frontiersin.org/journals/genetics/articles/10.3389/fgene.2025.1713727},
|
|
273
|
+
DOI={10.3389/fgene.2025.1713727},
|
|
274
|
+
ISSN={1664-8021}
|
|
275
|
+
}
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
## Contributing
|
|
279
|
+
|
|
280
|
+
Contributions are welcome! Please ensure tests pass before submitting PRs:
|
|
281
|
+
|
|
282
|
+
```bash
|
|
283
|
+
pytest -q
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
## License
|
|
287
|
+
|
|
288
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
livae_sc-0.2.3/README.md
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
|
|
2
|
+
# LiVAE: Lorentz-regularized Interpretable Variational Autoencoder
|
|
3
|
+
|
|
4
|
+
[](https://pypi.org/project/livae-sc/)
|
|
5
|
+
[](https://www.python.org/downloads/)
|
|
6
|
+
[](https://pytorch.org/)
|
|
7
|
+
[](https://github.com/PeterPonyu/LiVAE/actions/workflows/ci.yml)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
|
|
10
|
+
LiVAE (Lorentz-regularized Interpretable Variational Autoencoder) is a dual-pathway architecture for learning interpretable latent representations from single-cell transcriptomic and epigenomic data. It applies hyperbolic geometry as soft regularization over standard Euclidean latent spaces to balance local fidelity with global coherence.
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
# Install from PyPI (recommended)
|
|
17
|
+
pip install livae-sc
|
|
18
|
+
|
|
19
|
+
# Or install from source for development
|
|
20
|
+
git clone https://github.com/PeterPonyu/LiVAE.git
|
|
21
|
+
cd LiVAE
|
|
22
|
+
pip install -e .
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
From version 0.2.3 the package is published on PyPI as `livae-sc`; the import name is still `livae`. The earlier `livae` project on PyPI stays at 0.2.1 and is no longer updated.
|
|
26
|
+
|
|
27
|
+
### Core Requirements
|
|
28
|
+
|
|
29
|
+
```text
|
|
30
|
+
torch>=2.3.0,<2.5.0
|
|
31
|
+
torchvision>=0.18.0,<0.20.0
|
|
32
|
+
scanpy>=1.10.0,<1.11.0
|
|
33
|
+
scvi-tools>=1.1.0,<1.2.0
|
|
34
|
+
anndata>=0.10.0,<0.11.0
|
|
35
|
+
scib>=1.0.0
|
|
36
|
+
numpy>=1.26.0,<1.27.0
|
|
37
|
+
pandas>=2.2.0,<2.3.0
|
|
38
|
+
scipy>=1.12.0,<1.13.0
|
|
39
|
+
scikit-learn>=1.5.0,<1.6.0
|
|
40
|
+
tqdm>=4.66.0,<5.0.0
|
|
41
|
+
fastapi>=0.117.0,<0.118.0
|
|
42
|
+
uvicorn[standard]>=0.36.0,<0.37.0
|
|
43
|
+
python-multipart>=0.0.6
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Python Quick Start
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
import scanpy as sc
|
|
50
|
+
from livae import agent
|
|
51
|
+
|
|
52
|
+
# Load your single-cell data
|
|
53
|
+
adata = sc.read_h5ad('your_data.h5ad')
|
|
54
|
+
|
|
55
|
+
# Initialize LiVAE agent
|
|
56
|
+
model = agent(
|
|
57
|
+
adata=adata,
|
|
58
|
+
layer='counts', # Data layer to use
|
|
59
|
+
latent_dim=10, # Primary latent dimension
|
|
60
|
+
i_dim=2, # Interpretable latent dimension
|
|
61
|
+
hidden_dim=128, # Hidden layer dimension
|
|
62
|
+
lr=1e-4, # Learning rate
|
|
63
|
+
# Regularization weights
|
|
64
|
+
beta=1.0, # β-VAE weight
|
|
65
|
+
lorentz=1.0, # Lorentzian regularization
|
|
66
|
+
irecon=1.0, # Interpretable reconstruction
|
|
67
|
+
)
|
|
68
|
+
|
|
69
|
+
# Train the model
|
|
70
|
+
model.fit(epochs=100)
|
|
71
|
+
|
|
72
|
+
# Extract embeddings
|
|
73
|
+
latent = model.get_latent() # Primary latent representation
|
|
74
|
+
interpretable = model.get_iembed() # Interpretable embedding (i_dim)
|
|
75
|
+
|
|
76
|
+
# Access results
|
|
77
|
+
print(f"Latent shape: {latent.shape}")
|
|
78
|
+
print(f"Interpretable embedding shape: {interpretable.shape}")
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Web Interface
|
|
82
|
+
|
|
83
|
+
LiVAE includes an integrated web interface for interactive training and visualization.
|
|
84
|
+
|
|
85
|
+
### Launch the Application
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
# Start the FastAPI server (serves both API and frontend)
|
|
89
|
+
uvicorn api.main:app --host 0.0.0.0 --port 8000
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Access the web interface at `http://localhost:8000`
|
|
93
|
+
|
|
94
|
+
### Features
|
|
95
|
+
|
|
96
|
+
- **Data Upload**: Upload single-cell datasets (H5AD format)
|
|
97
|
+
- **Training Configuration**: Configure model parameters and hyperparameters
|
|
98
|
+
- **Real-time Monitoring**: Track loss curves and metrics during training
|
|
99
|
+
- **Results Visualization**: Download embeddings and view training summaries
|
|
100
|
+
|
|
101
|
+
### API Endpoints
|
|
102
|
+
|
|
103
|
+
- `POST /upload` - Upload dataset
|
|
104
|
+
- `POST /train/start` - Start training
|
|
105
|
+
- `GET /train/metrics` - Get training metrics
|
|
106
|
+
- `GET /embeddings/interpretable` - Get interpretable embeddings
|
|
107
|
+
- `GET /embeddings/latent` - Get latent embeddings
|
|
108
|
+
- `GET /download/embeddings/{type}` - Download embeddings as CSV
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
## Architecture Overview
|
|
112
|
+
|
|
113
|
+
LiVAE consists of three main components working in concert:
|
|
114
|
+
|
|
115
|
+
### 1. **Encoder Network**
|
|
116
|
+
|
|
117
|
+
```text
|
|
118
|
+
Input (gene expression) → Hidden → Hidden → μ, σ (latent parameters)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
- Maps high-dimensional gene expression to latent distribution parameters
|
|
122
|
+
- Uses reparameterization trick for differentiable sampling
|
|
123
|
+
|
|
124
|
+
### 2. **Hyperbolic Transformation**
|
|
125
|
+
|
|
126
|
+
```text
|
|
127
|
+
Latent Sample → Tangent Space → Exponential Map → Lorentzian Manifold
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
- Projects latent vectors onto hyperbolic manifold
|
|
131
|
+
- Enables natural representation of hierarchical relationships
|
|
132
|
+
|
|
133
|
+
### 3. **Dual Decoder Pathway**
|
|
134
|
+
|
|
135
|
+
```text
|
|
136
|
+
Primary: Latent → Decoder → Reconstruction
|
|
137
|
+
Interpretable: Latent → Compress → Decompress → Decoder → Reconstruction
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
- Dual reconstruction paths for enhanced representation learning
|
|
141
|
+
- Compression bottleneck encourages essential feature extraction
|
|
142
|
+
|
|
143
|
+
## Loss Function
|
|
144
|
+
|
|
145
|
+
LiVAE optimizes a composite loss function:
|
|
146
|
+
|
|
147
|
+
```text
|
|
148
|
+
L_total = L_recon + L_irecon + L_lorentz + L_KL
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Where:
|
|
152
|
+
|
|
153
|
+
- **L_recon**: Negative binomial reconstruction loss
|
|
154
|
+
- **L_irecon**: Interpretable reconstruction loss
|
|
155
|
+
- **L_lorentz**: Lorentz distance regularization
|
|
156
|
+
- **L_KL**: KL divergence
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
## Evaluation Metrics
|
|
160
|
+
|
|
161
|
+
### Clustering Quality
|
|
162
|
+
|
|
163
|
+
- **ARI** (Adjusted Rand Index): Clustering agreement with ground truth
|
|
164
|
+
- **NMI** (Normalized Mutual Information): Information-theoretic clustering measure
|
|
165
|
+
- **ASW** (Average Silhouette Width): Cluster cohesion and separation
|
|
166
|
+
|
|
167
|
+
### Cluster Validity
|
|
168
|
+
|
|
169
|
+
- **C_H** (Calinski-Harabasz): Ratio of between to within cluster variance
|
|
170
|
+
- **D_B** (Davies-Bouldin): Average similarity between clusters
|
|
171
|
+
- **P_C** (Graph Connectivity): Connectivity within clusters
|
|
172
|
+
|
|
173
|
+
### Batch Integration
|
|
174
|
+
|
|
175
|
+
- **cLISI**: Cluster-specific Local Inverse Simpson Index
|
|
176
|
+
- **iLISI**: Integration LISI for batch mixing
|
|
177
|
+
- **bASW**: Batch-corrected Average Silhouette Width
|
|
178
|
+
|
|
179
|
+
## Performance Tips
|
|
180
|
+
|
|
181
|
+
### Memory Optimization
|
|
182
|
+
|
|
183
|
+
```python
|
|
184
|
+
# For large datasets, reduce batch size
|
|
185
|
+
model = agent(adata, percent=0.005) # Use 0.5% of data per batch (default is 1%)
|
|
186
|
+
|
|
187
|
+
# Use CPU if GPU memory is limited
|
|
188
|
+
import torch
|
|
189
|
+
model = agent(adata, device=torch.device('cpu'))
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Training Efficiency
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
# Progressive training with increasing regularization
|
|
196
|
+
model = agent(adata, beta=0.1, lorentz=0.0)
|
|
197
|
+
model.fit(epochs=500)
|
|
198
|
+
|
|
199
|
+
# Increase regularization for fine-tuning
|
|
200
|
+
model.beta = 1.0
|
|
201
|
+
model.lorentz = 0.1
|
|
202
|
+
model.fit(epochs=500)
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
## Citation
|
|
206
|
+
|
|
207
|
+
If you use LiVAE in your research, please cite the following paper:
|
|
208
|
+
|
|
209
|
+
```bibtex
|
|
210
|
+
@ARTICLE{10.3389/fgene.2025.1713727,
|
|
211
|
+
AUTHOR={Fu, Zeyu and Fu, Jiawei and Chen, Chunlin and Zhang, Keyang and Wang, Song},
|
|
212
|
+
TITLE={Lorentz-regularized interpretable VAE for multi-scale single-cell transcriptomic and epigenomic embeddings},
|
|
213
|
+
JOURNAL={Frontiers in Genetics},
|
|
214
|
+
VOLUME={16},
|
|
215
|
+
PAGES={1713727},
|
|
216
|
+
YEAR={2026},
|
|
217
|
+
URL={https://www.frontiersin.org/journals/genetics/articles/10.3389/fgene.2025.1713727},
|
|
218
|
+
DOI={10.3389/fgene.2025.1713727},
|
|
219
|
+
ISSN={1664-8021}
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
## Contributing
|
|
224
|
+
|
|
225
|
+
Contributions are welcome! Please ensure tests pass before submitting PRs:
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
pytest -q
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
## License
|
|
232
|
+
|
|
233
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|