ccvgae 0.3.0__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.
ccvgae-0.3.0/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.
ccvgae-0.3.0/PKG-INFO ADDED
@@ -0,0 +1,416 @@
1
+ Metadata-Version: 2.4
2
+ Name: ccvgae
3
+ Version: 0.3.0
4
+ Summary: CCVGAE: centroid-coupled variational graph attention autoencoder for stable and interpretable single-cell representation learning
5
+ Author: Zeyu Fu
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/PeterPonyu/CCVGAE
8
+ Project-URL: Repository, https://github.com/PeterPonyu/CCVGAE
9
+ Project-URL: Paper, https://doi.org/10.1016/j.array.2026.100808
10
+ Keywords: single-cell,variational autoencoder,graph neural network,scRNA-seq,scATAC-seq
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
17
+ Requires-Python: >=3.9
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Requires-Dist: torch
21
+ Requires-Dist: torch-geometric
22
+ Requires-Dist: numpy
23
+ Requires-Dist: scanpy
24
+ Requires-Dist: anndata
25
+ Requires-Dist: scikit-learn
26
+ Requires-Dist: psutil
27
+ Requires-Dist: tqdm
28
+ Provides-Extra: scvi
29
+ Requires-Dist: scvi-tools; extra == "scvi"
30
+ Provides-Extra: harmony
31
+ Requires-Dist: harmonypy; extra == "harmony"
32
+ Provides-Extra: all
33
+ Requires-Dist: scvi-tools; extra == "all"
34
+ Requires-Dist: harmonypy; extra == "all"
35
+ Dynamic: license-file
36
+
37
+ <div align="center">
38
+ <a href="https://peterponyu.github.io/">
39
+ <img src="https://peterponyu.github.io/assets/badges/CCVGAE.svg" width="64" alt="ZF Lab · CCVGAE">
40
+ </a>
41
+ </div>
42
+
43
+ # CCVGAE: Centroid-based Coupled Variational Graph Autoencoder
44
+
45
+ CCVGAE is a deep learning framework for stable and interpretable analysis of single-cell multi-omics data. It combines centroid-based latent summaries, coupling losses, and graph neural network components in a variational autoencoder workflow.
46
+
47
+ ## Key Features
48
+
49
+ - **Centroid Inference**: Uses deterministic posterior means as stable cell embeddings.
50
+ - **Coupling Mechanism**: Regularizes latent space through intermediate representations.
51
+ - **Graph Neural Networks**: Leverages cell-cell similarity relationships with attention mechanisms.
52
+ - **Scalable Architecture**: Supports subgraph sampling for large-scale datasets.
53
+ - **Flexible Design**: Compatible with multiple encoder/decoder architectures and graph convolution types.
54
+
55
+ ## Table of Contents
56
+ - [Installation](#installation)
57
+ - [Quick Start](#quick-start)
58
+ - [Detailed Usage](#detailed-usage)
59
+ - [Parameters](#parameters)
60
+ - [Advanced Examples](#advanced-examples)
61
+ - [Output and Analysis](#output-and-analysis)
62
+ - [Citation](#citation)
63
+
64
+ ## Installation
65
+
66
+ ### Requirements
67
+ - Python >= 3.7
68
+ - PyTorch >= 1.8.0
69
+ - PyTorch Geometric
70
+ - scanpy
71
+ - anndata
72
+ - scikit-learn
73
+ - numpy
74
+ - psutil
75
+ - tqdm
76
+
77
+ ### Install from PyPI
78
+
79
+ ```bash
80
+ pip install ccvgae
81
+ ```
82
+
83
+ Batch correction with scVI or Harmony needs the optional extras: `pip install "ccvgae[scvi]"` or `pip install "ccvgae[harmony]"`.
84
+
85
+ ### Install from source
86
+
87
+ ```bash
88
+ git clone https://github.com/PeterPonyu/CCVGAE
89
+ cd CCVGAE
90
+ pip install -r requirements.txt
91
+ ```
92
+
93
+ ## Quick Start
94
+
95
+ ```python
96
+ import scanpy as sc
97
+ from ccvgae import CCVGAE_agent
98
+
99
+ adata = sc.read_h5ad("your_data.h5ad")
100
+
101
+ agent = CCVGAE_agent(
102
+ adata=adata,
103
+ layer='counts', # Use the 'counts' layer for training
104
+ n_var=2000, # Number of highly variable genes to use
105
+ n_neighbors=15, # Number of neighbors for graph construction
106
+ latent_dim=10, # Dimension of the latent space
107
+ subgraph_size=512, # Size of subgraphs for training
108
+ num_subgraphs_per_epoch=10, # Number of subgraphs per epoch
109
+ lr=1e-4,
110
+ w_recon=1.0, # Weight for reconstruction loss
111
+ w_irecon=1.0, # Weight for coupling reconstruction loss
112
+ w_kl=1.0, # Weight for KL divergence loss
113
+ )
114
+
115
+ # Train the model
116
+ agent.fit(epochs=300, update_steps=10)
117
+
118
+ latent_representation = agent.get_latent()
119
+
120
+ from sklearn.cluster import KMeans
121
+ clusters = KMeans(n_clusters=10).fit_predict(latent_representation)
122
+ adata.obs['ccvgae_clusters'] = clusters
123
+ ```
124
+
125
+ ## Detailed Usage
126
+
127
+ ### Data Preprocessing
128
+
129
+ CCVGAE automatically handles preprocessing steps including:
130
+ 1. **Normalization**: Total count normalization and log1p transformation
131
+ 2. **Feature Selection**: Highly variable genes selection
132
+ 3. **Dimensionality Reduction**: PCA or other methods (NMF, FastICA, TruncatedSVD, FactorAnalysis, LatentDirichletAllocation)
133
+ 4. **Graph Construction**: k-nearest neighbor graph based on reduced dimensions
134
+ 5. **Batch Correction** (optional): Harmony or scVI integration
135
+
136
+ ```python
137
+ # Example with custom preprocessing options
138
+ agent = CCVGAE_agent(
139
+ adata=adata,
140
+ layer='counts', # Layer containing raw counts
141
+ n_var=3000, # Select top 3000 highly variable genes
142
+ tech='PCA', # Dimensionality reduction method
143
+ n_neighbors=20, # Number of neighbors for KNN graph
144
+ batch_tech='harmony', # Optional: use Harmony for batch correction
145
+ all_feat=False, # Use only highly variable genes
146
+ )
147
+ ```
148
+
149
+ ### Model Architecture Configuration
150
+
151
+ CCVGAE supports flexible architecture configuration:
152
+
153
+ ```python
154
+ agent = CCVGAE_agent(
155
+ adata=adata,
156
+ # Architecture parameters
157
+ encoder_type='graph', # 'graph' or 'linear'
158
+ graph_type='GAT', # 'GAT', 'GCN', 'SAGE', 'Cheb', etc.
159
+ hidden_dim=128, # Hidden layer dimension
160
+ latent_dim=10, # Latent space dimension
161
+ i_dim=10, # Intermediate coupling dimension
162
+ hidden_layers=2, # Number of hidden layers
163
+ decoder_hidden_dim=128, # Decoder hidden dimension
164
+ dropout=0.05, # Dropout rate
165
+ use_residual=True, # Use residual connections
166
+ structure_decoder_type='mlp', # 'mlp', 'bilinear', 'inner_product'
167
+ feature_decoder_type='linear', # Feature decoder type
168
+ )
169
+ ```
170
+
171
+ ### Training Configuration
172
+
173
+ Control training dynamics and loss weighting:
174
+
175
+ ```python
176
+ agent = CCVGAE_agent(
177
+ adata=adata,
178
+ # Training parameters
179
+ lr=1e-4, # Learning rate
180
+ beta=1.0, # KL divergence regularization strength (β-VAE)
181
+ graph=1.0, # Graph reconstruction loss weight
182
+ w_recon=1.0, # Feature reconstruction loss weight
183
+ w_irecon=1.0, # Coupling reconstruction loss weight
184
+ w_kl=1.0, # KL divergence loss weight
185
+ w_adj=1.0, # Adjacency reconstruction loss weight
186
+
187
+ # Subgraph sampling for large datasets
188
+ subgraph_size=512, # Maximum nodes per subgraph
189
+ num_subgraphs_per_epoch=10, # Number of subgraphs per epoch
190
+ sampling_method='random', # Sampling strategy
191
+
192
+ # Device configuration
193
+ device=torch.device('cuda' if torch.cuda.is_available() else 'cpu'),
194
+ latent_type='q_m', # 'q_m' (deterministic) or 'q_z' (stochastic)
195
+ )
196
+
197
+ # Train the model
198
+ agent.fit(epochs=300, update_steps=10, silent=False)
199
+ ```
200
+
201
+ ## Parameters
202
+
203
+ ### Core Parameters
204
+
205
+ | Parameter | Type | Default | Description |
206
+ |-----------|------|---------|-------------|
207
+ | `adata` | AnnData | Required | Annotated data object containing single-cell data |
208
+ | `layer` | str | 'counts' | Data layer to use for training |
209
+ | `n_var` | int | None | Number of highly variable genes (None for automatic) |
210
+ | `latent_dim` | int | 10 | Dimension of the main latent space |
211
+ | `hidden_dim` | int | 128 | Hidden layer dimension for networks |
212
+
213
+ ### Architecture Parameters
214
+
215
+ | Parameter | Type | Default | Description |
216
+ |-----------|------|---------|-------------|
217
+ | `encoder_type` | str | 'graph' | Encoder type: 'graph' or 'linear' |
218
+ | `graph_type` | str | 'GAT' | Graph convolution type: 'GAT', 'GCN', 'SAGE', 'Cheb', 'TAG', 'ARMA', 'Transformer', 'SG', 'SSG' |
219
+ | `structure_decoder_type` | str | 'mlp' | Structure decoder: 'mlp', 'bilinear', 'inner_product' |
220
+ | `feature_decoder_type` | str | 'linear' | Feature decoder type: 'linear' |
221
+ | `hidden_layers` | int | 2 | Number of hidden layers |
222
+ | `dropout` | float | 0.05 | Dropout probability for regularization |
223
+ | `use_residual` | bool | True | Whether to use residual connections |
224
+ | `i_dim` | int | 10 | Intermediate coupling space dimension |
225
+
226
+ ### Training Parameters
227
+
228
+ | Parameter | Type | Default | Description |
229
+ |-----------|------|---------|-------------|
230
+ | `lr` | float | 1e-4 | Learning rate for Adam optimizer |
231
+ | `w_recon` | float | 1.0 | Weight for feature reconstruction loss |
232
+ | `w_irecon` | float | 1.0 | Weight for coupling reconstruction loss |
233
+ | `w_kl` | float | 1.0 | Weight for KL divergence loss |
234
+ | `w_adj` | float | 1.0 | Weight for adjacency reconstruction loss |
235
+ | `beta` | float | 1.0 | KL divergence regularization strength (β-VAE) |
236
+ | `graph` | float | 1.0 | Graph reconstruction loss weight |
237
+
238
+ ### Data Processing Parameters
239
+
240
+ | Parameter | Type | Default | Description |
241
+ |-----------|------|---------|-------------|
242
+ | `tech` | str | 'PCA' | Dimensionality reduction: 'PCA', 'NMF', 'FastICA', 'TruncatedSVD', 'FactorAnalysis', 'LatentDirichletAllocation' |
243
+ | `n_neighbors` | int | 15 | Number of neighbors for graph construction |
244
+ | `batch_tech` | str | None | Batch correction method: None, 'harmony', or 'scvi' |
245
+ | `all_feat` | bool | False | Use all features (True) or just highly variable genes (False) |
246
+
247
+ ### Subgraph Sampling Parameters
248
+
249
+ | Parameter | Type | Default | Description |
250
+ |-----------|------|---------|-------------|
251
+ | `subgraph_size` | int | 512 | Maximum number of nodes per subgraph |
252
+ | `num_subgraphs_per_epoch` | int | 10 | Number of subgraphs sampled per training epoch |
253
+ | `sampling_method` | str | 'random' | Subgraph sampling strategy |
254
+
255
+ ## Advanced Examples
256
+
257
+ ### Example 1: Multi-batch Integration
258
+
259
+ ```python
260
+ import scanpy as sc
261
+ from ccvgae import CCVGAE_agent
262
+
263
+ # Load data with multiple batches
264
+ adata = sc.read_h5ad("multi_batch_data.h5ad")
265
+
266
+ # Ensure batch information is in adata.obs
267
+ # adata.obs['batch'] should contain batch labels
268
+
269
+ # Initialize with batch correction
270
+ agent = CCVGAE_agent(
271
+ adata=adata,
272
+ layer='counts',
273
+ n_var=2000,
274
+ batch_tech='harmony', # Use Harmony for batch correction
275
+ n_neighbors=15,
276
+ latent_dim=20,
277
+ )
278
+
279
+ agent.fit(epochs=500, update_steps=20)
280
+ latent = agent.get_latent()
281
+
282
+ # Add latent representation to adata for visualization
283
+ adata.obsm['X_ccvgae'] = latent
284
+ sc.pp.neighbors(adata, use_rep='X_ccvgae')
285
+ sc.tl.umap(adata)
286
+ sc.pl.umap(adata, color=['batch', 'cell_type'])
287
+ ```
288
+
289
+ ### Example 2: Large Dataset with Subgraph Sampling
290
+
291
+ ```python
292
+ # For datasets with > 10,000 cells, use subgraph sampling
293
+ agent = CCVGAE_agent(
294
+ adata=large_adata,
295
+ layer='counts',
296
+ n_var=2000,
297
+ latent_dim=15,
298
+ subgraph_size=1024, # Larger subgraphs
299
+ num_subgraphs_per_epoch=20, # More subgraphs per epoch
300
+ )
301
+
302
+ agent.fit(epochs=300, update_steps=10)
303
+ ```
304
+
305
+ ### Example 3: Custom Loss Weights
306
+
307
+ ```python
308
+ # Fine-tune loss weights for specific analysis needs
309
+ agent = CCVGAE_agent(
310
+ adata=adata,
311
+ layer='counts',
312
+ n_var=2000,
313
+ latent_dim=10,
314
+ w_recon=1.0, # Standard reconstruction
315
+ w_irecon=0.5, # Reduce coupling weight
316
+ w_kl=0.8, # Reduce KL weight for more flexibility
317
+ w_adj=1.2, # Emphasize graph structure learning
318
+ beta=0.5, # Lighter regularization
319
+ )
320
+
321
+ agent.fit(epochs=300, update_steps=10)
322
+ ```
323
+
324
+ ### Example 4: Linear Encoder (Faster Training)
325
+
326
+ ```python
327
+ # Use linear encoder when graph structure is less important
328
+ agent = CCVGAE_agent(
329
+ adata=adata,
330
+ layer='counts',
331
+ n_var=2000,
332
+ encoder_type='linear', # Faster than graph encoder
333
+ latent_dim=10,
334
+ hidden_dim=256,
335
+ hidden_layers=3,
336
+ )
337
+
338
+ agent.fit(epochs=200, update_steps=10)
339
+ ```
340
+
341
+ ## Output and Analysis
342
+
343
+ ### Extracting Latent Representations
344
+
345
+ ```python
346
+ # Get latent representations (deterministic posterior means)
347
+ latent = agent.get_latent() # Shape: (n_cells, latent_dim)
348
+
349
+ # Add to AnnData for downstream analysis
350
+ adata.obsm['X_ccvgae'] = latent
351
+ ```
352
+
353
+ ### Evaluation Metrics
354
+
355
+ During training, CCVGAE tracks several metrics:
356
+ - **Loss**: Total loss value
357
+ - **ARI**: Adjusted Rand Index (clustering quality)
358
+ - **NMI**: Normalized Mutual Information
359
+ - **ASW**: Average Silhouette Width
360
+ - **C_H**: Calinski-Harabasz Index
361
+ - **D_B**: Davies-Bouldin Index
362
+ - **P_C**: Average pairwise correlation
363
+
364
+ ```python
365
+ # Access final scores after training
366
+ agent.score_final()
367
+ print(f"Final scores: {agent.final_score}")
368
+ ```
369
+
370
+ ### Downstream Analysis
371
+
372
+ ```python
373
+ # Clustering
374
+ from sklearn.cluster import KMeans
375
+ clusters = KMeans(n_clusters=8).fit_predict(latent)
376
+ adata.obs['ccvgae_clusters'] = clusters
377
+
378
+ # Visualization with UMAP
379
+ adata.obsm['X_ccvgae'] = latent
380
+ sc.pp.neighbors(adata, use_rep='X_ccvgae')
381
+ sc.tl.umap(adata)
382
+ sc.pl.umap(adata, color=['ccvgae_clusters', 'cell_type'])
383
+
384
+ # Trajectory inference
385
+ import scanpy as sc
386
+ sc.tl.diffmap(adata, use_rep='X_ccvgae')
387
+ sc.tl.dpt(adata)
388
+ ```
389
+
390
+ ## Citation
391
+
392
+ If you use CCVGAE, please cite the article:
393
+
394
+ > Fu Z, Liu Y, Wang J, Wang S. CCVGAE: A centroid-coupled variational graph attention autoencoder for stable and interpretable single-cell representation learning. *Array*. 2026;30:100808. https://doi.org/10.1016/j.array.2026.100808
395
+
396
+ ```bibtex
397
+ @article{fu2026ccvgae,
398
+ author = {Fu, Zeyu and Liu, Yiyao and Wang, Junping and Wang, Song},
399
+ title = {CCVGAE: A centroid-coupled variational graph attention autoencoder for stable and interpretable single-cell representation learning},
400
+ journal = {Array},
401
+ volume = {30},
402
+ pages = {100808},
403
+ year = {2026},
404
+ doi = {10.1016/j.array.2026.100808}
405
+ }
406
+ ```
407
+
408
+ GitHub's "Cite this repository" button reads the same record from `CITATION.cff`.
409
+
410
+ ## License
411
+
412
+ This project is licensed under the terms specified in the LICENSE file.
413
+
414
+ ## Support
415
+
416
+ For questions, issues, or feature requests, please open an issue on GitHub.