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/CLEAR.py +172 -0
- GNODEVAE/GODEVAE.py +413 -0
- GNODEVAE/GODEVAE_agent.py +385 -0
- GNODEVAE/GODEVAE_env.py +758 -0
- GNODEVAE/GODEVAE_trainer.py +309 -0
- GNODEVAE/SC3.py +198 -0
- GNODEVAE/__init__.py +6 -0
- GNODEVAE/agent.py +472 -0
- GNODEVAE/env.py +474 -0
- GNODEVAE/mixin.py +418 -0
- GNODEVAE/module.py +939 -0
- GNODEVAE/module_refined.py +561 -0
- GNODEVAE/partition_time.py +185 -0
- GNODEVAE/scGCC.py +184 -0
- GNODEVAE/scGNN.py +146 -0
- GNODEVAE/trainer.py +397 -0
- GNODEVAE/utils.py +460 -0
- GNODEVAE/utils_ODE.py +140 -0
- gnodevae-0.0.3.dist-info/METADATA +330 -0
- gnodevae-0.0.3.dist-info/RECORD +23 -0
- gnodevae-0.0.3.dist-info/WHEEL +5 -0
- gnodevae-0.0.3.dist-info/licenses/LICENSE +21 -0
- gnodevae-0.0.3.dist-info/top_level.txt +1 -0
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
|