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 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
+ [![PyPI](https://img.shields.io/pypi/v/ivae-sc.svg?color=brightgreen&style=flat)](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
+ [![Documentation Status](https://readthedocs.org/projects/ivae/badge/?version=latest)](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
+ [![PyPI](https://img.shields.io/github/license/PeterPonyu/iVAE?style=flat-square&color=brightgreen)](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
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15686686.svg)](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
+ ---
@@ -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
+ [![PyPI](https://img.shields.io/pypi/v/ivae-sc.svg?color=brightgreen&style=flat)](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
+ [![Documentation Status](https://readthedocs.org/projects/ivae/badge/?version=latest)](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
+ [![PyPI](https://img.shields.io/github/license/PeterPonyu/iVAE?style=flat-square&color=brightgreen)](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
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15686686.svg)](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
+ ---
@@ -0,0 +1,6 @@
1
+ from .agent import agent
2
+ from .cli import main
3
+
4
+ __all__ = ['agent', 'main']
5
+
6
+ __version__ = '0.0.6'