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.
GNODEVAE/utils.py ADDED
@@ -0,0 +1,460 @@
1
+ """
2
+ Utility Functions for GNODEVAE
3
+
4
+ This module provides utility classes for graph structure manipulation and
5
+ decoding in GNODEVAE models. These utilities handle the conversion between
6
+ different graph representations and enable flexible graph reconstruction.
7
+
8
+ Key Components:
9
+ - AdjToEdge: Convert adjacency matrices to edge index format
10
+ - GraphStructureDecoder: Decode latent representations to graph structure
11
+ """
12
+
13
+ import torch
14
+ import torch.nn as nn
15
+ from typing import Tuple, Union, Optional
16
+ from torch_sparse import SparseTensor
17
+ import numpy as np
18
+
19
+ class AdjToEdge:
20
+ """
21
+ Convert adjacency matrix to edge index and weight format.
22
+
23
+ This utility class handles the conversion of dense adjacency matrices
24
+ to the edge index format used by PyTorch Geometric. It supports various
25
+ operations including sparsification, symmetrization, and self-loop addition.
26
+
27
+ The class is particularly useful for processing predicted adjacency matrices
28
+ from graph decoders, allowing control over graph sparsity and structure.
29
+
30
+ Parameters
31
+ ----------
32
+ threshold : float, default=0
33
+ Probability threshold for edge existence. Edges with weights below
34
+ this threshold are removed.
35
+ sparse_threshold : int, optional
36
+ Maximum number of edges to keep per node. If specified, only the
37
+ top-k edges for each node are retained, where k=sparse_threshold.
38
+ symmetric : bool, default=True
39
+ Whether to ensure symmetric edges. If True, edge weights are averaged
40
+ for bidirectional connections: w(i,j) = w(j,i) = (w(i,j) + w(j,i))/2.
41
+ add_self_loops : bool, default=False
42
+ Whether to add self-loops to the graph. Each node will have an edge
43
+ to itself with weight 1.0.
44
+
45
+ Attributes
46
+ ----------
47
+ threshold : float
48
+ Edge probability threshold.
49
+ sparse_threshold : int or None
50
+ Sparsification parameter.
51
+ symmetric : bool
52
+ Whether to enforce symmetry.
53
+ add_self_loops : bool
54
+ Whether to add self-loops.
55
+
56
+ Examples
57
+ --------
58
+ >>> converter = AdjToEdge(threshold=0.5, symmetric=True)
59
+ >>> adj = np.random.rand(100, 100) # Predicted adjacency matrix
60
+ >>> edge_index, edge_weight = converter.convert(adj)
61
+ >>> print(f"Created {edge_index.shape[1]} edges")
62
+
63
+ Notes
64
+ -----
65
+ The order of operations is:
66
+ 1. Sparsification (if sparse_threshold is set)
67
+ 2. Thresholding
68
+ 3. Symmetrization (if symmetric=True)
69
+ 4. Self-loop addition (if add_self_loops=True)
70
+ """
71
+
72
+ def __init__(
73
+ self,
74
+ threshold: float = 0,
75
+ sparse_threshold: Optional[int] = None,
76
+ symmetric: bool = True,
77
+ add_self_loops: bool = False
78
+ ):
79
+ self.threshold = threshold
80
+ self.sparse_threshold = sparse_threshold
81
+ self.symmetric = symmetric
82
+ self.add_self_loops = add_self_loops
83
+
84
+ def _sparsify(
85
+ self,
86
+ adj: np.ndarray,
87
+ k: int
88
+ ) -> np.ndarray:
89
+ """
90
+ Keep only top-k edges per node.
91
+
92
+ For each node, retains only the k edges with highest weights.
93
+ This helps control graph sparsity and computational complexity.
94
+
95
+ Parameters
96
+ ----------
97
+ adj : np.ndarray
98
+ Adjacency matrix, shape (num_nodes, num_nodes).
99
+ k : int
100
+ Number of top edges to keep per node.
101
+
102
+ Returns
103
+ -------
104
+ sparse_adj : np.ndarray
105
+ Sparsified adjacency matrix.
106
+ """
107
+ sparse_adj = np.zeros_like(adj)
108
+ for i in range(adj.shape[0]):
109
+ # Find indices of top-k edge weights for node i
110
+ top_k_idx = np.argpartition(adj[i], -k)[-k:]
111
+ # Apply threshold filter to top-k edges
112
+ mask = adj[i, top_k_idx] > self.threshold
113
+ sparse_adj[i, top_k_idx] = adj[i, top_k_idx] * mask
114
+ return sparse_adj
115
+
116
+ def _symmetrize(
117
+ self,
118
+ edge_index: np.ndarray,
119
+ edge_weight: np.ndarray
120
+ ) -> Tuple[np.ndarray, np.ndarray]:
121
+ """
122
+ Make edges symmetric by averaging bidirectional edge weights.
123
+
124
+ Ensures that the graph is undirected by setting:
125
+ w(i,j) = w(j,i) = (w(i,j) + w(j,i)) / 2
126
+
127
+ Parameters
128
+ ----------
129
+ edge_index : np.ndarray
130
+ Edge indices, shape (2, num_edges).
131
+ edge_weight : np.ndarray
132
+ Edge weights, shape (num_edges,).
133
+
134
+ Returns
135
+ -------
136
+ edge_index : np.ndarray
137
+ Symmetrized edge indices.
138
+ edge_weight : np.ndarray
139
+ Symmetrized edge weights.
140
+ """
141
+ if edge_index.size == 0 or edge_weight.size == 0:
142
+ return np.zeros((2, 0), dtype=np.int64), np.array([], dtype=edge_weight.dtype)
143
+
144
+ # Determine number of nodes
145
+ n = max(edge_index[0].max(), edge_index[1].max()) + 1
146
+ adj = np.zeros((n, n))
147
+ adj[edge_index[0], edge_index[1]] = edge_weight
148
+
149
+ # Symmetrize by averaging
150
+ adj = (adj + adj.T) / 2
151
+
152
+ # Convert back to edge format
153
+ rows, cols = np.nonzero(adj)
154
+ edge_index = np.stack([rows, cols])
155
+ edge_weight = adj[rows, cols]
156
+
157
+ return edge_index, edge_weight
158
+
159
+ def _add_self_loops(
160
+ self,
161
+ edge_index: np.ndarray,
162
+ edge_weight: np.ndarray,
163
+ num_nodes: int
164
+ ) -> Tuple[np.ndarray, np.ndarray]:
165
+ """
166
+ Add self-loops to the graph.
167
+
168
+ Creates edges from each node to itself with weight 1.0.
169
+ This can help with graph neural network training by ensuring
170
+ each node includes its own features in aggregation.
171
+
172
+ Parameters
173
+ ----------
174
+ edge_index : np.ndarray
175
+ Edge indices, shape (2, num_edges).
176
+ edge_weight : np.ndarray
177
+ Edge weights, shape (num_edges,).
178
+ num_nodes : int
179
+ Total number of nodes.
180
+
181
+ Returns
182
+ -------
183
+ edge_index : np.ndarray
184
+ Edge indices with self-loops added.
185
+ edge_weight : np.ndarray
186
+ Edge weights with self-loop weights (1.0) added.
187
+ """
188
+ self_loops = np.arange(num_nodes)
189
+ self_loops = np.stack([self_loops, self_loops])
190
+
191
+ edge_index = np.concatenate([edge_index, self_loops], axis=1)
192
+ edge_weight = np.concatenate([edge_weight, np.ones(num_nodes)])
193
+
194
+ return edge_index, edge_weight
195
+
196
+ def convert(
197
+ self,
198
+ adj: np.ndarray
199
+ ) -> Tuple[np.ndarray, np.ndarray]:
200
+ """
201
+ Convert adjacency matrix to edge index and weights.
202
+
203
+ Main conversion function that applies all configured operations:
204
+ sparsification, thresholding, symmetrization, and self-loop addition.
205
+
206
+ Parameters
207
+ ----------
208
+ adj : np.ndarray
209
+ Adjacency matrix with edge probabilities, shape (num_nodes, num_nodes).
210
+ Values should be in [0, 1] for probabilistic edges.
211
+
212
+ Returns
213
+ -------
214
+ edge_index : np.ndarray
215
+ Edge indices in COO format, shape (2, num_edges).
216
+ edge_index[0] contains source nodes, edge_index[1] contains target nodes.
217
+ edge_weight : np.ndarray
218
+ Edge weights, shape (num_edges,).
219
+
220
+ Examples
221
+ --------
222
+ >>> adj = np.array([[0, 0.8, 0.3], [0.8, 0, 0.9], [0.3, 0.9, 0]])
223
+ >>> converter = AdjToEdge(threshold=0.5)
224
+ >>> edge_index, edge_weight = converter.convert(adj)
225
+ """
226
+ # Step 1: Sparsify if requested
227
+ if self.sparse_threshold is not None:
228
+ adj = self._sparsify(adj, self.sparse_threshold)
229
+
230
+ # Step 2: Apply threshold and convert to edge format
231
+ mask = adj > self.threshold
232
+ rows, cols = np.nonzero(mask)
233
+ edge_index = np.stack([rows, cols])
234
+ edge_weight = adj[rows, cols]
235
+
236
+ # Step 3: Symmetrize if requested
237
+ if self.symmetric:
238
+ edge_index, edge_weight = self._symmetrize(edge_index, edge_weight)
239
+
240
+ # Step 4: Add self-loops if requested
241
+ if self.add_self_loops:
242
+ edge_index, edge_weight = self._add_self_loops(
243
+ edge_index, edge_weight, adj.shape[0]
244
+ )
245
+
246
+ return edge_index, edge_weight
247
+
248
+
249
+ class GraphStructureDecoder(nn.Module):
250
+ """
251
+ Graph structure decoder with flexible conversion to edge format.
252
+
253
+ This decoder combines a structure decoding network with edge conversion
254
+ utilities to produce graph representations in various formats. It wraps
255
+ one of the basic decoder types (MLP, Bilinear, InnerProduct) and provides
256
+ additional functionality for edge format conversion.
257
+
258
+ Parameters
259
+ ----------
260
+ structure_decoder : str
261
+ Type of structure decoder ('bilinear', 'inner_product', or 'mlp')
262
+ latent_dim : int
263
+ Latent space dimension
264
+ hidden_dim : int, optional
265
+ Hidden dimension for MLP decoder, by default None
266
+ threshold : float, optional
267
+ Edge probability threshold, by default 0.5
268
+ sparse_threshold : int, optional
269
+ Maximum edges per node, by default None
270
+ symmetric : bool, optional
271
+ Whether to ensure symmetric edges, by default True
272
+ add_self_loops : bool, optional
273
+ Whether to add self-loops, by default False
274
+ """
275
+ def __init__(
276
+ self,
277
+ structure_decoder: str,
278
+ latent_dim: int,
279
+ hidden_dim: Optional[int] = None,
280
+ threshold: float = 0.5,
281
+ sparse_threshold: Optional[int] = None,
282
+ symmetric: bool = True,
283
+ add_self_loops: bool = False
284
+ ):
285
+ super().__init__()
286
+ # Initialize structure decoder
287
+ if structure_decoder == 'bilinear':
288
+ self.decoder = BilinearDecoder(latent_dim)
289
+ elif structure_decoder == 'inner_product':
290
+ self.decoder = InnerProductDecoder()
291
+ elif structure_decoder == 'mlp':
292
+ if hidden_dim is None:
293
+ raise ValueError("hidden_dim must be specified for MLP decoder")
294
+ self.decoder = MLPDecoder(latent_dim, hidden_dim)
295
+ else:
296
+ raise ValueError(
297
+ f"Unknown decoder type: {structure_decoder}. "
298
+ "Choose from: bilinear, inner_product, mlp"
299
+ )
300
+
301
+ # Initialize edge converter
302
+ self.edge_converter = AdjToEdge(
303
+ threshold=threshold,
304
+ sparse_threshold=sparse_threshold,
305
+ symmetric=symmetric,
306
+ add_self_loops=add_self_loops
307
+ )
308
+
309
+ self.structure_decoder = structure_decoder
310
+
311
+ def forward(
312
+ self,
313
+ z: torch.Tensor,
314
+ edge_index: Optional[torch.Tensor] = None
315
+ ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
316
+ """
317
+ Convert latent embeddings to edge index and weights.
318
+
319
+ Parameters
320
+ ----------
321
+ z : torch.Tensor
322
+ Latent node embeddings (num_nodes, latent_dim)
323
+ edge_index : torch.Tensor, optional
324
+ Edge indices for MLP decoder (2, num_edges)
325
+
326
+ Returns
327
+ -------
328
+ adj : torch.Tensor
329
+ Adjacency matrix (num_nodes, num_nodes)
330
+ edge_index : torch.Tensor
331
+ Edge indices (2, num_edges)
332
+ edge_weight : torch.Tensor
333
+ Edge weights (num_edges,)
334
+ """
335
+ # Get adjacency matrix from structure decoder
336
+ if self.structure_decoder == 'mlp':
337
+ if edge_index is None:
338
+ raise ValueError("edge_index required for MLP decoder")
339
+ adj = self.decoder(z, edge_index)
340
+ else:
341
+ adj = self.decoder(z)
342
+
343
+ # Convert torch tensor to numpy array
344
+ adj_np = adj.detach().cpu().numpy()
345
+
346
+ # Convert to edge index and weights using numpy-based edge converter
347
+ edge_index_np, edge_weight_np = self.edge_converter.convert(adj_np)
348
+
349
+ # Convert back to torch tensors
350
+ device = z.device
351
+ edge_index = torch.from_numpy(edge_index_np).to(device)
352
+ edge_weight = torch.from_numpy(edge_weight_np).to(device)
353
+
354
+ return adj, edge_index, edge_weight
355
+
356
+
357
+ class BilinearDecoder(nn.Module):
358
+ """
359
+ Bilinear Decoder for graph reconstruction.
360
+
361
+ Parameters
362
+ ----------
363
+ latent_dim : int
364
+ Latent space dimension.
365
+ """
366
+
367
+ def __init__(self, latent_dim: int):
368
+ super(BilinearDecoder, self).__init__()
369
+ self.weight = nn.Parameter(torch.Tensor(latent_dim, latent_dim))
370
+ nn.init.xavier_uniform_(self.weight)
371
+
372
+ def forward(self, z: torch.Tensor) -> torch.Tensor:
373
+ """
374
+ Reconstruct adjacency matrix using bilinear transformation.
375
+
376
+ Parameters
377
+ ----------
378
+ z : torch.Tensor
379
+ Latent node embeddings, shape (num_nodes, latent_dim).
380
+
381
+ Returns
382
+ -------
383
+ adj_recon : torch.Tensor
384
+ Reconstructed adjacency matrix, shape (num_nodes, num_nodes).
385
+ """
386
+ adj_recon = torch.sigmoid(torch.matmul(z @ self.weight, z.t()))
387
+ return adj_recon
388
+
389
+
390
+ class InnerProductDecoder(nn.Module):
391
+ """
392
+ Inner Product Decoder for graph reconstruction.
393
+ """
394
+
395
+ def __init__(self):
396
+ super(InnerProductDecoder, self).__init__()
397
+
398
+ def forward(self, z: torch.Tensor) -> torch.Tensor:
399
+ """
400
+ Reconstruct adjacency matrix using inner product.
401
+
402
+ Parameters
403
+ ----------
404
+ z : torch.Tensor
405
+ Latent node embeddings, shape (num_nodes, latent_dim).
406
+
407
+ Returns
408
+ -------
409
+ adj_recon : torch.Tensor
410
+ Reconstructed adjacency matrix, shape (num_nodes, num_nodes).
411
+ """
412
+ adj_recon = torch.sigmoid(torch.matmul(z, z.t()))
413
+ return adj_recon
414
+
415
+
416
+ class MLPDecoder(nn.Module):
417
+ """
418
+ MLP Decoder for graph reconstruction.
419
+
420
+ Parameters
421
+ ----------
422
+ latent_dim : int
423
+ Latent space dimension.
424
+ hidden_dim : int
425
+ Hidden layer dimension.
426
+ """
427
+
428
+ def __init__(self, latent_dim: int, hidden_dim: int):
429
+ super(MLPDecoder, self).__init__()
430
+ self.mlp = nn.Sequential(
431
+ nn.Linear(latent_dim * 2, hidden_dim),
432
+ nn.ReLU(),
433
+ nn.Linear(hidden_dim, 1),
434
+ nn.Sigmoid(),
435
+ )
436
+
437
+ def forward(self, z: torch.Tensor, edge_index: torch.Tensor) -> torch.Tensor:
438
+ """
439
+ Reconstruct adjacency matrix using an MLP.
440
+
441
+ Parameters
442
+ ----------
443
+ z : torch.Tensor
444
+ Latent node embeddings, shape (num_nodes, latent_dim).
445
+ edge_index : torch.Tensor
446
+ Edge indices, shape (2, num_edges).
447
+
448
+ Returns
449
+ -------
450
+ adj_recon : torch.Tensor
451
+ Reconstructed adjacency matrix, shape (num_nodes, num_nodes).
452
+ """
453
+ num_nodes = z.size(0)
454
+ row, col = edge_index
455
+ edge_features = torch.cat([z[row], z[col]], dim=1)
456
+ edge_probs = self.mlp(edge_features).squeeze()
457
+ adj_recon = torch.zeros((num_nodes, num_nodes), device=z.device)
458
+ adj_recon[row, col] = edge_probs
459
+ return adj_recon
460
+
GNODEVAE/utils_ODE.py ADDED
@@ -0,0 +1,140 @@
1
+ """
2
+ Neural ODE Utilities for GNODEVAE
3
+
4
+ This module provides utility functions and classes for integrating Neural Ordinary
5
+ Differential Equations (ODEs) into the GNODEVAE framework. Neural ODEs enable
6
+ modeling of continuous-time dynamics in the latent space, which is particularly
7
+ useful for trajectory inference in single-cell data.
8
+
9
+ Key components:
10
+ - get_step_size: Compute step size for ODE solvers
11
+ - LatentODEfunc: Neural network that defines the ODE dynamics
12
+ """
13
+
14
+ import torch
15
+ import torch.nn as nn
16
+ from typing import Optional
17
+
18
+
19
+ def get_step_size(step_size: Optional[float], t1: float, t2: float, t_size: int) -> dict:
20
+ """
21
+ Compute the step size options for ODE solvers.
22
+
23
+ This function calculates the appropriate step size for numerical ODE solvers
24
+ based on the time range and number of time steps. The step size controls
25
+ the granularity of the numerical integration.
26
+
27
+ Parameters
28
+ ----------
29
+ step_size : Optional[float]
30
+ The desired step size multiplier. If None, no step size constraints are set,
31
+ and the solver uses adaptive stepping.
32
+ t1 : float
33
+ The start time of the ODE integration.
34
+ t2 : float
35
+ The end time of the ODE integration.
36
+ t_size : int
37
+ The number of time steps for integration.
38
+
39
+ Returns
40
+ -------
41
+ dict
42
+ A dictionary containing the step size options for the ODE solver.
43
+ Empty dict if step_size is None, otherwise contains {"step_size": computed_value}.
44
+
45
+ Examples
46
+ --------
47
+ >>> get_step_size(0.1, 0.0, 1.0, 10)
48
+ {'step_size': 0.01}
49
+ >>> get_step_size(None, 0.0, 1.0, 10)
50
+ {}
51
+ """
52
+ if step_size is None:
53
+ return {}
54
+
55
+ # Compute step size based on time range and number of steps
56
+ # The step_size parameter acts as a divisor to scale the base interval
57
+ computed_step_size = (t2 - t1) / t_size / step_size
58
+ return {"step_size": computed_step_size}
59
+
60
+
61
+ class LatentODEfunc(nn.Module):
62
+ """
63
+ Neural network that defines the dynamics of the latent ODE system.
64
+
65
+ This class implements a neural network that models how the latent state
66
+ changes over time. It takes a latent state and returns its derivative,
67
+ which is used by ODE solvers to integrate trajectories. The network uses
68
+ a simple two-layer architecture with ELU activation.
69
+
70
+ In the context of single-cell analysis, this models how cells move through
71
+ the latent space over developmental time or other continuous processes.
72
+
73
+ Parameters
74
+ ----------
75
+ n_latent : int, default=5
76
+ The dimensionality of the latent space (number of latent features).
77
+ n_hidden : int, default=25
78
+ The dimensionality of the hidden layer. Larger values provide more
79
+ capacity but may lead to overfitting.
80
+
81
+ Attributes
82
+ ----------
83
+ fc1 : nn.Linear
84
+ First fully connected layer (latent_dim -> hidden_dim)
85
+ elu : nn.ELU
86
+ ELU activation function for smooth gradients
87
+ fc2 : nn.Linear
88
+ Second fully connected layer (hidden_dim -> latent_dim)
89
+
90
+ Notes
91
+ -----
92
+ The ELU activation is chosen for its smoothness, which helps with
93
+ stable ODE integration. The output dimension matches the input dimension
94
+ since we're computing derivatives in the latent space.
95
+
96
+ Examples
97
+ --------
98
+ >>> ode_func = LatentODEfunc(n_latent=10, n_hidden=50)
99
+ >>> t = torch.tensor(0.5)
100
+ >>> z = torch.randn(10)
101
+ >>> dz_dt = ode_func(t, z) # Compute derivative
102
+ """
103
+
104
+ def __init__(self, n_latent: int = 5, n_hidden: int = 25):
105
+ super().__init__()
106
+ self.fc1 = nn.Linear(n_latent, n_hidden)
107
+ self.elu = nn.ELU()
108
+ self.fc2 = nn.Linear(n_hidden, n_latent)
109
+
110
+ def forward(self, t: torch.Tensor, x: torch.Tensor) -> torch.Tensor:
111
+ """
112
+ Compute the derivative of the latent state at a given time.
113
+
114
+ This function defines the ODE: dz/dt = f(z, t), where z is the latent state.
115
+ Note that while time `t` is passed for compatibility with ODE solvers,
116
+ this implementation uses a time-invariant (autonomous) ODE where the
117
+ dynamics don't explicitly depend on t.
118
+
119
+ Parameters
120
+ ----------
121
+ t : torch.Tensor
122
+ Current time point. Included for compatibility with ODE solvers
123
+ but not used in this time-invariant implementation.
124
+ x : torch.Tensor
125
+ Current latent state, shape (batch_size, n_latent) or (n_latent,).
126
+
127
+ Returns
128
+ -------
129
+ torch.Tensor
130
+ Derivative of the latent state (dz/dt), same shape as input x.
131
+
132
+ Notes
133
+ -----
134
+ The ODE solver will use these derivatives to integrate the trajectory:
135
+ z(t) = z(t0) + ∫[t0 to t] f(z(τ), τ) dτ
136
+ """
137
+ out = self.fc1(x)
138
+ out = self.elu(out)
139
+ out = self.fc2(out)
140
+ return out