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 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