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/agent.py ADDED
@@ -0,0 +1,472 @@
1
+ """
2
+ Training Agents for GNODEVAE
3
+
4
+ This module implements agent classes that manage the training process for
5
+ GNODEVAE models. Agents combine environment setup, model training, and
6
+ evaluation metrics to provide a high-level interface for users.
7
+
8
+ Key Classes:
9
+ - BaseAgent: Base class with common training functionality
10
+ - agent: Standard GraphVAE agent
11
+ - agent_r: GNODEVAE agent with ODE component
12
+ """
13
+
14
+ from .env import Env, Env_r
15
+ from anndata import AnnData
16
+ import numpy as np
17
+ import torch
18
+ import tqdm
19
+ from typing import Optional, Self
20
+ import time
21
+ import psutil
22
+
23
+ class BaseAgent:
24
+ """
25
+ Base class for training agents.
26
+
27
+ This class provides common functionality for training, including:
28
+ - Progress tracking with tqdm
29
+ - Resource monitoring (CPU/GPU memory)
30
+ - Score computation and storage
31
+ - Latent representation extraction
32
+
33
+ The BaseAgent uses multiple inheritance to combine environment setup
34
+ (Env/Env_r) with training logic.
35
+ """
36
+
37
+ def __init__(self, *args, **kwargs):
38
+ """
39
+ Initialize the base agent.
40
+
41
+ This __init__ will be called by agent and agent_r, which will then
42
+ call their respective Env/Env_r initialization methods.
43
+ """
44
+ super().__init__(*args, **kwargs)
45
+
46
+ def fit(
47
+ self,
48
+ epochs: int = 300,
49
+ update_steps: int = 10,
50
+ silent: bool = False,
51
+ ) -> Self:
52
+ """
53
+ Train the model for a specified number of epochs.
54
+
55
+ This method iterates through epochs, performs training steps,
56
+ monitors resources, and tracks evaluation metrics. Progress is
57
+ displayed using tqdm with periodic updates of loss and scores.
58
+
59
+ Parameters
60
+ ----------
61
+ epochs : int, default=300
62
+ Number of training epochs to run.
63
+ update_steps : int, default=10
64
+ Frequency of progress bar updates (every N epochs).
65
+ silent : bool, default=False
66
+ If True, suppress progress bar output.
67
+
68
+ Returns
69
+ -------
70
+ Self
71
+ Returns self for method chaining.
72
+
73
+ Attributes Set
74
+ --------------
75
+ resource : list
76
+ List of tuples containing (step_time, cpu_memory, gpu_memory)
77
+ for each epoch.
78
+ time_all : float
79
+ Total training time in seconds.
80
+
81
+ Notes
82
+ -----
83
+ The method computes and displays the following metrics:
84
+ - Loss: Total reconstruction and KL divergence loss
85
+ - ARI: Adjusted Rand Index (clustering agreement)
86
+ - NMI: Normalized Mutual Information
87
+ - ASW: Average Silhouette Width (cluster separation)
88
+ - C_H: Calinski-Harabasz Index (cluster quality)
89
+ - D_B: Davies-Bouldin Index (lower is better)
90
+ - P_C: Pearson Correlation
91
+ - Step Time: Time per training step
92
+ """
93
+ self.resource = []
94
+ start_time = time.time()
95
+
96
+ try:
97
+ with tqdm.tqdm(total=epochs, desc='Fitting', ncols=150, disable=silent, miniters=update_steps) as pbar:
98
+ for i in range(epochs):
99
+ step_start_time = time.time()
100
+
101
+ # Perform one training step (forward + backward + optimize)
102
+ self.step()
103
+
104
+ step_end_time = time.time()
105
+ step_time = step_end_time - step_start_time
106
+
107
+ # Monitor resource usage
108
+ process = psutil.Process()
109
+ cpu_memory = process.memory_info().rss / (1024 ** 2) # MB
110
+
111
+ if torch.cuda.is_available():
112
+ gpu_memory = torch.cuda.memory_allocated(self.device) / (1024 ** 2) # MB
113
+ else:
114
+ gpu_memory = 0.0
115
+
116
+ self.resource.append((step_time, cpu_memory, gpu_memory))
117
+
118
+ # Update progress bar periodically
119
+ if (i + 1) % update_steps == 0:
120
+ # Compute average metrics over recent steps
121
+ recent_losses = self.loss[-update_steps:] if len(self.loss) >= update_steps else self.loss
122
+ recent_scores = self.score[-update_steps:] if len(self.score) >= update_steps else self.score
123
+ recent_resources = self.resource[-update_steps:] if len(self.resource) >= update_steps else self.resource
124
+
125
+ loss = np.mean([sum(loss_step) for loss_step in recent_losses])
126
+ ari, nmi, asw, ch, db, pc = np.mean(recent_scores, axis=0)
127
+ st, cm, gm = np.mean(recent_resources, axis=0)
128
+
129
+ pbar.set_postfix({
130
+ 'Loss': f'{loss:.2f}',
131
+ 'ARI': f'{ari:.2f}',
132
+ 'NMI': f'{nmi:.2f}',
133
+ 'ASW': f'{asw:.2f}',
134
+ 'C_H': f'{ch:.2f}',
135
+ 'D_B': f'{db:.2f}',
136
+ 'P_C': f'{pc:.2f}',
137
+ 'Step Time': f'{st:.2f}s',
138
+ }, refresh=False)
139
+ pbar.update(1)
140
+
141
+ except Exception as e:
142
+ print(f"{e}")
143
+ raise e
144
+
145
+ end_time = time.time()
146
+ self.time_all = end_time - start_time
147
+ return self
148
+
149
+ def _get_latent_representation(self) -> np.ndarray:
150
+ """
151
+ Extract latent representations from all data partitions.
152
+
153
+ This internal method collects latent embeddings from each graph
154
+ partition and concatenates them into a single array.
155
+
156
+ Returns
157
+ -------
158
+ np.ndarray
159
+ Concatenated latent representations, shape (num_cells, latent_dim).
160
+ """
161
+ ls_l = []
162
+ for cd in self.cdata:
163
+ latent = self.take_latent(cd)
164
+ ls_l.append(latent)
165
+ latent = np.vstack(ls_l)
166
+ return latent
167
+
168
+ def get_latent(self) -> np.ndarray:
169
+ """
170
+ Get latent representations in original cell order.
171
+
172
+ Since cells may be reordered during graph partitioning, this method
173
+ restores the original ordering using stored indices.
174
+
175
+ Returns
176
+ -------
177
+ np.ndarray
178
+ Latent representations in original cell order,
179
+ shape (num_cells, latent_dim).
180
+
181
+ Examples
182
+ --------
183
+ >>> agent = agent_r(adata=adata, ...)
184
+ >>> agent.fit(epochs=100)
185
+ >>> latent = agent.get_latent()
186
+ >>> adata.obsm['X_gnodevae'] = latent
187
+ """
188
+ latent = self._get_latent_representation()
189
+ # Restore original cell ordering
190
+ lut = dict(zip(self.idx, latent))
191
+ latent_ordered = np.vstack([lut[i] for i in range(self.n_obs)])
192
+ return latent_ordered
193
+
194
+ def score_final(self) -> None:
195
+ """
196
+ Compute final clustering scores after training.
197
+
198
+ This method evaluates the quality of the learned latent representation
199
+ by computing various clustering metrics. Results are stored in the
200
+ `final_score` attribute.
201
+
202
+ Sets
203
+ ----
204
+ final_score : tuple
205
+ Tuple of (ARI, NMI, ASW, CH, DB, PC) scores.
206
+ """
207
+ latent = self._get_latent_representation()
208
+ score = self._calc_score(latent)
209
+ self.final_score = score
210
+
211
+
212
+ class agent_r(BaseAgent, Env_r):
213
+ """
214
+ GNODEVAE agent with Neural ODE component.
215
+
216
+ This agent class provides a high-level interface for training GNODEVAE
217
+ models that include the Neural ODE component for trajectory inference.
218
+ It combines environment setup (data preprocessing, graph construction)
219
+ with the ODE-augmented VAE model.
220
+
221
+ Parameters
222
+ ----------
223
+ adata : AnnData
224
+ Annotated data matrix containing single-cell gene expression.
225
+ layer : str, default='counts'
226
+ Layer of AnnData to use for input features.
227
+ n_var : Optional[int], default=None
228
+ Number of highly variable genes to select. If None, uses all genes.
229
+ tech : str, default='PCA'
230
+ Dimensionality reduction technique ('PCA', 'NMF', 'FastICA', etc.).
231
+ n_neighbors : int, default=15
232
+ Number of neighbors for k-NN graph construction.
233
+ batch_tech : Optional[str], default=None
234
+ Batch correction method ('harmony' or 'scvi').
235
+ all_feat : bool, default=True
236
+ Whether to use all features or only highly variable genes.
237
+ hidden_dim : int, default=128
238
+ Hidden layer dimension for neural networks.
239
+ latent_dim : int, default=10
240
+ Latent space dimension for cell embeddings.
241
+ encoder_type : str, default='graph'
242
+ Type of encoder ('graph' or 'linear').
243
+ graph_type : str, default='GAT'
244
+ Graph convolution type ('GAT', 'GCN', 'SAGE', etc.).
245
+ structure_decoder_type : str, default='mlp'
246
+ Structure decoder type ('mlp', 'bilinear', 'inner_product').
247
+ feature_decoder_type : str, default='linear'
248
+ Feature decoder type ('linear' or 'graph').
249
+ hidden_layers : int, default=2
250
+ Number of hidden layers.
251
+ decoder_hidden_dim : int, default=128
252
+ Hidden dimension for structure decoder.
253
+ dropout : float, default=0.05
254
+ Dropout rate for regularization.
255
+ use_residual : bool, default=True
256
+ Whether to use residual connections.
257
+ Cheb_k : int, default=1
258
+ Order of Chebyshev polynomials.
259
+ alpha : float, default=0.5
260
+ Teleport probability for SSGConv.
261
+ threshold : float, default=0
262
+ Threshold for edge probability.
263
+ sparse_threshold : Optional[int], default=None
264
+ Maximum number of edges per node.
265
+ lr : float, default=1e-4
266
+ Learning rate for optimizer.
267
+ beta : float, default=1.0
268
+ Weight for KL divergence loss.
269
+ graph : float, default=1.0
270
+ Weight for graph reconstruction loss.
271
+ device : torch.device, optional
272
+ Computing device (auto-detected if not specified).
273
+ num_parts : int, default=10
274
+ Number of graph partitions for mini-batch training.
275
+ *args, **kwargs
276
+ Additional arguments passed to parent classes.
277
+
278
+ Examples
279
+ --------
280
+ >>> import scanpy as sc
281
+ >>> from GNODEVAE import agent_r
282
+ >>> adata = sc.read_h5ad('data.h5ad')
283
+ >>> model = agent_r(adata=adata, latent_dim=10)
284
+ >>> model.fit(epochs=300)
285
+ >>> latent = model.get_latent()
286
+ """
287
+
288
+ def __init__(
289
+ self,
290
+ adata: AnnData,
291
+ layer: str = 'counts',
292
+ n_var: Optional[int] = None,
293
+ tech: str = 'PCA',
294
+ n_neighbors: int = 15,
295
+ batch_tech: Optional[str] = None,
296
+ all_feat: bool = True,
297
+ hidden_dim: int = 128,
298
+ latent_dim: int = 10,
299
+ encoder_type: str = 'graph',
300
+ graph_type: str = 'GAT',
301
+ structure_decoder_type: str = 'mlp',
302
+ feature_decoder_type: str = 'linear',
303
+ hidden_layers: int = 2,
304
+ decoder_hidden_dim: int = 128,
305
+ dropout: float = 0.05,
306
+ use_residual: bool = True,
307
+ Cheb_k: int = 1,
308
+ alpha: float = 0.5,
309
+ threshold: float = 0,
310
+ sparse_threshold: Optional[int] = None,
311
+ lr: float = 1e-4,
312
+ beta: float = 1.0,
313
+ graph: float = 1.0,
314
+ device: torch.device = torch.device('cuda') if torch.cuda.is_available() else torch.device('cpu'),
315
+ num_parts: int = 10,
316
+ *args,
317
+ **kwargs,
318
+ ):
319
+ super().__init__(
320
+ adata=adata,
321
+ layer=layer,
322
+ n_var=n_var,
323
+ tech=tech,
324
+ n_neighbors=n_neighbors,
325
+ batch_tech=batch_tech,
326
+ all_feat=all_feat,
327
+ hidden_dim=hidden_dim,
328
+ latent_dim=latent_dim,
329
+ encoder_type=encoder_type,
330
+ graph_type=graph_type,
331
+ structure_decoder_type=structure_decoder_type,
332
+ feature_decoder_type=feature_decoder_type,
333
+ hidden_layers=hidden_layers,
334
+ decoder_hidden_dim=decoder_hidden_dim,
335
+ dropout=dropout,
336
+ use_residual=use_residual,
337
+ Cheb_k=Cheb_k,
338
+ alpha=alpha,
339
+ threshold=threshold,
340
+ sparse_threshold=sparse_threshold,
341
+ lr=lr,
342
+ beta=beta,
343
+ graph=graph,
344
+ device=device,
345
+ num_parts=num_parts,
346
+ *args,
347
+ **kwargs,
348
+ )
349
+
350
+
351
+ class agent(BaseAgent, Env):
352
+ """
353
+ Standard GraphVAE agent (without ODE component).
354
+
355
+ This agent class provides a high-level interface for training standard
356
+ GraphVAE models without the Neural ODE component. It's suitable for
357
+ static clustering tasks where temporal dynamics are not needed.
358
+
359
+ Parameters
360
+ ----------
361
+ adata : AnnData
362
+ Annotated data matrix (e.g., single-cell data).
363
+ layer : str, optional
364
+ Layer of the AnnData object to use for input features, by default 'counts'.
365
+ n_var : int
366
+ Number of highly variable genes to select.
367
+ tech : str
368
+ Decomposition method to use (PCA, NMF, FastICA, TruncatedSVD, FactorAnalysis, LatentDirichletAllocation).
369
+ n_neighbors : int
370
+ Number of neighbors for graph construction.
371
+ latent_dim : int
372
+ Latent space dimension for clustering.
373
+ batch_tech : Optional[str]
374
+ Method to correct batch effects ('harmony' or 'scvi').
375
+ all_feat : bool
376
+ Whether to use all features or only highly variable ones
377
+ hidden_dim : int, optional
378
+ Hidden layer dimension for the encoder, by default 128.
379
+ latent_dim : int, optional
380
+ Latent space dimension, by default 10.
381
+ encoder_type : str, optional
382
+ Type of graph convolutional layer ('GCN', 'Cheb', 'SAGE', 'Graph', 'TAG', 'ARMA', 'GAT', 'Transformer', 'SG', 'SSG'), by default 'GAT'.
383
+ encoder_hidden_layers : int, optional
384
+ Number of hidden layers in the graph encoder, by default 2.
385
+ decoder_type : str, optional
386
+ Type of graph decoder ('Bilinear', 'InnerProduct', 'MLP'), by default 'MLP'.
387
+ decoder_hidden_dim : int, optional
388
+ Hidden dimension for the MLPDecoder (if used), by default 128.
389
+ feature_decoder_hidden_layers : int, optional
390
+ Number of hidden layers in the feature decoder, by default 2.
391
+ dropout : float, optional
392
+ Dropout rate, by default 5e-3.
393
+ use_residual : bool, optional
394
+ Whether to use residual connections, by default True.
395
+ Cheb_k : int, optional
396
+ The order of Chebyshev polynomials for ChebConv, by default None.
397
+ alpha : float, optional
398
+ Teleport probability, by default 0.5.
399
+ lr : float, optional
400
+ Learning rate for the optimizer, by default 1e-4.
401
+ beta : float, optional
402
+ Weight for the KL divergence term in the loss function, by default 1.0.
403
+ graph : float, optional
404
+ Weight for the graph reconstruction loss, by default 1.0.
405
+ device : torch.device, optional
406
+ Device to run the model on (e.g., 'cpu' or 'cuda'), by default uses GPU if available.
407
+ num_parts : int, optional
408
+ Number of partitions for clustering the graph data, by default 10.
409
+ *args : tuple
410
+ Additional positional arguments.
411
+ **kwargs : dict
412
+ Additional keyword arguments.
413
+ """
414
+ def __init__(
415
+ self,
416
+ adata: AnnData,
417
+ layer: str = 'counts',
418
+ n_var: Optional[int] = None,
419
+ tech: str = 'PCA',
420
+ n_neighbors: int = 15,
421
+ batch_tech: Optional[str] = None,
422
+ all_feat: bool = True,
423
+ interpretable: bool = False,
424
+ hidden_dim: int = 128,
425
+ latent_dim: int = 10,
426
+ idim: Optional[int] = 2,
427
+ encoder_type: str = 'GAT',
428
+ encoder_hidden_layers: int = 2,
429
+ decoder_type: str = 'MLP',
430
+ decoder_hidden_dim: int = 128,
431
+ feature_decoder_hidden_layers: int = 2,
432
+ dropout: float = 5e-3,
433
+ use_residual: bool = True,
434
+ Cheb_k: Optional[int] = 1,
435
+ alpha: Optional[float] = .5,
436
+ lr: float = 1e-4,
437
+ beta: float = 1.0,
438
+ graph: float = 1.0,
439
+ device: torch.device = torch.device('cuda') if torch.cuda.is_available() else torch.device('cpu'),
440
+ num_parts: int = 10,
441
+ *args,
442
+ **kwargs,
443
+ ):
444
+ super().__init__(
445
+ adata=adata,
446
+ layer=layer,
447
+ n_var=n_var,
448
+ tech=tech,
449
+ n_neighbors=n_neighbors,
450
+ batch_tech=batch_tech,
451
+ all_feat=all_feat,
452
+ interpretable=interpretable,
453
+ hidden_dim=hidden_dim,
454
+ latent_dim=latent_dim,
455
+ idim=idim,
456
+ encoder_type=encoder_type,
457
+ encoder_hidden_layers=encoder_hidden_layers,
458
+ decoder_type=decoder_type,
459
+ decoder_hidden_dim=decoder_hidden_dim,
460
+ feature_decoder_hidden_layers=feature_decoder_hidden_layers,
461
+ dropout=dropout,
462
+ use_residual=use_residual,
463
+ Cheb_k=Cheb_k,
464
+ alpha=alpha,
465
+ lr=lr,
466
+ beta=beta,
467
+ graph=graph,
468
+ device=device,
469
+ num_parts=num_parts,
470
+ *args,
471
+ **kwargs,
472
+ )