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.
@@ -0,0 +1,309 @@
1
+ from .mixin import scviMixin, adjMixin
2
+ from .GODEVAE import GODEVAE_r
3
+ from .utils_ODE import get_step_size
4
+ import torch
5
+ import torch.nn.functional as F
6
+ from torch_geometric.data import Data
7
+ import numpy as np
8
+ from typing import List, Tuple, Optional
9
+ from torchdiffeq import odeint
10
+
11
+
12
+ class GODEVAE_Trainer_r(scviMixin, adjMixin):
13
+ """
14
+ Trainer class for training the GODEVAE_r model.
15
+
16
+ This class combines the functionality of `scviMixin` and `adjMixin` to train
17
+ a Graph Variational Autoencoder (GraphVAE) model. It handles the forward pass,
18
+ loss computation, and optimization steps.
19
+
20
+ Parameters
21
+ ----------
22
+ input_dim : int
23
+ Input feature dimension.
24
+ hidden_dim : int
25
+ Hidden layer dimension.
26
+ latent_dim : int
27
+ Latent space dimension.
28
+ ode_hidden_dim : int
29
+ Hidden dimension for the ODE function.
30
+ encoder_type : str
31
+ Type of encoder ('linear' or 'graph').
32
+ graph_type : str, optional
33
+ Type of graph conv layer ('GCN', 'Cheb', 'SAGE', 'TAG', 'ARMA', 'GAT', 'Transformer'), by default 'GAT'.
34
+ structure_decoder_type : str, optional
35
+ Type of structure decoder ('bilinear', 'inner_product', 'mlp'), by default 'mlp'.
36
+ feature_decoder_type : str, optional
37
+ Type of feature decoder ('linear' or 'graph'), by default 'linear'.
38
+ hidden_layers : int, optional
39
+ Number of hidden layers, by default 2.
40
+ decoder_hidden_dim : int, optional
41
+ Hidden dimension for structure MLP decoder, by default 128.
42
+ dropout : float, optional
43
+ Dropout rate, by default 0.05.
44
+ use_residual : bool, optional
45
+ Whether to use residual connections, by default True.
46
+ Cheb_k : int, optional
47
+ Order of Chebyshev polynomials, by default 1.
48
+ alpha : float, optional
49
+ Teleport probability, by default 0.5.
50
+ threshold : float, optional
51
+ Threshold for structure decoder, by default 0.
52
+ sparse_threshold : int, optional
53
+ Maximum edges per node for structure decoder, by default None.
54
+ lr : float
55
+ Learning rate for the optimizer.
56
+ beta : float
57
+ Weight for the KL divergence term in the loss function.
58
+ graph : float
59
+ Weight for the graph reconstruction loss.
60
+ device : torch.device
61
+ Device to run the model on (e.g., 'cpu' or 'cuda').
62
+
63
+ Attributes
64
+ ----------
65
+ godevae : GODEVAE_r
66
+ The GODEVAE_r model instance.
67
+ opt : torch.optim.Adam
68
+ Optimizer for training the model.
69
+ beta : float
70
+ Weight for the KL divergence term in the loss function.
71
+ graph : float
72
+ Weight for the graph reconstruction loss.
73
+ loss : List[Tuple[float, float, float, float, float]]
74
+ List of loss values (reconstruction loss, KL divergence, BCE loss, ODE reconstruction loss, latent divergence) for each training step.
75
+ device : torch.device
76
+ Device to run the model on.
77
+ """
78
+
79
+ def __init__(
80
+ self,
81
+ input_dim: int,
82
+ hidden_dim: int,
83
+ latent_dim: int,
84
+ ode_hidden_dim: int,
85
+ encoder_type: str = "graph",
86
+ graph_type: str = "GAT",
87
+ structure_decoder_type: str = "mlp",
88
+ feature_decoder_type: str = "linear",
89
+ hidden_layers: int = 2,
90
+ decoder_hidden_dim: int = 128,
91
+ dropout: float = 0.05,
92
+ use_residual: bool = True,
93
+ Cheb_k: int = 1,
94
+ alpha: float = 0.5,
95
+ threshold: float = 0,
96
+ sparse_threshold: Optional[int] = None,
97
+ lr: float = 1e-4,
98
+ beta: float = 1.0,
99
+ graph: float = 1.0,
100
+ w_recon: float = 1.0,
101
+ w_kl: float = 1.0,
102
+ w_adj: float = 1.0,
103
+ w_recon_ode: float = 1.0,
104
+ w_z_div: float = 1.0,
105
+ device: torch.device = torch.device("cuda"),
106
+ latent_type: str = 'q_m',
107
+ ):
108
+ self.godevae = GODEVAE_r(
109
+ input_dim,
110
+ hidden_dim,
111
+ latent_dim,
112
+ ode_hidden_dim,
113
+ encoder_type,
114
+ graph_type,
115
+ structure_decoder_type,
116
+ feature_decoder_type,
117
+ hidden_layers,
118
+ decoder_hidden_dim,
119
+ dropout,
120
+ use_residual,
121
+ Cheb_k,
122
+ alpha,
123
+ threshold,
124
+ sparse_threshold,
125
+ ).to(device)
126
+
127
+ self.opt = torch.optim.Adam(self.godevae.parameters(), lr=lr)
128
+ self.beta = beta
129
+ self.graph = graph
130
+ self.w_recon = w_recon
131
+ self.w_kl = w_kl
132
+ self.w_adj = w_adj
133
+ self.w_recon_ode = w_recon_ode
134
+ self.w_z_div = w_z_div
135
+ self.loss: List[Tuple[float, float, float, float, float]] = []
136
+ self.device = device
137
+ self.latent_type = latent_type
138
+
139
+ @torch.no_grad()
140
+ def take_latent(self, cd: Data) -> np.ndarray:
141
+ """
142
+ Extract latent variables from the encoder.
143
+
144
+ Parameters
145
+ ----------
146
+ cd : Data
147
+ Input data.
148
+ """
149
+ states = cd.x
150
+ edge_index = cd.edge_index
151
+ edge_weight = cd.edge_attr
152
+ if self.godevae.encoder_type == 'linear':
153
+ q_z, q_m, _, t = self.godevae.encoder(states)
154
+ else:
155
+ q_z, q_m, _, t = self.godevae.encoder(states, edge_index, edge_weight)
156
+ if self.latent_type == 'q_m':
157
+ return q_m.cpu().numpy()
158
+ elif self.latent_type == 'q_z':
159
+ return q_z.cpu().numpy()
160
+ else:
161
+ raise ValueError("latent_type must be 'q_m' or 'q_z'")
162
+
163
+ @torch.no_grad()
164
+ def take_odelatent(
165
+ self,
166
+ cd: Data,
167
+ step_size: Optional[int] = None,
168
+ step_wise: bool = False,
169
+ batch_size: Optional[int] = None,
170
+ ) -> np.ndarray:
171
+ """
172
+ Extract ODE latent variables by solving the latent ODE.
173
+
174
+ Parameters
175
+ ----------
176
+ cd : Data
177
+ Input data.
178
+ step_size : int, optional
179
+ Step size for the ODE solver, by default None.
180
+ step_wise : bool, optional
181
+ Whether to solve the ODE step-wise, by default False.
182
+ batch_size : int, optional
183
+ Batch size for processing, by default None.
184
+ """
185
+ states = cd.x
186
+ edge_index = cd.edge_index
187
+ edge_weight = cd.edge_attr
188
+
189
+ if self.godevae.encoder_type == 'linear':
190
+ q_z, q_m, _, t = self.godevae.encoder(states)
191
+ else:
192
+ q_z, q_m, _, t = self.godevae.encoder(states, edge_index, edge_weight)
193
+
194
+ if self.latent_type == 'q_m':
195
+ latent = q_m
196
+ elif self.latent_type == 'q_z':
197
+ latent = q_z
198
+ else:
199
+ raise ValueError("latent_type must be 'q_m' or 'q_z'")
200
+
201
+ sort_t, sort_idx, sort_ridx = np.unique(t.cpu(), return_index=True, return_inverse=True)
202
+ sort_t = torch.tensor(sort_t).to(self.device)
203
+ q_z_sort = latent[sort_idx]
204
+
205
+ q_z_ode = []
206
+ if batch_size is None:
207
+ batch_size = len(sort_t)
208
+
209
+ for i in range(0, len(sort_t), batch_size):
210
+ t_batch = sort_t[i : i + batch_size]
211
+ z_batch = q_z_sort[i : i + batch_size]
212
+ z0 = z_batch[0]
213
+
214
+ if not step_wise:
215
+ options = get_step_size(step_size, t_batch[0], t_batch[-1], len(t_batch))
216
+ pred_z = odeint(
217
+ self.godevae.lode_func, z0, t_batch, method="euler", options=options
218
+ )
219
+ else:
220
+ pred_z = torch.empty((len(t_batch), z_batch.size(1)), device=self.device)
221
+ pred_z[0] = z0
222
+ for j in range(len(t_batch) - 1):
223
+ t_segment = t_batch[j : j + 2]
224
+ options = get_step_size(step_size, t_segment[0], t_segment[-1], len(t_segment))
225
+ pred_z[j + 1] = odeint(
226
+ self.godevae.lode_func, z_batch[j], t_segment, method="euler", options=options
227
+ )[1]
228
+
229
+ q_z_ode.append(pred_z)
230
+
231
+ q_z_ode = torch.cat(q_z_ode)
232
+ q_z_ode = q_z_ode[sort_ridx.ravel()]
233
+ return q_z_ode.cpu().numpy()
234
+
235
+ @torch.no_grad()
236
+ def take_time(self, cd: Data) -> np.ndarray:
237
+ """
238
+ Extract time variables from the encoder.
239
+ """
240
+ states = cd.x
241
+ edge_index = cd.edge_index
242
+ edge_weight = cd.edge_attr
243
+ if self.godevae.encoder_type == 'linear':
244
+ ts = self.godevae.encoder(states)[-1]
245
+ else:
246
+ ts = self.godevae.encoder(states, edge_index, edge_weight)[-1]
247
+ return ts.cpu().numpy().ravel()
248
+
249
+ def update(self, cd: Data) -> None:
250
+ """
251
+ Perform a single training step for the GODEVAE model.
252
+ """
253
+ states = cd.x
254
+ edge_index = cd.edge_index
255
+ edge_weight = cd.edge_attr
256
+
257
+ # Forward pass
258
+ q_z, q_m, q_s, pred_a, pred_x, q_z_ode, pred_x_ode = self.godevae(states, edge_index, edge_weight)
259
+
260
+ # Compute losses
261
+ l = states.sum(-1).view(-1, 1)
262
+ recon_loss = self._recon_loss(l, states, pred_x)
263
+ kl_loss = self._kl_loss(q_m, q_s)
264
+
265
+ num_nodes = states.size(0)
266
+ adj = self._build_adj(edge_index, num_nodes, edge_weight).to_dense()
267
+ adj_loss = self._adj_loss(adj, pred_a)
268
+
269
+ idx1, idx2 = self.godevae.idx1, self.godevae.idx2
270
+
271
+ recon_loss_ode = self._recon_loss(l[idx1][idx2], states[idx1][idx2], pred_x_ode)
272
+ z_div = F.mse_loss(q_m[idx1][idx2], q_z_ode, reduction="none").sum(-1).mean()
273
+
274
+ # Total loss
275
+ loss = (self.w_recon * recon_loss +
276
+ self.w_kl * kl_loss +
277
+ self.w_adj * adj_loss +
278
+ self.w_recon_ode * recon_loss_ode +
279
+ self.w_z_div * z_div)
280
+
281
+ # Store loss values
282
+ self.loss.append((recon_loss.item(), kl_loss.item(), adj_loss.item(), recon_loss_ode.item(), z_div.item()))
283
+
284
+ # Backpropagation
285
+ self.opt.zero_grad()
286
+ loss.backward()
287
+ self.opt.step()
288
+
289
+ def _recon_loss(self, l, states, pred_x):
290
+ """
291
+ Compute reconstruction loss for node features.
292
+ """
293
+ pred_x = pred_x * l
294
+ disp = torch.exp(self.godevae.feature_decoder.disp)
295
+ return -self._log_nb(states, pred_x, disp).sum(-1).mean()
296
+
297
+ def _kl_loss(self, q_m, q_s):
298
+ """
299
+ Compute KL divergence for the latent space.
300
+ """
301
+ p_m = torch.zeros_like(q_m)
302
+ p_s = torch.zeros_like(q_s)
303
+ return self.beta * self._normal_kl(q_m, q_s, p_m, p_s).sum(-1).mean()
304
+
305
+ def _adj_loss(self, adj, pred_a):
306
+ """
307
+ Compute graph reconstruction loss.
308
+ """
309
+ return self.graph * F.binary_cross_entropy_with_logits(pred_a, adj)
GNODEVAE/SC3.py ADDED
@@ -0,0 +1,198 @@
1
+ import numpy as np
2
+ import pandas as pd
3
+ import scanpy as sc
4
+ from anndata import AnnData
5
+ from sklearn.metrics.pairwise import euclidean_distances
6
+ from scipy.stats import spearmanr
7
+ from scipy.linalg import eigh
8
+ from sklearn.decomposition import PCA
9
+ from sklearn.cluster import KMeans
10
+ from scipy.cluster.hierarchy import linkage, fcluster
11
+ from tqdm import tqdm
12
+
13
+ class SC3:
14
+ """
15
+ Python implementation of the SC3 (Single-Cell Consensus Clustering) algorithm.
16
+
17
+ This class provides a streamlined workflow to perform consensus clustering on
18
+ single-cell RNA-seq data, taking an AnnData object as input and producing
19
+ cluster assignments.
20
+
21
+ The workflow consists of:
22
+ 1. Gene filtering.
23
+ 2. Calculating multiple distance matrices (Euclidean, Pearson, Spearman).
24
+ 3. Transforming these matrices (PCA, Laplacian).
25
+ 4. Performing k-means clustering on all transformed matrices for a range of k.
26
+ 5. Building a consensus matrix from all clustering results for each k.
27
+ 6. Hierarchical clustering on the consensus matrix to get final labels.
28
+ """
29
+
30
+ def __init__(self, adata: AnnData, use_highly_variable: bool = True, layer: str = None):
31
+ """
32
+ Initializes the SC3 object.
33
+
34
+ Args:
35
+ adata: An AnnData object containing the single-cell data.
36
+ use_highly_variable: If True, uses highly variable genes.
37
+ If False, uses all genes.
38
+ layer: The layer in adata to use for calculations. If None, uses adata.X.
39
+ """
40
+ self.adata = adata.copy()
41
+ self.use_highly_variable = use_highly_variable
42
+ self.layer = layer
43
+ self._prepare_data()
44
+
45
+ def _prepare_data(self):
46
+ """Selects the data layer and subsets to highly variable genes if specified."""
47
+ if self.layer and self.layer in self.adata.layers:
48
+ self.adata.X = self.adata.layers[self.layer]
49
+
50
+ if self.use_highly_variable:
51
+ if 'highly_variable' not in self.adata.var.keys():
52
+ print("Highly variable genes not found. Calculating...")
53
+ sc.pp.highly_variable_genes(self.adata)
54
+ self.adata = self.adata[:, self.adata.var['highly_variable']].copy()
55
+
56
+ def fit(self, ks, d_region_min=0.02, d_region_max=0.05):
57
+ """
58
+ Executes the complete SC3 workflow.
59
+
60
+ Args:
61
+ ks (list or int): A list or a single integer for the number of clusters k.
62
+ d_region_min: Minimum number of eigenvectors (as a fraction of cells).
63
+ d_region_max: Maximum number of eigenvectors (as a fraction of cells).
64
+
65
+ Returns:
66
+ The fitted SC3 object.
67
+ """
68
+ if isinstance(ks, int):
69
+ ks = [ks]
70
+
71
+ print("1. Calculating distance matrices...")
72
+ distance_matrices = self._calculate_distances()
73
+
74
+ print("2. Calculating transformations...")
75
+ n_cells = self.adata.n_obs
76
+ n_dim_min = int(np.floor(d_region_min * n_cells))
77
+ n_dim_max = int(np.ceil(d_region_max * n_cells))
78
+ dims_range = list(range(max(2, n_dim_min), min(n_cells - 1, n_dim_max + 1)))
79
+ transformed_matrices = self._calculate_transformations(distance_matrices, max(dims_range))
80
+
81
+ print("3. Running k-means clustering...")
82
+ kmeans_results = self._run_kmeans(transformed_matrices, ks, dims_range)
83
+
84
+ print("4. Calculating consensus matrices...")
85
+ self._calculate_consensus(kmeans_results, ks)
86
+
87
+ print("SC3 analysis complete.")
88
+ return self
89
+
90
+ def get_embedding(self, k: int) -> np.ndarray:
91
+ """
92
+ Returns the consensus matrix for a given k, which can be viewed as a
93
+ cell-by-cell similarity embedding.
94
+ """
95
+ if 'sc3_consensus_matrices' in self.adata.uns and k in self.adata.uns['sc3_consensus_matrices']:
96
+ return self.adata.uns['sc3_consensus_matrices'][k]
97
+ else:
98
+ raise ValueError(f"Consensus matrix for k={k} not found. Please run .fit() for this k first.")
99
+
100
+ def _calculate_distances(self):
101
+ # self.adata.X is (n_cells, n_genes)
102
+ if hasattr(self.adata.X, 'toarray'):
103
+ data = self.adata.X.toarray()
104
+ else:
105
+ data = self.adata.X
106
+
107
+ # For correlation between cells, cells should be columns.
108
+ # So we need (n_genes, n_cells)
109
+ data_t = data.T
110
+
111
+ # Euclidean is between rows of the input. So input should be (n_cells, n_genes)
112
+ euclidean_dist = euclidean_distances(data)
113
+
114
+ # Pearson correlation. Input is (n_genes, n_cells)
115
+ # We need to check for cells (columns) with zero variance.
116
+ col_vars = np.var(data_t, axis=0)
117
+ valid_cell_mask = col_vars > 0
118
+
119
+ pearson_dist = np.ones((data.shape[0], data.shape[0]))
120
+
121
+ if np.sum(valid_cell_mask) > 1:
122
+ # subset the data to only include cells with non-zero variance
123
+ valid_data = data_t[:, valid_cell_mask]
124
+ # Calculate correlation on the valid cells. The result will be smaller.
125
+ corr_matrix = np.corrcoef(valid_data, rowvar=False)
126
+ # Place the results back into the full-size matrix
127
+ ix = np.ix_(valid_cell_mask, valid_cell_mask)
128
+ pearson_dist[ix] = 1 - corr_matrix
129
+
130
+ # Spearman correlation. Input is (n_genes, n_cells)
131
+ spearman_corr, _ = spearmanr(data_t, axis=0)
132
+ # Handle case where spearmanr returns a single value
133
+ if spearman_corr.ndim == 0:
134
+ spearman_corr = np.array([[1.0]])
135
+ # Replace NaNs that can occur from zero variance columns
136
+ spearman_dist = 1 - np.nan_to_num(spearman_corr)
137
+
138
+ return {'euclidean': euclidean_dist, 'pearson': pearson_dist, 'spearman': spearman_dist}
139
+
140
+ def _calculate_transformations(self, dists, max_dim):
141
+ transformed = {}
142
+ for name, d in dists.items():
143
+ pca = PCA(n_components=max_dim)
144
+ transformed[f'{name}_pca'] = pca.fit_transform(d)
145
+
146
+ A = np.exp(-d / d.max())
147
+ D_inv_sqrt = np.diag(1.0 / np.sqrt(np.sum(A, axis=1)))
148
+ L = np.eye(A.shape[0]) - D_inv_sqrt @ A @ D_inv_sqrt
149
+ eigvals, eigvecs = eigh(L)
150
+ sorted_indices = np.argsort(eigvals)
151
+ transformed[f'{name}_laplacian'] = eigvecs[:, sorted_indices][:, :max_dim]
152
+ return transformed
153
+
154
+ def _kmeans_worker(self, task):
155
+ k = task['k']
156
+ dim = task['dim']
157
+ name = task['name']
158
+ data = task['data']
159
+
160
+ kmeans = KMeans(n_clusters=k, random_state=0, n_init=10)
161
+ labels = kmeans.fit_predict(data)
162
+ return {'key': f'{name}_{k}_{dim}', 'labels': labels}
163
+
164
+ def _run_kmeans(self, transfs, ks, dims_range):
165
+ tasks = [{'k': k, 'dim': dim, 'name': name, 'data': data[:, :dim]}
166
+ for k in ks for dim in dims_range for name, data in transfs.items()]
167
+
168
+ results = []
169
+ for task in tqdm(tasks, desc="Running K-Means"):
170
+ results.append(self._kmeans_worker(task))
171
+
172
+ return {res['key']: res['labels'] for res in results}
173
+
174
+
175
+
176
+ def _calculate_consensus(self, kmeans_results, ks):
177
+ self.adata.uns['sc3_consensus_matrices'] = {}
178
+ for k in ks:
179
+ relevant_keys = [key for key in kmeans_results.keys() if f'_{k}_' in key]
180
+ if not relevant_keys:
181
+ continue
182
+
183
+ clusterings = np.array([kmeans_results[key] for key in relevant_keys]).T
184
+ n_cells, n_runs = clusterings.shape
185
+ consensus_matrix = np.zeros((n_cells, n_cells))
186
+
187
+ for i in range(n_cells):
188
+ for j in range(i, n_cells):
189
+ similarity = np.sum(clusterings[i, :] == clusterings[j, :])
190
+ consensus_matrix[i, j] = consensus_matrix[j, i] = similarity
191
+
192
+ consensus_matrix /= n_runs
193
+ distance_from_consensus = 1 - consensus_matrix
194
+ linked = linkage(distance_from_consensus[np.triu_indices(n_cells, k=1)], method='complete')
195
+ labels = fcluster(linked, k, criterion='maxclust')
196
+
197
+ self.adata.uns['sc3_consensus_matrices'][k] = consensus_matrix
198
+ self.adata.obs[f'sc3_{k}_clusters'] = pd.Categorical(labels)
GNODEVAE/__init__.py ADDED
@@ -0,0 +1,6 @@
1
+ from .agent import agent, agent_r
2
+ from .GODEVAE_agent import GNODEVAE_agent_r, GNODEVAE_agent_subgraph
3
+
4
+ __all__ = [agent, agent_r, GNODEVAE_agent_r, GNODEVAE_agent_subgraph]
5
+
6
+ __version__ = '0.0.3'