ccvgae 0.3.0__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.
- ccvgae/CCVGAE.py +390 -0
- ccvgae/CCVGAE_agent.py +339 -0
- ccvgae/CCVGAE_env.py +493 -0
- ccvgae/CCVGAE_module.py +525 -0
- ccvgae/CCVGAE_trainer.py +306 -0
- ccvgae/__init__.py +5 -0
- ccvgae/mixin.py +376 -0
- ccvgae/utils.py +349 -0
- ccvgae-0.3.0.dist-info/METADATA +416 -0
- ccvgae-0.3.0.dist-info/RECORD +13 -0
- ccvgae-0.3.0.dist-info/WHEEL +5 -0
- ccvgae-0.3.0.dist-info/licenses/LICENSE +21 -0
- ccvgae-0.3.0.dist-info/top_level.txt +1 -0
ccvgae/CCVGAE.py
ADDED
|
@@ -0,0 +1,390 @@
|
|
|
1
|
+
|
|
2
|
+
"""
|
|
3
|
+
CCVGAE: Centroid-based Coupled Variational Graph Autoencoder
|
|
4
|
+
|
|
5
|
+
This module implements CCVGAE, a novel deep generative model for single-cell multi-omics
|
|
6
|
+
data integration. CCVGAE addresses the challenges of high dimensionality, noise, and
|
|
7
|
+
instability in standard VAEs through three key innovations:
|
|
8
|
+
|
|
9
|
+
1. **Centroid Inference**: Uses deterministic posterior mean as stable cell embeddings,
|
|
10
|
+
decoupling analysis from stochastic training for improved reproducibility and
|
|
11
|
+
geometric integrity.
|
|
12
|
+
|
|
13
|
+
2. **Coupling Mechanism**: Regularizes the latent space through an intermediate
|
|
14
|
+
representation that enhances model stability and performance.
|
|
15
|
+
|
|
16
|
+
3. **Graph Attention Networks**: Leverages cell-cell similarity relationships to
|
|
17
|
+
capture complex biological structures in the data.
|
|
18
|
+
|
|
19
|
+
The architecture supports both linear and graph-based encoders/decoders, providing
|
|
20
|
+
flexibility for different data types and analysis requirements.
|
|
21
|
+
|
|
22
|
+
Reference:
|
|
23
|
+
"CCVGAE: A Centroid-based Coupled Variational Graph Autoencoder for
|
|
24
|
+
Single-cell Multi-omics Data Integration"
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
from typing import Optional, Tuple
|
|
28
|
+
|
|
29
|
+
import torch
|
|
30
|
+
import torch.nn as nn
|
|
31
|
+
import torch.nn.functional as F
|
|
32
|
+
from torch.distributions import Normal
|
|
33
|
+
|
|
34
|
+
from .CCVGAE_module import (
|
|
35
|
+
BaseGraphNetwork,
|
|
36
|
+
BaseLinearModel,
|
|
37
|
+
LinearDecoder,
|
|
38
|
+
)
|
|
39
|
+
from .utils import GraphStructureDecoder
|
|
40
|
+
|
|
41
|
+
class GraphEncoder(BaseGraphNetwork):
|
|
42
|
+
"""
|
|
43
|
+
Graph-based encoder component of CCVGAE.
|
|
44
|
+
|
|
45
|
+
This encoder leverages graph neural networks to capture cell-cell relationships
|
|
46
|
+
and similarity structures in single-cell data. It produces variational parameters
|
|
47
|
+
for the latent representation while maintaining the graph topology information.
|
|
48
|
+
|
|
49
|
+
The encoder implements the Centroid Inference mechanism by generating both
|
|
50
|
+
stochastic samples (q_z) and deterministic means (q_m) for downstream analysis.
|
|
51
|
+
"""
|
|
52
|
+
|
|
53
|
+
def __init__(
|
|
54
|
+
self,
|
|
55
|
+
input_dim: int,
|
|
56
|
+
hidden_dim: int,
|
|
57
|
+
latent_dim: int,
|
|
58
|
+
conv_layer_type: str = 'GAT',
|
|
59
|
+
hidden_layers: int = 2,
|
|
60
|
+
dropout: float = 0.05,
|
|
61
|
+
Cheb_k: int = 1,
|
|
62
|
+
alpha: float = 0.5,
|
|
63
|
+
) -> None:
|
|
64
|
+
"""
|
|
65
|
+
Initialize the graph encoder.
|
|
66
|
+
|
|
67
|
+
Args:
|
|
68
|
+
input_dim: Dimension of input cell features (e.g., gene expression)
|
|
69
|
+
hidden_dim: Dimension of hidden layers in the network
|
|
70
|
+
latent_dim: Dimension of the latent embedding space
|
|
71
|
+
conv_layer_type: Type of graph convolution ('GAT', 'GCN', etc.)
|
|
72
|
+
hidden_layers: Number of hidden graph convolution layers
|
|
73
|
+
dropout: Dropout probability for regularization
|
|
74
|
+
Cheb_k: Order parameter for Chebyshev convolution (if applicable)
|
|
75
|
+
alpha: Alpha parameter for SSG convolution (if applicable)
|
|
76
|
+
"""
|
|
77
|
+
super().__init__(
|
|
78
|
+
input_dim, hidden_dim, latent_dim, conv_layer_type,
|
|
79
|
+
hidden_layers, dropout, Cheb_k, alpha
|
|
80
|
+
)
|
|
81
|
+
self.apply(self._init_weights)
|
|
82
|
+
|
|
83
|
+
def _build_output_layer(
|
|
84
|
+
self,
|
|
85
|
+
hidden_dim: int,
|
|
86
|
+
latent_dim: int,
|
|
87
|
+
Cheb_k: int,
|
|
88
|
+
alpha: float
|
|
89
|
+
) -> None:
|
|
90
|
+
"""
|
|
91
|
+
Build output layers for variational inference.
|
|
92
|
+
|
|
93
|
+
Creates separate convolution layers for mean and log-variance estimation,
|
|
94
|
+
enabling the variational autoencoder framework with proper uncertainty
|
|
95
|
+
quantification in the latent space.
|
|
96
|
+
"""
|
|
97
|
+
self.conv_mean = self._create_conv_layer(hidden_dim, latent_dim, Cheb_k, alpha)
|
|
98
|
+
self.conv_logvar = self._create_conv_layer(hidden_dim, latent_dim, Cheb_k, alpha)
|
|
99
|
+
|
|
100
|
+
def forward(
|
|
101
|
+
self,
|
|
102
|
+
x: torch.Tensor,
|
|
103
|
+
edge_index: torch.Tensor,
|
|
104
|
+
edge_weight: Optional[torch.Tensor] = None,
|
|
105
|
+
use_residual: bool = True,
|
|
106
|
+
) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
|
|
107
|
+
"""
|
|
108
|
+
Forward pass through the graph encoder.
|
|
109
|
+
|
|
110
|
+
Processes single-cell features through graph convolution layers to generate
|
|
111
|
+
latent representations. The key innovation is producing both stochastic
|
|
112
|
+
samples for training and deterministic means for stable downstream analysis.
|
|
113
|
+
|
|
114
|
+
Args:
|
|
115
|
+
x: Cell feature matrix [num_cells, input_dim]
|
|
116
|
+
edge_index: Graph connectivity [2, num_edges]
|
|
117
|
+
edge_weight: Edge weights [num_edges] (optional)
|
|
118
|
+
use_residual: Whether to apply residual connections for training stability
|
|
119
|
+
|
|
120
|
+
Returns:
|
|
121
|
+
Tuple containing:
|
|
122
|
+
- q_z: Stochastic latent samples for training [num_cells, latent_dim]
|
|
123
|
+
- q_m: Deterministic posterior means (Centroid Inference) [num_cells, latent_dim]
|
|
124
|
+
- q_s: Log-variance parameters [num_cells, latent_dim]
|
|
125
|
+
"""
|
|
126
|
+
residual = None
|
|
127
|
+
|
|
128
|
+
# Process through graph convolution layers with batch normalization and dropout
|
|
129
|
+
for i, (conv, bn, dropout) in enumerate(zip(self.convs, self.bns, self.dropouts)):
|
|
130
|
+
x = self._process_layer(x, conv, edge_index, edge_weight)
|
|
131
|
+
x = bn(x)
|
|
132
|
+
x = self.relu(x)
|
|
133
|
+
x = dropout(x)
|
|
134
|
+
|
|
135
|
+
# Capture first layer output for residual connection
|
|
136
|
+
if use_residual and i == 0:
|
|
137
|
+
residual = x
|
|
138
|
+
|
|
139
|
+
# Apply residual connection for gradient flow and stability
|
|
140
|
+
if use_residual and residual is not None:
|
|
141
|
+
x = x + residual
|
|
142
|
+
|
|
143
|
+
# Generate variational parameters
|
|
144
|
+
q_m = self._process_layer(x, self.conv_mean, edge_index, edge_weight)
|
|
145
|
+
q_s = self._process_layer(x, self.conv_logvar, edge_index, edge_weight)
|
|
146
|
+
|
|
147
|
+
# Sample from the variational distribution (reparameterization trick)
|
|
148
|
+
std = F.softplus(q_s) + 1e-6 # Ensure numerical stability
|
|
149
|
+
dist = Normal(q_m, std)
|
|
150
|
+
q_z = dist.rsample()
|
|
151
|
+
|
|
152
|
+
return q_z, q_m, q_s
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
class LinearEncoder(BaseLinearModel):
|
|
156
|
+
"""
|
|
157
|
+
Linear encoder component of CCVGAE.
|
|
158
|
+
|
|
159
|
+
Provides a fully-connected alternative to the graph encoder for scenarios
|
|
160
|
+
where cell-cell relationships are not available or when computational
|
|
161
|
+
efficiency is prioritized over graph structure modeling.
|
|
162
|
+
|
|
163
|
+
Like the graph encoder, it implements Centroid Inference by generating
|
|
164
|
+
both stochastic and deterministic representations.
|
|
165
|
+
"""
|
|
166
|
+
|
|
167
|
+
def __init__(
|
|
168
|
+
self,
|
|
169
|
+
input_dim: int,
|
|
170
|
+
hidden_dim: int,
|
|
171
|
+
latent_dim: int,
|
|
172
|
+
hidden_layers: int = 2,
|
|
173
|
+
dropout: float = 0.0,
|
|
174
|
+
) -> None:
|
|
175
|
+
"""
|
|
176
|
+
Initialize the linear encoder.
|
|
177
|
+
|
|
178
|
+
Args:
|
|
179
|
+
input_dim: Dimension of input cell features
|
|
180
|
+
hidden_dim: Dimension of hidden layers
|
|
181
|
+
latent_dim: Dimension of latent space
|
|
182
|
+
hidden_layers: Number of hidden fully-connected layers
|
|
183
|
+
dropout: Dropout probability for regularization
|
|
184
|
+
"""
|
|
185
|
+
super().__init__(input_dim, hidden_dim, hidden_dim, hidden_layers, dropout)
|
|
186
|
+
|
|
187
|
+
# Variational output layers
|
|
188
|
+
self.mu_layer = nn.Linear(hidden_dim, latent_dim)
|
|
189
|
+
self.logvar_layer = nn.Linear(hidden_dim, latent_dim)
|
|
190
|
+
|
|
191
|
+
# Initialize variational layers with proper scaling
|
|
192
|
+
nn.init.xavier_uniform_(self.mu_layer.weight)
|
|
193
|
+
nn.init.zeros_(self.mu_layer.bias)
|
|
194
|
+
nn.init.xavier_uniform_(self.logvar_layer.weight)
|
|
195
|
+
nn.init.zeros_(self.logvar_layer.bias)
|
|
196
|
+
|
|
197
|
+
def forward(self, x: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
|
|
198
|
+
"""
|
|
199
|
+
Forward pass through the linear encoder.
|
|
200
|
+
|
|
201
|
+
Args:
|
|
202
|
+
x: Cell feature matrix [num_cells, input_dim]
|
|
203
|
+
|
|
204
|
+
Returns:
|
|
205
|
+
Tuple containing:
|
|
206
|
+
- q_z: Stochastic latent samples [num_cells, latent_dim]
|
|
207
|
+
- q_m: Deterministic posterior means [num_cells, latent_dim]
|
|
208
|
+
- q_s: Log-variance parameters [num_cells, latent_dim]
|
|
209
|
+
"""
|
|
210
|
+
# Process through hidden layers
|
|
211
|
+
h = self.network(x)
|
|
212
|
+
|
|
213
|
+
# Generate variational parameters
|
|
214
|
+
q_m = self.mu_layer(h)
|
|
215
|
+
q_s = self.logvar_layer(h)
|
|
216
|
+
|
|
217
|
+
# Sample with reparameterization trick
|
|
218
|
+
std = F.softplus(q_s) + 1e-6
|
|
219
|
+
dist = Normal(q_m, std)
|
|
220
|
+
q_z = dist.rsample()
|
|
221
|
+
|
|
222
|
+
return q_z, q_m, q_s
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
class CCVGAE(nn.Module):
|
|
226
|
+
"""
|
|
227
|
+
Centroid-based Coupled Variational Graph Autoencoder (CCVGAE).
|
|
228
|
+
|
|
229
|
+
The main CCVGAE model that integrates single-cell multi-omics data through
|
|
230
|
+
three key innovations:
|
|
231
|
+
|
|
232
|
+
1. **Centroid Inference**: Uses deterministic posterior means for stable embeddings
|
|
233
|
+
2. **Coupling Mechanism**: Regularizes latent space through intermediate encoding
|
|
234
|
+
3. **Graph Structure Learning**: Jointly models features and cell relationships
|
|
235
|
+
|
|
236
|
+
This architecture addresses the instability issues of standard VAEs while
|
|
237
|
+
maintaining the flexibility to handle both graph-structured and linear data
|
|
238
|
+
processing pipelines.
|
|
239
|
+
"""
|
|
240
|
+
|
|
241
|
+
def __init__(
|
|
242
|
+
self,
|
|
243
|
+
input_dim: int,
|
|
244
|
+
hidden_dim: int,
|
|
245
|
+
latent_dim: int,
|
|
246
|
+
i_dim: int,
|
|
247
|
+
encoder_type: str = 'graph',
|
|
248
|
+
graph_type: str = 'GAT',
|
|
249
|
+
structure_decoder_type: str = 'mlp',
|
|
250
|
+
feature_decoder_type: str = 'linear',
|
|
251
|
+
hidden_layers: int = 2,
|
|
252
|
+
decoder_hidden_dim: int = 128,
|
|
253
|
+
dropout: float = 0.05,
|
|
254
|
+
use_residual: bool = True,
|
|
255
|
+
Cheb_k: int = 1,
|
|
256
|
+
alpha: float = 0.5,
|
|
257
|
+
threshold: float = 0,
|
|
258
|
+
sparse_threshold: Optional[int] = None,
|
|
259
|
+
) -> None:
|
|
260
|
+
"""
|
|
261
|
+
Initialize the CCVGAE model.
|
|
262
|
+
|
|
263
|
+
Args:
|
|
264
|
+
input_dim: Dimension of input features (e.g., number of genes)
|
|
265
|
+
hidden_dim: Dimension of encoder hidden layers
|
|
266
|
+
latent_dim: Dimension of the main latent space
|
|
267
|
+
i_dim: Dimension of intermediate coupling space
|
|
268
|
+
encoder_type: Type of encoder ('linear' or 'graph')
|
|
269
|
+
graph_type: Graph convolution type ('GAT', 'GCN', etc.)
|
|
270
|
+
structure_decoder_type: Type of structure decoder ('mlp', etc.)
|
|
271
|
+
feature_decoder_type: Type of feature decoder ('linear' or 'graph')
|
|
272
|
+
hidden_layers: Number of hidden layers in encoder
|
|
273
|
+
decoder_hidden_dim: Hidden dimension for decoders
|
|
274
|
+
dropout: Dropout probability for regularization
|
|
275
|
+
use_residual: Whether to use residual connections
|
|
276
|
+
Cheb_k: Chebyshev polynomial order (for ChebConv)
|
|
277
|
+
alpha: Alpha parameter (for SSGConv)
|
|
278
|
+
threshold: Threshold for structure decoder adjacency
|
|
279
|
+
sparse_threshold: Sparsity threshold for structure decoder
|
|
280
|
+
|
|
281
|
+
Raises:
|
|
282
|
+
ValueError: If encoder_type or feature_decoder_type is not supported
|
|
283
|
+
NotImplementedError: If graph-based feature decoder is requested
|
|
284
|
+
"""
|
|
285
|
+
super().__init__()
|
|
286
|
+
|
|
287
|
+
# Validate encoder type
|
|
288
|
+
if encoder_type not in ['linear', 'graph']:
|
|
289
|
+
raise ValueError("encoder_type must be 'linear' or 'graph'")
|
|
290
|
+
|
|
291
|
+
# Initialize encoder based on type
|
|
292
|
+
if encoder_type == 'linear':
|
|
293
|
+
self.encoder = LinearEncoder(
|
|
294
|
+
input_dim, hidden_dim, latent_dim, hidden_layers, dropout
|
|
295
|
+
)
|
|
296
|
+
else:
|
|
297
|
+
self.encoder = GraphEncoder(
|
|
298
|
+
input_dim, hidden_dim, latent_dim, graph_type,
|
|
299
|
+
hidden_layers, dropout, Cheb_k, alpha
|
|
300
|
+
)
|
|
301
|
+
|
|
302
|
+
# Structure decoder for learning cell-cell relationships
|
|
303
|
+
self.structure_decoder = GraphStructureDecoder(
|
|
304
|
+
structure_decoder=structure_decoder_type,
|
|
305
|
+
latent_dim=latent_dim,
|
|
306
|
+
hidden_dim=decoder_hidden_dim,
|
|
307
|
+
threshold=threshold,
|
|
308
|
+
sparse_threshold=sparse_threshold,
|
|
309
|
+
symmetric=True,
|
|
310
|
+
add_self_loops=False,
|
|
311
|
+
)
|
|
312
|
+
|
|
313
|
+
# Validate and initialize feature decoder
|
|
314
|
+
if feature_decoder_type not in ['linear', 'graph']:
|
|
315
|
+
raise ValueError("feature_decoder_type must be 'linear' or 'graph'")
|
|
316
|
+
|
|
317
|
+
if feature_decoder_type == 'linear':
|
|
318
|
+
self.feature_decoder = LinearDecoder(
|
|
319
|
+
input_dim, hidden_dim, latent_dim, hidden_layers, dropout
|
|
320
|
+
)
|
|
321
|
+
else:
|
|
322
|
+
# Graph-based feature decoder not implemented yet
|
|
323
|
+
raise NotImplementedError(
|
|
324
|
+
"Graph-based feature decoder is not currently supported."
|
|
325
|
+
)
|
|
326
|
+
|
|
327
|
+
# Coupling mechanism: latent space regularization
|
|
328
|
+
self.latent_encoder = nn.Linear(latent_dim, i_dim)
|
|
329
|
+
self.latent_decoder = nn.Linear(i_dim, latent_dim)
|
|
330
|
+
|
|
331
|
+
# Store configuration
|
|
332
|
+
self.encoder_type = encoder_type
|
|
333
|
+
self.feature_decoder_type = feature_decoder_type
|
|
334
|
+
self.use_residual = use_residual
|
|
335
|
+
|
|
336
|
+
def forward(
|
|
337
|
+
self,
|
|
338
|
+
x: torch.Tensor,
|
|
339
|
+
edge_index: Optional[torch.Tensor] = None,
|
|
340
|
+
edge_weight: Optional[torch.Tensor] = None,
|
|
341
|
+
) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor,
|
|
342
|
+
torch.Tensor, torch.Tensor, torch.Tensor]:
|
|
343
|
+
"""
|
|
344
|
+
Forward pass through the complete CCVGAE model.
|
|
345
|
+
|
|
346
|
+
Implements the full CCVGAE pipeline including encoding, coupling mechanism,
|
|
347
|
+
and dual reconstruction (structure and features). The Centroid Inference
|
|
348
|
+
approach uses both stochastic samples for training and deterministic means
|
|
349
|
+
for stable downstream analysis.
|
|
350
|
+
|
|
351
|
+
Args:
|
|
352
|
+
x: Input cell feature matrix [num_cells, input_dim]
|
|
353
|
+
edge_index: Graph edge indices [2, num_edges] (required for graph encoder)
|
|
354
|
+
edge_weight: Edge weights [num_edges] (optional)
|
|
355
|
+
|
|
356
|
+
Returns:
|
|
357
|
+
Tuple containing:
|
|
358
|
+
- q_z: Stochastic latent samples [num_cells, latent_dim]
|
|
359
|
+
- q_m: Deterministic posterior means [num_cells, latent_dim]
|
|
360
|
+
- q_s: Log-variance parameters [num_cells, latent_dim]
|
|
361
|
+
- pred_a: Predicted adjacency matrix [num_cells, num_cells]
|
|
362
|
+
- pred_x: Reconstructed features from main latent [num_cells, input_dim]
|
|
363
|
+
- le: Intermediate coupling representation [num_cells, i_dim]
|
|
364
|
+
- pred_xl: Reconstructed features from coupled latent [num_cells, input_dim]
|
|
365
|
+
|
|
366
|
+
Raises:
|
|
367
|
+
ValueError: If graph encoder is used without edge_index
|
|
368
|
+
"""
|
|
369
|
+
# Encode input to latent space
|
|
370
|
+
if self.encoder_type == 'linear':
|
|
371
|
+
q_z, q_m, q_s = self.encoder(x)
|
|
372
|
+
else:
|
|
373
|
+
if edge_index is None:
|
|
374
|
+
raise ValueError("edge_index is required for graph encoder")
|
|
375
|
+
q_z, q_m, q_s = self.encoder(x, edge_index, edge_weight, self.use_residual)
|
|
376
|
+
|
|
377
|
+
# Coupling mechanism: intermediate representation
|
|
378
|
+
le = self.latent_encoder(q_z) # Encode to intermediate space
|
|
379
|
+
ld = self.latent_decoder(le) # Decode back to latent space
|
|
380
|
+
|
|
381
|
+
# Structure reconstruction: learn cell-cell relationships
|
|
382
|
+
pred_a, pred_edge_index, pred_edge_weight = self.structure_decoder(
|
|
383
|
+
q_z, edge_index
|
|
384
|
+
)
|
|
385
|
+
|
|
386
|
+
# Feature reconstruction from main and coupled latent representations
|
|
387
|
+
pred_x = self.feature_decoder(q_z) # Main reconstruction
|
|
388
|
+
pred_xl = self.feature_decoder(ld) # Coupled reconstruction
|
|
389
|
+
|
|
390
|
+
return q_z, q_m, q_s, pred_a, pred_x, le, pred_xl
|