ivae-sc 0.0.6__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.
- ivae_sc-0.0.6/LICENSE +21 -0
- ivae_sc-0.0.6/PKG-INFO +294 -0
- ivae_sc-0.0.6/README.md +261 -0
- ivae_sc-0.0.6/iVAE/__init__.py +6 -0
- ivae_sc-0.0.6/iVAE/agent.py +240 -0
- ivae_sc-0.0.6/iVAE/cli.py +128 -0
- ivae_sc-0.0.6/iVAE/environment.py +181 -0
- ivae_sc-0.0.6/iVAE/mixin.py +469 -0
- ivae_sc-0.0.6/iVAE/model.py +194 -0
- ivae_sc-0.0.6/iVAE/module.py +250 -0
- ivae_sc-0.0.6/iVAE/utils.py +185 -0
- ivae_sc-0.0.6/ivae_sc.egg-info/PKG-INFO +294 -0
- ivae_sc-0.0.6/ivae_sc.egg-info/SOURCES.txt +17 -0
- ivae_sc-0.0.6/ivae_sc.egg-info/dependency_links.txt +1 -0
- ivae_sc-0.0.6/ivae_sc.egg-info/entry_points.txt +2 -0
- ivae_sc-0.0.6/ivae_sc.egg-info/requires.txt +5 -0
- ivae_sc-0.0.6/ivae_sc.egg-info/top_level.txt +1 -0
- ivae_sc-0.0.6/setup.cfg +4 -0
- ivae_sc-0.0.6/setup.py +37 -0
ivae_sc-0.0.6/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 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.
|
ivae_sc-0.0.6/PKG-INFO
ADDED
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ivae-sc
|
|
3
|
+
Version: 0.0.6
|
|
4
|
+
Summary: Interpretable Variational Autoencoder for Single-Cell Data
|
|
5
|
+
Home-page: https://github.com/PeterPonyu/iVAE
|
|
6
|
+
Author: Zeyu Fu
|
|
7
|
+
Author-email: fuzeyu99@126.com
|
|
8
|
+
License: MIT
|
|
9
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
14
|
+
Requires-Python: >=3.9
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
License-File: LICENSE
|
|
17
|
+
Requires-Dist: scanpy>=1.10.4
|
|
18
|
+
Requires-Dist: scib>=1.1.5
|
|
19
|
+
Requires-Dist: torch>=1.13.1
|
|
20
|
+
Requires-Dist: joblib>=1.2.0
|
|
21
|
+
Requires-Dist: tqdm>=4.64.1
|
|
22
|
+
Dynamic: author
|
|
23
|
+
Dynamic: author-email
|
|
24
|
+
Dynamic: classifier
|
|
25
|
+
Dynamic: description
|
|
26
|
+
Dynamic: description-content-type
|
|
27
|
+
Dynamic: home-page
|
|
28
|
+
Dynamic: license
|
|
29
|
+
Dynamic: license-file
|
|
30
|
+
Dynamic: requires-dist
|
|
31
|
+
Dynamic: requires-python
|
|
32
|
+
Dynamic: summary
|
|
33
|
+
|
|
34
|
+
<div align="center">
|
|
35
|
+
<a href="https://peterponyu.github.io/">
|
|
36
|
+
<img src="https://peterponyu.github.io/assets/badges/iVAE.svg" width="64" alt="ZF Lab · iVAE">
|
|
37
|
+
</a>
|
|
38
|
+
</div>
|
|
39
|
+
|
|
40
|
+
## About
|
|
41
|
+
|
|
42
|
+
iVAE is a representation learning method for single-cell transcriptomics. Compared with a standard VAE, it adds an interpretative bottleneck that encourages correlated latent structure when those correlations are present in the data.
|
|
43
|
+
|
|
44
|
+
<img src='source/_static/fig.png' width='600' align='center'>
|
|
45
|
+
|
|
46
|
+
## Key Features
|
|
47
|
+
|
|
48
|
+
- **Interpretative Module**: A bottleneck layer that encourages learning of correlated patterns in gene expression
|
|
49
|
+
- **Multiple Loss Functions**: Supports various regularization techniques (KL, DIP, TC, MMD) for improved disentanglement
|
|
50
|
+
- **Single-Cell Optimized**: Uses negative binomial distribution for count data modeling
|
|
51
|
+
- **Python API and CLI**: Supports both scripted and command-line workflows
|
|
52
|
+
- **GPU Accelerated**: Automatic GPU detection and usage when available
|
|
53
|
+
|
|
54
|
+
## Installation
|
|
55
|
+
|
|
56
|
+
[](https://pypi.org/project/ivae-sc/)
|
|
57
|
+
|
|
58
|
+
Install the package from PyPI:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
pip install ivae-sc
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
From version 0.0.6 the package is published on PyPI as `ivae-sc`; the import name is still `iVAE`. The earlier `iVAE` project on PyPI stays at 0.0.5 and is no longer updated.
|
|
65
|
+
|
|
66
|
+
This repository is hosted at [iVAE GitHub Repository](https://github.com/PeterPonyu/iVAE).
|
|
67
|
+
|
|
68
|
+
### Requirements
|
|
69
|
+
|
|
70
|
+
- Python >= 3.9
|
|
71
|
+
- PyTorch >= 1.13.1
|
|
72
|
+
- scanpy >= 1.10.4
|
|
73
|
+
- scikit-learn
|
|
74
|
+
- numpy
|
|
75
|
+
- tqdm
|
|
76
|
+
|
|
77
|
+
All dependencies are automatically installed with pip.
|
|
78
|
+
|
|
79
|
+
## Quick Start
|
|
80
|
+
|
|
81
|
+
### Command-Line Interface
|
|
82
|
+
|
|
83
|
+
The simplest way to use iVAE is through the command-line interface:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
# Basic usage with default parameters
|
|
87
|
+
iVAE --data_path data.h5ad --epochs 500 --output_dir results
|
|
88
|
+
|
|
89
|
+
# With custom parameters
|
|
90
|
+
iVAE --data_path data.h5ad \
|
|
91
|
+
--epochs 1000 \
|
|
92
|
+
--latent_dim 15 \
|
|
93
|
+
--i_dim 3 \
|
|
94
|
+
--beta 2.0 \
|
|
95
|
+
--irecon 0.5 \
|
|
96
|
+
--output_dir results
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Python API
|
|
100
|
+
|
|
101
|
+
You can also use iVAE directly in Python scripts:
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
import scanpy as sc
|
|
105
|
+
from iVAE import agent
|
|
106
|
+
|
|
107
|
+
# Load your single-cell data
|
|
108
|
+
adata = sc.read_h5ad('data.h5ad')
|
|
109
|
+
|
|
110
|
+
# Initialize and train the model
|
|
111
|
+
model = agent(
|
|
112
|
+
adata=adata,
|
|
113
|
+
layer='counts', # Layer to use from AnnData
|
|
114
|
+
latent_dim=10, # Number of latent dimensions
|
|
115
|
+
i_dim=2, # Interpretative dimension
|
|
116
|
+
epochs=500
|
|
117
|
+
)
|
|
118
|
+
model.fit(epochs=500)
|
|
119
|
+
|
|
120
|
+
# Extract representations
|
|
121
|
+
latent = model.get_latent() # Main latent representation
|
|
122
|
+
iembed = model.get_iembed() # Interpretative embedding
|
|
123
|
+
|
|
124
|
+
# Use for downstream analysis
|
|
125
|
+
adata.obsm['X_ivae'] = latent
|
|
126
|
+
sc.pp.neighbors(adata, use_rep='X_ivae')
|
|
127
|
+
sc.tl.umap(adata)
|
|
128
|
+
sc.tl.leiden(adata)
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## Usage
|
|
132
|
+
|
|
133
|
+
### Command-Line Arguments
|
|
134
|
+
|
|
135
|
+
You can customize the behavior of the script by providing additional arguments:
|
|
136
|
+
|
|
137
|
+
#### Data Parameters
|
|
138
|
+
- `--data_path`: Path to the h5ad data file (default: 'data.h5ad')
|
|
139
|
+
- `--layer`: Layer to use from the AnnData object (default: 'counts'). Common options: 'counts', 'X', or custom layer names
|
|
140
|
+
- `--output_dir`: Directory to save the results (default: 'iVAE_output')
|
|
141
|
+
|
|
142
|
+
#### Training Parameters
|
|
143
|
+
- `--epochs`: Number of training epochs (default: 1000). More epochs = better convergence but longer training
|
|
144
|
+
- `--lr`: Learning rate for Adam optimizer (default: 1e-4)
|
|
145
|
+
- `--percent`: Fraction of cells per training batch (default: 0.01). Range: (0, 1]. Smaller = more updates but noisier gradients
|
|
146
|
+
|
|
147
|
+
#### Architecture Parameters
|
|
148
|
+
- `--hidden_dim`: Hidden layer dimension in encoder/decoder (default: 128). Larger = more capacity
|
|
149
|
+
- `--latent_dim`: Main latent space dimension (default: 10). Should roughly match expected cell types/states
|
|
150
|
+
- `--i_dim`: Interpretative latent space dimension (default: 2). Creates bottleneck for learning correlated patterns. Should be < latent_dim
|
|
151
|
+
|
|
152
|
+
#### Loss Weight Parameters
|
|
153
|
+
- `--beta`: Weight for KL divergence term (default: 1.0). Higher values encourage latent codes closer to prior distribution
|
|
154
|
+
- `--irecon`: Weight for interpretative reconstruction loss (default: 0.0). If > 0, penalizes reconstruction from interpretative bottleneck
|
|
155
|
+
- `--dip`: Weight for DIP (Disentangled Inferred Prior) loss (default: 0.0). If > 0, encourages diagonal covariance for disentanglement
|
|
156
|
+
- `--tc`: Weight for Total Correlation loss (default: 0.0). If > 0, encourages independent latent dimensions
|
|
157
|
+
- `--info`: Weight for InfoVAE MMD loss (default: 0.0). If > 0, matches aggregated posterior to prior
|
|
158
|
+
|
|
159
|
+
### Example Commands
|
|
160
|
+
|
|
161
|
+
Basic training with default parameters:
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
iVAE --data_path 'path/to/your/data.h5ad' --epochs 500 --output_dir 'results'
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Training with interpretative reconstruction and disentanglement:
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
iVAE --epochs 1000 \
|
|
171
|
+
--layer 'counts' \
|
|
172
|
+
--data_path 'data.h5ad' \
|
|
173
|
+
--latent_dim 15 \
|
|
174
|
+
--i_dim 3 \
|
|
175
|
+
--beta 2.0 \
|
|
176
|
+
--irecon 0.5 \
|
|
177
|
+
--dip 1.0 \
|
|
178
|
+
--output_dir 'ivae_output'
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Output
|
|
182
|
+
|
|
183
|
+
After running the script, the latent space representations are saved in the specified output directory (`iVAE_output` by default):
|
|
184
|
+
|
|
185
|
+
- **`iembed.npy`**: Interpretative embedding from the bottleneck layer (shape: n_cells × i_dim). This compressed representation captures the most important correlated patterns.
|
|
186
|
+
- **`latent.npy`**: Main latent representation (shape: n_cells × latent_dim). This is the primary encoded representation for downstream analysis.
|
|
187
|
+
|
|
188
|
+
These files are NumPy arrays that can be loaded using `numpy.load()` for further analysis.
|
|
189
|
+
|
|
190
|
+
### Example of Loading and Using Output Data
|
|
191
|
+
|
|
192
|
+
You can load and analyze the output data using the following Python code:
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
import numpy as np
|
|
196
|
+
import scanpy as sc
|
|
197
|
+
|
|
198
|
+
# Load the saved representations
|
|
199
|
+
iembed = np.load('iVAE_output/iembed.npy')
|
|
200
|
+
latent = np.load('iVAE_output/latent.npy')
|
|
201
|
+
|
|
202
|
+
# Inspect shapes
|
|
203
|
+
print("Interpretative embedding shape:", iembed.shape) # (n_cells, i_dim)
|
|
204
|
+
print("Latent representation shape:", latent.shape) # (n_cells, latent_dim)
|
|
205
|
+
|
|
206
|
+
# Add to AnnData object for downstream analysis
|
|
207
|
+
adata = sc.read_h5ad('data.h5ad')
|
|
208
|
+
adata.obsm['X_ivae_latent'] = latent
|
|
209
|
+
adata.obsm['X_ivae_iembed'] = iembed
|
|
210
|
+
|
|
211
|
+
# Perform clustering and visualization
|
|
212
|
+
sc.pp.neighbors(adata, use_rep='X_ivae_latent')
|
|
213
|
+
sc.tl.umap(adata)
|
|
214
|
+
sc.tl.leiden(adata, resolution=0.5)
|
|
215
|
+
|
|
216
|
+
# Visualize results
|
|
217
|
+
sc.pl.umap(adata, color=['leiden', 'cell_type'])
|
|
218
|
+
|
|
219
|
+
# Analyze interpretative embedding
|
|
220
|
+
import pandas as pd
|
|
221
|
+
iembed_df = pd.DataFrame(iembed, columns=[f'iDim{i}' for i in range(iembed.shape[1])])
|
|
222
|
+
print(iembed_df.describe())
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
## Advanced Usage
|
|
226
|
+
|
|
227
|
+
### Using Different Regularization Techniques
|
|
228
|
+
|
|
229
|
+
iVAE supports multiple regularization methods that can be combined:
|
|
230
|
+
|
|
231
|
+
```python
|
|
232
|
+
from iVAE import agent
|
|
233
|
+
|
|
234
|
+
# Beta-VAE style training (disentanglement via KL weighting)
|
|
235
|
+
model = agent(adata, beta=4.0, latent_dim=10)
|
|
236
|
+
|
|
237
|
+
# DIP-VAE style training (disentanglement via covariance penalty)
|
|
238
|
+
model = agent(adata, dip=10.0, latent_dim=10)
|
|
239
|
+
|
|
240
|
+
# TC-VAE style training (total correlation penalty)
|
|
241
|
+
model = agent(adata, tc=5.0, latent_dim=10)
|
|
242
|
+
|
|
243
|
+
# InfoVAE style training (MMD between posterior and prior)
|
|
244
|
+
model = agent(adata, info=1.0, latent_dim=10)
|
|
245
|
+
|
|
246
|
+
# Combined approach with interpretative reconstruction
|
|
247
|
+
model = agent(
|
|
248
|
+
adata,
|
|
249
|
+
beta=2.0, # KL regularization
|
|
250
|
+
irecon=0.5, # Interpretative reconstruction
|
|
251
|
+
dip=1.0, # Disentanglement
|
|
252
|
+
latent_dim=15,
|
|
253
|
+
i_dim=3
|
|
254
|
+
)
|
|
255
|
+
model.fit(epochs=1000)
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
### Hyperparameter Tuning Tips
|
|
259
|
+
|
|
260
|
+
- **latent_dim**: Start with the expected number of cell types/states. Can be higher for complex datasets.
|
|
261
|
+
- **i_dim**: Should be significantly smaller than latent_dim (e.g., 2-3 for latent_dim=10).
|
|
262
|
+
- **irecon**: Start with 0.0, gradually increase to 0.5-1.0 if you want stronger interpretability.
|
|
263
|
+
- **beta**: Values > 1 encourage disentanglement but may reduce reconstruction quality. Try 1.0-4.0.
|
|
264
|
+
- **percent**: Use 0.01-0.1 depending on dataset size. Larger datasets can use smaller values.
|
|
265
|
+
- **epochs**: 500-2000 epochs usually sufficient. Monitor loss curves to determine convergence.
|
|
266
|
+
|
|
267
|
+
## API docs
|
|
268
|
+
[](https://ivae.readthedocs.io/en/latest/?badge=latest)
|
|
269
|
+
|
|
270
|
+
The documentation is available. Click the [doc](https://ivae.readthedocs.io/en/latest/) for details.
|
|
271
|
+
|
|
272
|
+
## License
|
|
273
|
+
[](https://choosealicense.com/licenses/mit/)
|
|
274
|
+
|
|
275
|
+
This project is licensed under the MIT License. See the LICENSE file for details.
|
|
276
|
+
|
|
277
|
+
## Zenodo
|
|
278
|
+
[](https://doi.org/10.5281/zenodo.15686686)
|
|
279
|
+
|
|
280
|
+
## Contact
|
|
281
|
+
|
|
282
|
+
For questions or issues, please contact Zeyu Fu at [fuzeyu99@126.com](mailto:fuzeyu99@126.com) or [fuzeyu09@gmail.com](mailto:fuzeyu09@gmail.com).
|
|
283
|
+
|
|
284
|
+
## Cite
|
|
285
|
+
|
|
286
|
+
- Fu, Z., Chen, C., Wang, S. et al. iVAE: an interpretable representation learning framework enhances clustering performance for single-cell data. *BMC Biol* **23**, 213 (2025). https://doi.org/10.1186/s12915-025-02315-7
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
|
|
294
|
+
---
|
ivae_sc-0.0.6/README.md
ADDED
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<a href="https://peterponyu.github.io/">
|
|
3
|
+
<img src="https://peterponyu.github.io/assets/badges/iVAE.svg" width="64" alt="ZF Lab · iVAE">
|
|
4
|
+
</a>
|
|
5
|
+
</div>
|
|
6
|
+
|
|
7
|
+
## About
|
|
8
|
+
|
|
9
|
+
iVAE is a representation learning method for single-cell transcriptomics. Compared with a standard VAE, it adds an interpretative bottleneck that encourages correlated latent structure when those correlations are present in the data.
|
|
10
|
+
|
|
11
|
+
<img src='source/_static/fig.png' width='600' align='center'>
|
|
12
|
+
|
|
13
|
+
## Key Features
|
|
14
|
+
|
|
15
|
+
- **Interpretative Module**: A bottleneck layer that encourages learning of correlated patterns in gene expression
|
|
16
|
+
- **Multiple Loss Functions**: Supports various regularization techniques (KL, DIP, TC, MMD) for improved disentanglement
|
|
17
|
+
- **Single-Cell Optimized**: Uses negative binomial distribution for count data modeling
|
|
18
|
+
- **Python API and CLI**: Supports both scripted and command-line workflows
|
|
19
|
+
- **GPU Accelerated**: Automatic GPU detection and usage when available
|
|
20
|
+
|
|
21
|
+
## Installation
|
|
22
|
+
|
|
23
|
+
[](https://pypi.org/project/ivae-sc/)
|
|
24
|
+
|
|
25
|
+
Install the package from PyPI:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
pip install ivae-sc
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
From version 0.0.6 the package is published on PyPI as `ivae-sc`; the import name is still `iVAE`. The earlier `iVAE` project on PyPI stays at 0.0.5 and is no longer updated.
|
|
32
|
+
|
|
33
|
+
This repository is hosted at [iVAE GitHub Repository](https://github.com/PeterPonyu/iVAE).
|
|
34
|
+
|
|
35
|
+
### Requirements
|
|
36
|
+
|
|
37
|
+
- Python >= 3.9
|
|
38
|
+
- PyTorch >= 1.13.1
|
|
39
|
+
- scanpy >= 1.10.4
|
|
40
|
+
- scikit-learn
|
|
41
|
+
- numpy
|
|
42
|
+
- tqdm
|
|
43
|
+
|
|
44
|
+
All dependencies are automatically installed with pip.
|
|
45
|
+
|
|
46
|
+
## Quick Start
|
|
47
|
+
|
|
48
|
+
### Command-Line Interface
|
|
49
|
+
|
|
50
|
+
The simplest way to use iVAE is through the command-line interface:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
# Basic usage with default parameters
|
|
54
|
+
iVAE --data_path data.h5ad --epochs 500 --output_dir results
|
|
55
|
+
|
|
56
|
+
# With custom parameters
|
|
57
|
+
iVAE --data_path data.h5ad \
|
|
58
|
+
--epochs 1000 \
|
|
59
|
+
--latent_dim 15 \
|
|
60
|
+
--i_dim 3 \
|
|
61
|
+
--beta 2.0 \
|
|
62
|
+
--irecon 0.5 \
|
|
63
|
+
--output_dir results
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Python API
|
|
67
|
+
|
|
68
|
+
You can also use iVAE directly in Python scripts:
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
import scanpy as sc
|
|
72
|
+
from iVAE import agent
|
|
73
|
+
|
|
74
|
+
# Load your single-cell data
|
|
75
|
+
adata = sc.read_h5ad('data.h5ad')
|
|
76
|
+
|
|
77
|
+
# Initialize and train the model
|
|
78
|
+
model = agent(
|
|
79
|
+
adata=adata,
|
|
80
|
+
layer='counts', # Layer to use from AnnData
|
|
81
|
+
latent_dim=10, # Number of latent dimensions
|
|
82
|
+
i_dim=2, # Interpretative dimension
|
|
83
|
+
epochs=500
|
|
84
|
+
)
|
|
85
|
+
model.fit(epochs=500)
|
|
86
|
+
|
|
87
|
+
# Extract representations
|
|
88
|
+
latent = model.get_latent() # Main latent representation
|
|
89
|
+
iembed = model.get_iembed() # Interpretative embedding
|
|
90
|
+
|
|
91
|
+
# Use for downstream analysis
|
|
92
|
+
adata.obsm['X_ivae'] = latent
|
|
93
|
+
sc.pp.neighbors(adata, use_rep='X_ivae')
|
|
94
|
+
sc.tl.umap(adata)
|
|
95
|
+
sc.tl.leiden(adata)
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Usage
|
|
99
|
+
|
|
100
|
+
### Command-Line Arguments
|
|
101
|
+
|
|
102
|
+
You can customize the behavior of the script by providing additional arguments:
|
|
103
|
+
|
|
104
|
+
#### Data Parameters
|
|
105
|
+
- `--data_path`: Path to the h5ad data file (default: 'data.h5ad')
|
|
106
|
+
- `--layer`: Layer to use from the AnnData object (default: 'counts'). Common options: 'counts', 'X', or custom layer names
|
|
107
|
+
- `--output_dir`: Directory to save the results (default: 'iVAE_output')
|
|
108
|
+
|
|
109
|
+
#### Training Parameters
|
|
110
|
+
- `--epochs`: Number of training epochs (default: 1000). More epochs = better convergence but longer training
|
|
111
|
+
- `--lr`: Learning rate for Adam optimizer (default: 1e-4)
|
|
112
|
+
- `--percent`: Fraction of cells per training batch (default: 0.01). Range: (0, 1]. Smaller = more updates but noisier gradients
|
|
113
|
+
|
|
114
|
+
#### Architecture Parameters
|
|
115
|
+
- `--hidden_dim`: Hidden layer dimension in encoder/decoder (default: 128). Larger = more capacity
|
|
116
|
+
- `--latent_dim`: Main latent space dimension (default: 10). Should roughly match expected cell types/states
|
|
117
|
+
- `--i_dim`: Interpretative latent space dimension (default: 2). Creates bottleneck for learning correlated patterns. Should be < latent_dim
|
|
118
|
+
|
|
119
|
+
#### Loss Weight Parameters
|
|
120
|
+
- `--beta`: Weight for KL divergence term (default: 1.0). Higher values encourage latent codes closer to prior distribution
|
|
121
|
+
- `--irecon`: Weight for interpretative reconstruction loss (default: 0.0). If > 0, penalizes reconstruction from interpretative bottleneck
|
|
122
|
+
- `--dip`: Weight for DIP (Disentangled Inferred Prior) loss (default: 0.0). If > 0, encourages diagonal covariance for disentanglement
|
|
123
|
+
- `--tc`: Weight for Total Correlation loss (default: 0.0). If > 0, encourages independent latent dimensions
|
|
124
|
+
- `--info`: Weight for InfoVAE MMD loss (default: 0.0). If > 0, matches aggregated posterior to prior
|
|
125
|
+
|
|
126
|
+
### Example Commands
|
|
127
|
+
|
|
128
|
+
Basic training with default parameters:
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
iVAE --data_path 'path/to/your/data.h5ad' --epochs 500 --output_dir 'results'
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Training with interpretative reconstruction and disentanglement:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
iVAE --epochs 1000 \
|
|
138
|
+
--layer 'counts' \
|
|
139
|
+
--data_path 'data.h5ad' \
|
|
140
|
+
--latent_dim 15 \
|
|
141
|
+
--i_dim 3 \
|
|
142
|
+
--beta 2.0 \
|
|
143
|
+
--irecon 0.5 \
|
|
144
|
+
--dip 1.0 \
|
|
145
|
+
--output_dir 'ivae_output'
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### Output
|
|
149
|
+
|
|
150
|
+
After running the script, the latent space representations are saved in the specified output directory (`iVAE_output` by default):
|
|
151
|
+
|
|
152
|
+
- **`iembed.npy`**: Interpretative embedding from the bottleneck layer (shape: n_cells × i_dim). This compressed representation captures the most important correlated patterns.
|
|
153
|
+
- **`latent.npy`**: Main latent representation (shape: n_cells × latent_dim). This is the primary encoded representation for downstream analysis.
|
|
154
|
+
|
|
155
|
+
These files are NumPy arrays that can be loaded using `numpy.load()` for further analysis.
|
|
156
|
+
|
|
157
|
+
### Example of Loading and Using Output Data
|
|
158
|
+
|
|
159
|
+
You can load and analyze the output data using the following Python code:
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
import numpy as np
|
|
163
|
+
import scanpy as sc
|
|
164
|
+
|
|
165
|
+
# Load the saved representations
|
|
166
|
+
iembed = np.load('iVAE_output/iembed.npy')
|
|
167
|
+
latent = np.load('iVAE_output/latent.npy')
|
|
168
|
+
|
|
169
|
+
# Inspect shapes
|
|
170
|
+
print("Interpretative embedding shape:", iembed.shape) # (n_cells, i_dim)
|
|
171
|
+
print("Latent representation shape:", latent.shape) # (n_cells, latent_dim)
|
|
172
|
+
|
|
173
|
+
# Add to AnnData object for downstream analysis
|
|
174
|
+
adata = sc.read_h5ad('data.h5ad')
|
|
175
|
+
adata.obsm['X_ivae_latent'] = latent
|
|
176
|
+
adata.obsm['X_ivae_iembed'] = iembed
|
|
177
|
+
|
|
178
|
+
# Perform clustering and visualization
|
|
179
|
+
sc.pp.neighbors(adata, use_rep='X_ivae_latent')
|
|
180
|
+
sc.tl.umap(adata)
|
|
181
|
+
sc.tl.leiden(adata, resolution=0.5)
|
|
182
|
+
|
|
183
|
+
# Visualize results
|
|
184
|
+
sc.pl.umap(adata, color=['leiden', 'cell_type'])
|
|
185
|
+
|
|
186
|
+
# Analyze interpretative embedding
|
|
187
|
+
import pandas as pd
|
|
188
|
+
iembed_df = pd.DataFrame(iembed, columns=[f'iDim{i}' for i in range(iembed.shape[1])])
|
|
189
|
+
print(iembed_df.describe())
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## Advanced Usage
|
|
193
|
+
|
|
194
|
+
### Using Different Regularization Techniques
|
|
195
|
+
|
|
196
|
+
iVAE supports multiple regularization methods that can be combined:
|
|
197
|
+
|
|
198
|
+
```python
|
|
199
|
+
from iVAE import agent
|
|
200
|
+
|
|
201
|
+
# Beta-VAE style training (disentanglement via KL weighting)
|
|
202
|
+
model = agent(adata, beta=4.0, latent_dim=10)
|
|
203
|
+
|
|
204
|
+
# DIP-VAE style training (disentanglement via covariance penalty)
|
|
205
|
+
model = agent(adata, dip=10.0, latent_dim=10)
|
|
206
|
+
|
|
207
|
+
# TC-VAE style training (total correlation penalty)
|
|
208
|
+
model = agent(adata, tc=5.0, latent_dim=10)
|
|
209
|
+
|
|
210
|
+
# InfoVAE style training (MMD between posterior and prior)
|
|
211
|
+
model = agent(adata, info=1.0, latent_dim=10)
|
|
212
|
+
|
|
213
|
+
# Combined approach with interpretative reconstruction
|
|
214
|
+
model = agent(
|
|
215
|
+
adata,
|
|
216
|
+
beta=2.0, # KL regularization
|
|
217
|
+
irecon=0.5, # Interpretative reconstruction
|
|
218
|
+
dip=1.0, # Disentanglement
|
|
219
|
+
latent_dim=15,
|
|
220
|
+
i_dim=3
|
|
221
|
+
)
|
|
222
|
+
model.fit(epochs=1000)
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
### Hyperparameter Tuning Tips
|
|
226
|
+
|
|
227
|
+
- **latent_dim**: Start with the expected number of cell types/states. Can be higher for complex datasets.
|
|
228
|
+
- **i_dim**: Should be significantly smaller than latent_dim (e.g., 2-3 for latent_dim=10).
|
|
229
|
+
- **irecon**: Start with 0.0, gradually increase to 0.5-1.0 if you want stronger interpretability.
|
|
230
|
+
- **beta**: Values > 1 encourage disentanglement but may reduce reconstruction quality. Try 1.0-4.0.
|
|
231
|
+
- **percent**: Use 0.01-0.1 depending on dataset size. Larger datasets can use smaller values.
|
|
232
|
+
- **epochs**: 500-2000 epochs usually sufficient. Monitor loss curves to determine convergence.
|
|
233
|
+
|
|
234
|
+
## API docs
|
|
235
|
+
[](https://ivae.readthedocs.io/en/latest/?badge=latest)
|
|
236
|
+
|
|
237
|
+
The documentation is available. Click the [doc](https://ivae.readthedocs.io/en/latest/) for details.
|
|
238
|
+
|
|
239
|
+
## License
|
|
240
|
+
[](https://choosealicense.com/licenses/mit/)
|
|
241
|
+
|
|
242
|
+
This project is licensed under the MIT License. See the LICENSE file for details.
|
|
243
|
+
|
|
244
|
+
## Zenodo
|
|
245
|
+
[](https://doi.org/10.5281/zenodo.15686686)
|
|
246
|
+
|
|
247
|
+
## Contact
|
|
248
|
+
|
|
249
|
+
For questions or issues, please contact Zeyu Fu at [fuzeyu99@126.com](mailto:fuzeyu99@126.com) or [fuzeyu09@gmail.com](mailto:fuzeyu09@gmail.com).
|
|
250
|
+
|
|
251
|
+
## Cite
|
|
252
|
+
|
|
253
|
+
- Fu, Z., Chen, C., Wang, S. et al. iVAE: an interpretable representation learning framework enhances clustering performance for single-cell data. *BMC Biol* **23**, 213 (2025). https://doi.org/10.1186/s12915-025-02315-7
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
---
|