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/mixin.py ADDED
@@ -0,0 +1,418 @@
1
+ """
2
+ Mixin Classes for GNODEVAE
3
+
4
+ This module provides mixin classes that add specific functionality to the
5
+ main agent and environment classes. Mixins follow the composition pattern
6
+ to separate concerns and promote code reuse.
7
+
8
+ Key Components:
9
+ - scviMixin: Single-cell variational inference utilities
10
+ - adjMixin: Adjacency matrix construction utilities
11
+ - envMixin: Environment management utilities
12
+ - scMixin: Single-cell data preprocessing utilities
13
+ """
14
+
15
+ import torch
16
+ import numpy as np
17
+ from sklearn.cluster import KMeans
18
+ from sklearn.metrics import (
19
+ normalized_mutual_info_score,
20
+ adjusted_mutual_info_score,
21
+ silhouette_score,
22
+ davies_bouldin_score,
23
+ calinski_harabasz_score,
24
+ )
25
+ from sklearn.decomposition import (
26
+ PCA,
27
+ NMF,
28
+ FastICA,
29
+ TruncatedSVD,
30
+ FactorAnalysis,
31
+ LatentDirichletAllocation
32
+ )
33
+ from typing import Optional, Tuple
34
+ from anndata import AnnData
35
+ import scanpy as sc
36
+
37
+ class scviMixin:
38
+ """
39
+ Mixin providing variational inference utilities for single-cell data.
40
+
41
+ This mixin implements common probability distributions and loss functions
42
+ used in variational autoencoders for single-cell RNA-seq data, including:
43
+ - KL divergence between normal distributions
44
+ - Negative binomial log-likelihood for count data
45
+
46
+ These methods are used to compute the VAE loss components.
47
+ """
48
+
49
+ def _normal_kl(
50
+ self,
51
+ mu1: torch.Tensor,
52
+ lv1: torch.Tensor,
53
+ mu2: torch.Tensor,
54
+ lv2: torch.Tensor
55
+ ) -> torch.Tensor:
56
+ """
57
+ Compute KL divergence between two normal distributions.
58
+
59
+ Calculates KL(N(mu1, sigma1^2) || N(mu2, sigma2^2)) analytically.
60
+ This is used as a regularization term in the VAE loss to encourage
61
+ the learned latent distribution to match a prior distribution
62
+ (typically N(0, I)).
63
+
64
+ Parameters
65
+ ----------
66
+ mu1 : torch.Tensor
67
+ Mean of the first distribution, shape (batch_size, latent_dim).
68
+ lv1 : torch.Tensor
69
+ Log variance of the first distribution, shape (batch_size, latent_dim).
70
+ mu2 : torch.Tensor
71
+ Mean of the second distribution (prior), shape (batch_size, latent_dim).
72
+ lv2 : torch.Tensor
73
+ Log variance of the second distribution (prior).
74
+
75
+ Returns
76
+ -------
77
+ torch.Tensor
78
+ KL divergence for each dimension, shape (batch_size, latent_dim).
79
+ Sum over the latent dimension to get total KL per sample.
80
+
81
+ Notes
82
+ -----
83
+ The KL divergence is computed as:
84
+ KL = 0.5 * (log(σ2^2/σ1^2) + (σ1^2 + (μ1-μ2)^2)/σ2^2 - 1)
85
+
86
+ For standard VAE with N(0,1) prior, this simplifies to:
87
+ KL = 0.5 * (μ^2 + σ^2 - log(σ^2) - 1)
88
+ """
89
+ v1 = torch.exp(lv1)
90
+ v2 = torch.exp(lv2)
91
+ lstd1 = lv1 / 2.0
92
+ lstd2 = lv2 / 2.0
93
+ kl = lstd2 - lstd1 + (v1 + (mu1 - mu2) ** 2.0) / (2.0 * v2) - 0.5
94
+ return kl
95
+
96
+ def _log_nb(
97
+ self,
98
+ x: torch.Tensor,
99
+ mu: torch.Tensor,
100
+ theta: torch.Tensor,
101
+ eps: float = 1e-8
102
+ ) -> torch.Tensor:
103
+ """
104
+ Compute log-likelihood of negative binomial distribution.
105
+
106
+ The negative binomial (NB) distribution is commonly used to model
107
+ UMI count data in single-cell RNA-seq, as it can capture both the
108
+ mean-variance relationship and overdispersion in count data.
109
+
110
+ Parameters
111
+ ----------
112
+ x : torch.Tensor
113
+ Observed counts, shape (batch_size, num_genes).
114
+ mu : torch.Tensor
115
+ Mean parameter of NB distribution, shape (batch_size, num_genes).
116
+ theta : torch.Tensor
117
+ Dispersion parameter of NB distribution. Lower values indicate
118
+ higher overdispersion. Shape (num_genes,) or (batch_size, num_genes).
119
+ eps : float, default=1e-8
120
+ Small constant for numerical stability in logarithms.
121
+
122
+ Returns
123
+ -------
124
+ torch.Tensor
125
+ Log-likelihood for each gene count, shape (batch_size, num_genes).
126
+
127
+ Notes
128
+ -----
129
+ The negative binomial distribution is parameterized as:
130
+ NB(x | μ, θ) with mean μ and variance μ + μ^2/θ
131
+
132
+ The log-likelihood is:
133
+ log p(x|μ,θ) = log Γ(x+θ) - log Γ(θ) - log Γ(x+1)
134
+ + x*log(μ) + θ*log(θ) - (x+θ)*log(θ+μ)
135
+
136
+ This is used as the reconstruction loss for count data.
137
+ """
138
+ log_theta_mu_eps = torch.log(theta + mu + eps)
139
+ res = (
140
+ theta * (torch.log(theta + eps) - log_theta_mu_eps)
141
+ + x * (torch.log(mu + eps) - log_theta_mu_eps)
142
+ + torch.lgamma(x + theta)
143
+ - torch.lgamma(theta)
144
+ - torch.lgamma(x + 1)
145
+ )
146
+ return res
147
+
148
+
149
+ class adjMixin:
150
+ """
151
+ Mixin providing adjacency matrix construction utilities.
152
+
153
+ This mixin provides methods for building adjacency matrices from edge
154
+ representations, which is useful for loss computation and graph manipulation.
155
+ """
156
+
157
+ def _build_adj(
158
+ self,
159
+ edge_index: torch.Tensor,
160
+ num_nodes: int,
161
+ edge_weight: Optional[torch.Tensor] = None
162
+ ) -> torch.Tensor:
163
+ """
164
+ Build a sparse adjacency matrix.
165
+
166
+ Parameters
167
+ ----------
168
+ edge_index : torch.Tensor
169
+ Edge indices of the graph, shape (2, num_edges).
170
+ num_nodes : int
171
+ Number of nodes in the graph.
172
+ edge_weight : torch.Tensor, optional
173
+ Weights of the edges, by default None. If None, all edges are assigned a weight of 1.
174
+
175
+ Returns
176
+ -------
177
+ torch.Tensor
178
+ Sparse adjacency matrix in COO format.
179
+ """
180
+ if edge_weight is None:
181
+ edge_weight = torch.ones(edge_index.size(1), device=edge_index.device)
182
+ adj = torch.sparse_coo_tensor(
183
+ edge_index,
184
+ edge_weight,
185
+ size=(num_nodes, num_nodes),
186
+ device=edge_index.device,
187
+ )
188
+ return adj
189
+
190
+
191
+ class envMixin:
192
+ def _calc_score(
193
+ self,
194
+ latent: np.ndarray
195
+ ) -> Tuple[float, float, float, float, float, float]:
196
+ """
197
+ Calculate clustering and correlation scores for the latent space.
198
+
199
+ Parameters
200
+ ----------
201
+ latent : np.ndarray
202
+ Latent space representation of the data, shape (num_samples, num_features).
203
+
204
+ Returns
205
+ -------
206
+ Tuple[float, float, float, float, float, float]
207
+ A tuple containing the following scores:
208
+ - ARI: Adjusted Rand Index.
209
+ - NMI: Normalized Mutual Information.
210
+ - ASW: Average Silhouette Width.
211
+ - C_H: Calinski-Harabasz Index.
212
+ - D_B: Davies-Bouldin Index.
213
+ - P_C: Average pairwise correlation.
214
+ """
215
+ labels = self._calc_label(latent)
216
+ scores = self._metrics(latent, labels)
217
+ return scores
218
+
219
+ def _calc_label(
220
+ self,
221
+ latent: np.ndarray
222
+ ) -> np.ndarray:
223
+ """
224
+ Perform KMeans clustering on the latent space.
225
+
226
+ Parameters
227
+ ----------
228
+ latent : np.ndarray
229
+ Latent space representation of the data, shape (num_samples, num_features).
230
+
231
+ Returns
232
+ -------
233
+ np.ndarray
234
+ Cluster labels for each sample.
235
+ """
236
+ labels = KMeans(latent.shape[1]).fit_predict(latent)
237
+ return labels
238
+
239
+ def _calc_corr(
240
+ self,
241
+ latent: np.ndarray
242
+ ) -> float:
243
+ """
244
+ Calculate the average absolute pairwise correlation in the latent space.
245
+
246
+ Parameters
247
+ ----------
248
+ latent : np.ndarray
249
+ Latent space representation of the data, shape (num_samples, num_features).
250
+
251
+ Returns
252
+ -------
253
+ float
254
+ Average absolute pairwise correlation.
255
+ """
256
+ acorr = abs(np.corrcoef(latent.T))
257
+ return acorr.sum(axis=1).mean().item() - 1
258
+
259
+ def _metrics(
260
+ self,
261
+ latent: np.ndarray,
262
+ labels: np.ndarray
263
+ ) -> Tuple[float, float, float, float, float, float]:
264
+ """
265
+ Compute clustering and correlation metrics.
266
+
267
+ Parameters
268
+ ----------
269
+ latent : np.ndarray
270
+ Latent space representation of the data, shape (num_samples, num_features).
271
+ labels : np.ndarray
272
+ Cluster labels for each sample.
273
+
274
+ Returns
275
+ -------
276
+ Tuple[float, float, float, float, float, float]
277
+ A tuple containing the following scores:
278
+ - ARI: Adjusted Rand Index.
279
+ - NMI: Normalized Mutual Information.
280
+ - ASW: Average Silhouette Width.
281
+ - C_H: Calinski-Harabasz Index.
282
+ - D_B: Davies-Bouldin Index.
283
+ - P_C: Average pairwise correlation.
284
+ """
285
+ true_labels = self.labels[self.idx]
286
+ ARI = adjusted_mutual_info_score(true_labels, labels)
287
+ NMI = normalized_mutual_info_score(true_labels, labels)
288
+ ASW = silhouette_score(latent, labels)
289
+ C_H = calinski_harabasz_score(latent, labels)
290
+ D_B = davies_bouldin_score(latent, labels)
291
+ P_C = self._calc_corr(latent)
292
+ return ARI, NMI, ASW, C_H, D_B, P_C
293
+
294
+
295
+ class scMixin:
296
+ def _preprocess(
297
+ self,
298
+ adata: AnnData,
299
+ layer: str,
300
+ n_var: int
301
+ ) -> None:
302
+ """Preprocess the AnnData object by normalizing, log-transforming, and selecting highly variable genes.
303
+
304
+ Parameters
305
+ ----------
306
+ adata : AnnData
307
+ Annotated data matrix (e.g., single-cell data).
308
+ layer : str
309
+ Layer of the AnnData object to store original features.
310
+ n_var : int
311
+ Number of highly variable genes to select.
312
+ """
313
+ try:
314
+ # Store original data in specified layer
315
+ if layer not in adata.layers.keys():
316
+ adata.layers[layer] = adata.X.copy()
317
+ print(f'Creating layer: {layer}.')
318
+
319
+ # Normalize and log-transform the data
320
+ if 'log1p' not in adata.uns.keys():
321
+ sc.pp.normalize_total(adata, target_sum=1e4)
322
+ sc.pp.log1p(adata)
323
+ print('Performing normalization.')
324
+
325
+ # Select highly variable genes
326
+ if 'highly_variable' not in adata.var.keys():
327
+ if n_var:
328
+ sc.pp.highly_variable_genes(adata, n_top_genes=n_var)
329
+ else:
330
+ sc.pp.highly_variable_genes(adata)
331
+ print('Selecting highly variable genes.')
332
+
333
+ except Exception as e:
334
+ print(f"Error during preprocessing: {e}")
335
+
336
+ def _decomposition(
337
+ self,
338
+ adata: AnnData,
339
+ tech: str,
340
+ latent_dim: int
341
+ ) -> None:
342
+ """Perform dimensionality reduction based on the selected method.
343
+
344
+ Parameters
345
+ ----------
346
+ adata : AnnData
347
+ Annotated data matrix (e.g., single-cell data).
348
+ tech : str
349
+ Decomposition method to use (PCA, NMF, FastICA, TruncatedSVD, FactorAnalysis, LatentDirichletAllocation).
350
+ latent_dim : int
351
+ Latent space dimension.
352
+ """
353
+ try:
354
+ # Perform dimensionality reduction based on the selected method
355
+ if tech == 'PCA':
356
+ latent = PCA(n_components=latent_dim).fit_transform(adata[:, adata.var['highly_variable']].X.toarray())
357
+ elif tech == 'NMF':
358
+ latent = NMF(n_components=latent_dim).fit_transform(adata[:, adata.var['highly_variable']].X.toarray())
359
+ elif tech == 'FastICA':
360
+ latent = FastICA(n_components=latent_dim).fit_transform(adata[:, adata.var['highly_variable']].X.toarray())
361
+ elif tech == 'TruncatedSVD':
362
+ latent = TruncatedSVD(n_components=latent_dim).fit_transform(adata[:, adata.var['highly_variable']].X.toarray())
363
+ elif tech == 'FactorAnalysis':
364
+ latent = FactorAnalysis(n_components=latent_dim).fit_transform(adata[:, adata.var['highly_variable']].X.toarray())
365
+ elif tech == 'LatentDirichletAllocation':
366
+ latent = LatentDirichletAllocation(n_components=latent_dim).fit_transform(adata[:, adata.var['highly_variable']].X.toarray())
367
+ else:
368
+ raise ValueError(f"Unsupported decomposition method: {tech}. Choose from PCA, NMF, FastICA, TruncatedSVD, FactorAnalysis, LatentDirichletAllocation.")
369
+
370
+ # Store the latent representation
371
+ adata.obsm[f'X_{tech}'] = latent
372
+ print(f'Stored latent representation in adata.obsm["X_{tech}"].')
373
+
374
+ except Exception as e:
375
+ print(f"Error during decomposition: {e}")
376
+
377
+ def _batchcorrect(
378
+ self,
379
+ adata: AnnData,
380
+ batch_tech: str,
381
+ tech: str,
382
+ layer: str
383
+ ) -> None:
384
+ """Correct batch effects using specified methods.
385
+
386
+ Parameters
387
+ ----------
388
+ adata : AnnData
389
+ Annotated data matrix (e.g., single-cell data).
390
+ batch_tech : str
391
+ Method to correct batch effects ('harmony' or 'scvi').
392
+ tech : str
393
+ Decomposition method used for batch correction.
394
+ layer : str
395
+ Layer of the AnnData object to use for scVI.
396
+ """
397
+ try:
398
+ # Batch effect correction if specified
399
+ if batch_tech == 'harmony':
400
+ import scanpy.external as sce
401
+ # Use Harmony integration
402
+ sce.pp.harmony_integrate(adata, key='batch', basis=f'X_{tech}', adjusted_basis=f'X_harmony_{tech}')
403
+ print('Applied Harmony integration for batch correction.')
404
+
405
+ elif batch_tech == 'scvi':
406
+ import scvi
407
+ # Use original X for scVI
408
+ scvi.model.SCVI.setup_anndata(adata, layer=layer)
409
+ model = scvi.model.SCVI(adata)
410
+ model.train()
411
+ latent = model.get_latent_representation()
412
+ adata.obsm['X_scvi'] = latent
413
+ print('Applied scVI for batch correction.')
414
+
415
+ except Exception as e:
416
+ print(f"Error during batch correction: {e}")
417
+
418
+