gnodevae 0.0.3__py3-none-any.whl

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.
@@ -0,0 +1,330 @@
1
+ Metadata-Version: 2.4
2
+ Name: gnodevae
3
+ Version: 0.0.3
4
+ Summary: A Graph-Based ODE-VAE Enhances Clustering for Single-Cell Data
5
+ Author-email: Zeyu Fu <fuzeyu99@126.com>
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/GNODEVAE
29
+ Project-URL: Source, https://github.com/PeterPonyu/GNODEVAE
30
+ Project-URL: Issues, https://github.com/PeterPonyu/GNODEVAE/issues
31
+ Keywords: single-cell,graph-neural-network,neural-ode,variational-autoencoder,bioinformatics
32
+ Classifier: Development Status :: 3 - Alpha
33
+ Classifier: Programming Language :: Python :: 3
34
+ Classifier: Programming Language :: Python :: 3.9
35
+ Classifier: Programming Language :: Python :: 3.10
36
+ Classifier: Programming Language :: Python :: 3.11
37
+ Classifier: Programming Language :: Python :: 3.12
38
+ Classifier: License :: OSI Approved :: MIT License
39
+ Classifier: Intended Audience :: Science/Research
40
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
41
+ Requires-Python: >=3.9
42
+ Description-Content-Type: text/markdown
43
+ License-File: LICENSE
44
+ Requires-Dist: torch>=1.13.0
45
+ Requires-Dist: torch-geometric>=2.0.0
46
+ Requires-Dist: scanpy>=1.8.0
47
+ Requires-Dist: anndata>=0.8.0
48
+ Requires-Dist: numpy>=1.20.0
49
+ Requires-Dist: pandas>=1.3.0
50
+ Requires-Dist: scikit-learn>=1.0.0
51
+ Requires-Dist: tqdm>=4.60.0
52
+ Requires-Dist: psutil>=5.8.0
53
+ Requires-Dist: torchdiffeq>=0.2.0
54
+ Dynamic: license-file
55
+
56
+ # GNODEVAE: A Graph-Based ODE-VAE Enhances Clustering of Single-Cell Data
57
+
58
+ ## Graphical Abstract
59
+
60
+ ![GNODEVAE Graphical Abstract](gnodevae_abs.jpeg)
61
+
62
+ ## Introduction
63
+
64
+ GNODEVAE is an innovative computational framework that integrates Graph Attention Networks (GAT), Neural Ordinary Differential Equations (NODE), and Variational Autoencoders (VAE). It addresses three critical challenges in single-cell RNA sequencing data analysis:
65
+
66
+ 1. Capturing complex topological relationships between cells
67
+ 2. Modeling continuous dynamic processes of cell differentiation
68
+ 3. Handling high levels of technical noise and biological variation
69
+
70
+ This novel integration significantly improves the accurate identification of cell subpopulations, reconstruction of developmental trajectories, and understanding of cellular heterogeneity.
71
+
72
+ ## Key Contributions
73
+
74
+ ### 1. Dynamic Attention Weighting for Biological Significance
75
+
76
+ The GAT's attention mechanism adaptively weights gene expression profiles, prioritizing meaningful biological relationships while minimizing technical noise - particularly valuable for heterogeneous cell populations.
77
+
78
+ ### 2. Continuous-Time Developmental Modeling via Neural ODEs
79
+
80
+ Integration of neural ordinary differential equations transforms static representations into dynamic systems, with time variables providing natural parameterization of developmental processes and enabling predictions at any point in cellular development.
81
+
82
+ ### 3. Biologically Consistent Latent Space Representations
83
+
84
+ The model's latent space effectively captures biological phenomena like varying rates of cell differentiation, while attention weights align with established developmental relationships between cell types.
85
+
86
+ ### 4. Comprehensive Benchmark Leadership
87
+
88
+ When compared with six advanced single-cell analysis methods (scVI, DIP-VAE, TC-VAE, β-VAE, Info-VAE, and scTour), GNODEVAE ranked first across all 13 test datasets, demonstrating exceptional versatility across diverse biological contexts.
89
+
90
+ ### 5. Superior Gene Trend Analysis Performance
91
+
92
+ Quantitative evaluation shows GNODEVAE significantly outperforms existing methods (69.97% improvement over Palantir, 63.58% over Diffmap) in Calinski-Harabasz index, demonstrating clearer clustering and stronger category discrimination.
93
+
94
+
95
+ ## Installation
96
+
97
+ ### Prerequisites
98
+
99
+ - Python 3.8 or higher
100
+ - PyTorch 1.12 or higher (with CUDA support recommended for GPU acceleration)
101
+ - PyTorch Geometric
102
+
103
+ ### Install from Source
104
+
105
+ ```bash
106
+ # Clone the repository
107
+ git clone https://github.com/PeterPonyu/GNODEVAE.git
108
+ cd GNODEVAE
109
+
110
+ # Install dependencies
111
+ pip install torch torch-geometric scanpy anndata numpy pandas scikit-learn tqdm psutil torchdiffeq
112
+ ```
113
+
114
+ ### Dependencies
115
+
116
+ The main dependencies include:
117
+ - `torch` - PyTorch deep learning framework
118
+ - `torch-geometric` - Geometric deep learning extension for PyTorch
119
+ - `scanpy` - Single-cell analysis toolkit
120
+ - `anndata` - Annotated data structures for single-cell data
121
+ - `torchdiffeq` - Differentiable ODE solvers for PyTorch
122
+ - `numpy`, `pandas` - Data manipulation
123
+ - `scikit-learn` - Machine learning utilities
124
+ - `tqdm` - Progress bars
125
+ - `psutil` - System resource monitoring
126
+
127
+ ## Quick Start
128
+
129
+ ### Basic Usage
130
+
131
+ ```python
132
+ import scanpy as sc
133
+ from GNODEVAE import agent_r # GraphVAE with refined architecture
134
+ # OR
135
+ from GNODEVAE import agent # Standard GraphVAE
136
+ # For full GNODEVAE with ODE support, use:
137
+ # from GNODEVAE.GODEVAE_agent import GNODEVAE_agent_r
138
+
139
+ # Load your single-cell data
140
+ adata = sc.read_h5ad('your_data.h5ad')
141
+
142
+ # Initialize the GNODEVAE agent
143
+ model = agent_r(
144
+ adata=adata,
145
+ layer='counts', # Layer containing count data
146
+ n_var=2000, # Number of highly variable genes
147
+ tech='PCA', # Dimensionality reduction technique
148
+ n_neighbors=15, # Number of neighbors for graph construction
149
+ latent_dim=10, # Latent space dimension
150
+ hidden_dim=128, # Hidden layer dimension
151
+ encoder_type='graph', # Use graph encoder
152
+ graph_type='GAT', # Graph Attention Network
153
+ lr=1e-4, # Learning rate
154
+ device='cuda' # Use GPU if available
155
+ )
156
+
157
+ # Train the model
158
+ model.fit(epochs=300, update_steps=10, silent=False)
159
+
160
+ # Extract latent representations
161
+ latent = model.get_latent()
162
+
163
+ # Store latent representation in AnnData object
164
+ adata.obsm['X_gnodevae'] = latent
165
+
166
+ # Perform downstream analysis (e.g., clustering)
167
+ import scanpy as sc
168
+ sc.pp.neighbors(adata, use_rep='X_gnodevae')
169
+ sc.tl.leiden(adata)
170
+ sc.tl.umap(adata)
171
+ ```
172
+
173
+ ### Using Standard GraphVAE (without ODE)
174
+
175
+ ```python
176
+ from GNODEVAE import agent
177
+
178
+ # Initialize standard GraphVAE agent
179
+ model = agent(
180
+ adata=adata,
181
+ layer='counts',
182
+ n_var=2000,
183
+ tech='PCA',
184
+ n_neighbors=15,
185
+ latent_dim=10,
186
+ hidden_dim=128,
187
+ encoder_type='GAT',
188
+ lr=1e-4
189
+ )
190
+
191
+ # Train and extract embeddings
192
+ model.fit(epochs=300)
193
+ latent = model.get_latent()
194
+ ```
195
+
196
+ ## Key Parameters
197
+
198
+ ### Data Preprocessing Parameters
199
+ - `layer` (str): Layer of AnnData to use (default: 'counts')
200
+ - `n_var` (int): Number of highly variable genes to select (default: None, uses all)
201
+ - `tech` (str): Dimensionality reduction method - 'PCA', 'NMF', 'FastICA', 'TruncatedSVD', 'FactorAnalysis', or 'LatentDirichletAllocation' (default: 'PCA')
202
+ - `n_neighbors` (int): Number of neighbors for graph construction (default: 15)
203
+ - `batch_tech` (str): Batch correction method - 'harmony' or 'scvi' (default: None)
204
+ - `all_feat` (bool): Whether to use all features or only highly variable genes (default: True)
205
+
206
+ ### Model Architecture Parameters
207
+ - `hidden_dim` (int): Hidden layer dimension (default: 128)
208
+ - `latent_dim` (int): Latent space dimension for embeddings (default: 10)
209
+ - `encoder_type` (str): Encoder type - 'graph' or 'linear' (default: 'graph')
210
+ - `graph_type` (str): Graph convolution type - 'GAT', 'GCN', 'SAGE', 'Transformer', etc. (default: 'GAT')
211
+ - `structure_decoder_type` (str): Structure decoder type - 'mlp', 'bilinear', or 'inner_product' (default: 'mlp')
212
+ - `feature_decoder_type` (str): Feature decoder type - 'linear' or 'graph' (default: 'linear')
213
+ - `hidden_layers` (int): Number of hidden layers (default: 2)
214
+ - `dropout` (float): Dropout rate (default: 0.05)
215
+ - `use_residual` (bool): Whether to use residual connections (default: True)
216
+
217
+ ### Training Parameters
218
+ - `lr` (float): Learning rate for optimizer (default: 1e-4)
219
+ - `beta` (float): Weight for KL divergence loss term (default: 1.0)
220
+ - `graph` (float): Weight for graph reconstruction loss (default: 1.0)
221
+ - `epochs` (int): Number of training epochs (default: 300)
222
+ - `device` (str or torch.device): Computing device - 'cuda' or 'cpu' (default: auto-detect)
223
+ - `num_parts` (int): Number of graph partitions for mini-batch training (default: 10)
224
+
225
+ ### GNODEVAE-Specific Parameters (agent_r)
226
+ - `n_ode_hidden` (int): Number of hidden units in ODE function (default: varies)
227
+ - `w_recon` (float): Weight for reconstruction loss (default: 1.0)
228
+ - `w_kl` (float): Weight for KL divergence loss (default: 1.0)
229
+ - `w_adj` (float): Weight for adjacency matrix loss (default: 1.0)
230
+ - `w_recon_ode` (float): Weight for ODE reconstruction loss (default: 1.0)
231
+
232
+ ## Model Architecture
233
+
234
+ GNODEVAE consists of three main components:
235
+
236
+ 1. **Graph Encoder**: Encodes cell-cell relationships and gene expression using Graph Attention Networks (GAT) or other graph convolution layers
237
+ 2. **Neural ODE**: Models continuous developmental trajectories in the latent space
238
+ 3. **Decoder**: Reconstructs both graph structure and gene expression from latent representations
239
+
240
+ The model learns a low-dimensional latent representation that captures:
241
+ - Cell type identity
242
+ - Developmental state
243
+ - Cell-cell relationships
244
+ - Temporal dynamics (with ODE component)
245
+
246
+ ## Output
247
+
248
+ After training, GNODEVAE produces:
249
+ - **Latent representations**: Low-dimensional embeddings for each cell
250
+ - **Clustering metrics**: ARI, NMI, Silhouette score, Calinski-Harabasz index, Davies-Bouldin index
251
+ - **Pseudo-time**: Developmental trajectory information (for agent_r with ODE)
252
+ - **Graph structure**: Learned cell-cell similarity graph
253
+
254
+ ## Advanced Usage
255
+
256
+ ### Custom Graph Construction
257
+
258
+ ```python
259
+ # Use custom graph construction parameters
260
+ model = agent_r(
261
+ adata=adata,
262
+ n_neighbors=30, # Increase neighbors for denser graph
263
+ graph_type='Transformer', # Use Transformer convolution
264
+ alpha=0.5 # Set alpha for specific layers
265
+ )
266
+ ```
267
+
268
+ ### Interpretable Mode
269
+
270
+ ```python
271
+ # Use interpretable GraphVAE
272
+ model = agent(
273
+ adata=adata,
274
+ interpretable=True, # Enable interpretable mode
275
+ idim=2 # Interpretable dimension
276
+ )
277
+ ```
278
+
279
+ ### Extract Pseudo-time
280
+
281
+ ```python
282
+ # For GNODEVAE models with ODE component
283
+ # Note: Use GNODEVAE_agent_r from GODEVAE_agent module for pseudo-time functionality
284
+ from GNODEVAE.GODEVAE_agent import GNODEVAE_agent_r
285
+
286
+ model = GNODEVAE_agent_r(adata=adata, ...)
287
+ model.fit(epochs=300)
288
+
289
+ # Get pseudo-time for cells
290
+ pseudotime_df = model.partition_time()
291
+ ```
292
+
293
+ ## Evaluation Metrics
294
+
295
+ GNODEVAE automatically computes several clustering quality metrics during training:
296
+ - **ARI** (Adjusted Rand Index): Measures clustering agreement with ground truth
297
+ - **NMI** (Normalized Mutual Information): Information-theoretic clustering metric
298
+ - **ASW** (Average Silhouette Width): Measures cluster separation
299
+ - **C_H** (Calinski-Harabasz Index): Ratio of between-cluster to within-cluster variance
300
+ - **D_B** (Davies-Bouldin Index): Average similarity between clusters
301
+ - **P_C** (Pearson Correlation): Correlation between latent dimensions
302
+
303
+ ## Citation
304
+
305
+ If you use GNODEVAE in your research, please cite:
306
+
307
+ ```bibtex
308
+ @article{fu2025gnodevae,
309
+ title={GNODEVAE: a graph-based ODE-VAE enhances clustering for single-cell data},
310
+ author={Fu, Z. and Chen, C. and Wang, S. and others},
311
+ journal={BMC Genomics},
312
+ volume={26},
313
+ pages={767},
314
+ year={2025},
315
+ doi={10.1186/s12864-025-11946-7}
316
+ }
317
+ ```
318
+
319
+ **Full Citation:**
320
+ Fu, Z., Chen, C., Wang, S. et al. GNODEVAE: a graph-based ODE-VAE enhances clustering for single-cell data. BMC Genomics 26, 767 (2025). https://doi.org/10.1186/s12864-025-11946-7
321
+
322
+ [![DOI](https://zenodo.org/badge/988780888.svg)](https://doi.org/10.5281/zenodo.15826042)
323
+
324
+ ## License
325
+
326
+ See LICENSE file for details.
327
+
328
+ ## Contact
329
+
330
+ For questions and feedback, please open an issue on the GitHub repository.
@@ -0,0 +1,23 @@
1
+ GNODEVAE/CLEAR.py,sha256=8MMUa2N_fta4dpYupCJIwIIKEDCWpFWCJTNwEXw5u88,6680
2
+ GNODEVAE/GODEVAE.py,sha256=K9r-gD18vD_KtzKdrhzAeONNPvig8-13R6r948s71Gw,15930
3
+ GNODEVAE/GODEVAE_agent.py,sha256=Er6tBKpdhj2cE4uUoikft7kflIwZpelpmoALDAnPIpo,14129
4
+ GNODEVAE/GODEVAE_env.py,sha256=E2GdQ8beChDMDMPVzm8afCECamsEl9mrotyKGnSaNq0,26827
5
+ GNODEVAE/GODEVAE_trainer.py,sha256=BcKHl6L5-C4yN02L27_GAyUl9AteNyPwpEWp0kC1upE,11092
6
+ GNODEVAE/SC3.py,sha256=mWknt91wbeGvdYoiiYpG39F07Bz8dNjxUbijBp9iw_o,8322
7
+ GNODEVAE/__init__.py,sha256=JvOj7J_-n5E25xYCWQqT_8ybuOeqTiN9FJUzcTk3ebc,196
8
+ GNODEVAE/agent.py,sha256=2n0Mf6sC3M7FVXoE9fi89V952_q05Km0e7DOlHvW0r0,17103
9
+ GNODEVAE/env.py,sha256=C7hWIZjcbNsEMnMw9fC8NTq6IA9iUuersMdyjw05gj4,14428
10
+ GNODEVAE/mixin.py,sha256=G9uD99jy1sjZnHWsQOZ4rFWocLDjRW0FlM6_TpBQ8ss,14990
11
+ GNODEVAE/module.py,sha256=W5bIkzuXvqENtv5SJ8nJ2gG_h7u8sbif5-sP0uuLmOw,34969
12
+ GNODEVAE/module_refined.py,sha256=Ii3ECuOMB8Bjou-gZXXJW_Y26vAYP6nyYdRT5Xc4Hu0,20158
13
+ GNODEVAE/partition_time.py,sha256=c_lO-8FhS_Pj7BBZMXP67TLF2_XvYDJRGgP5y7w87Yw,6280
14
+ GNODEVAE/scGCC.py,sha256=TluCDszhEcyZ1wXzuLOpo5dBzXD93-yAXD6DkayivRY,7832
15
+ GNODEVAE/scGNN.py,sha256=nCVi_JWFySN46BoX2WlrLDsXQ4BH3gQYdGAqlyEXFM4,6188
16
+ GNODEVAE/trainer.py,sha256=dAdUJA0CyjtILnSLpHoLYuZudwj_d2etJ0FHtHB_EOo,13452
17
+ GNODEVAE/utils.py,sha256=I1WrHpK7v3sMJQdKQTRkLCiYy6Q2VotwMvFVdk8XQAk,15677
18
+ GNODEVAE/utils_ODE.py,sha256=gStxCqXdHMq3UgBqFwoqU-xl2EuhYk8LlMRAxMdjcYo,4952
19
+ gnodevae-0.0.3.dist-info/licenses/LICENSE,sha256=eHiyf509g75dhcKRi3G4eVJWaltCAwYdQ3T2yMn7d1I,1064
20
+ gnodevae-0.0.3.dist-info/METADATA,sha256=NrvWnA2eRwW-Tb13bx94CYzAG6ApDup-DkMkexwV4CU,12885
21
+ gnodevae-0.0.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
22
+ gnodevae-0.0.3.dist-info/top_level.txt,sha256=6mY_IDiMn4UY5Hiwz_hkvUOQ1To9zJzFOjL_cXTzMEE,9
23
+ gnodevae-0.0.3.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (82.0.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -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 @@
1
+ GNODEVAE