scCODE 0.1.0__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.
CODE/environment.py ADDED
@@ -0,0 +1,149 @@
1
+ from .model import CODEVAE
2
+ from .mixin import EnvMixin
3
+ import numpy as np
4
+ from sklearn.cluster import KMeans
5
+
6
+
7
+ class Env(CODEVAE, EnvMixin):
8
+ """
9
+ Environment class that encapsulates data handling and model training.
10
+
11
+ This class bridges the data (from AnnData) and the model (CODEVAE), providing
12
+ methods for data loading, batch sampling, and score computation during training.
13
+ It inherits both model functionality (CODEVAE) and environment utilities (EnvMixin).
14
+
15
+ Attributes:
16
+ X (np.ndarray): Log-normalized gene expression matrix (n_obs × n_var)
17
+ n_obs (int): Number of observations (cells)
18
+ n_var (int): Number of variables (genes)
19
+ labels (np.ndarray): KMeans cluster labels for evaluation
20
+ batch_size (int): Number of cells per training batch
21
+ idx (np.ndarray): Indices of current batch
22
+ score (list): History of evaluation metrics
23
+ """
24
+
25
+ def __init__(
26
+ self,
27
+ adata,
28
+ layer,
29
+ percent,
30
+ recon,
31
+ irecon,
32
+ beta,
33
+ dip,
34
+ tc,
35
+ info,
36
+ hidden_dim,
37
+ latent_dim,
38
+ i_dim,
39
+ use_ode,
40
+ use_moco,
41
+ loss_mode,
42
+ lr,
43
+ vae_reg,
44
+ ode_reg,
45
+ moco_weight,
46
+ device,
47
+ *args,
48
+ **kwargs,
49
+ ):
50
+ self._register_anndata(adata, layer, latent_dim)
51
+ self.batch_size = int(percent * self.n_obs)
52
+ super().__init__(
53
+ recon=recon,
54
+ irecon=irecon,
55
+ beta=beta,
56
+ dip=dip,
57
+ tc=tc,
58
+ info=info,
59
+ state_dim=self.n_var,
60
+ hidden_dim=hidden_dim,
61
+ latent_dim=latent_dim,
62
+ i_dim=i_dim,
63
+ use_ode=use_ode,
64
+ use_moco=use_moco,
65
+ loss_mode=loss_mode,
66
+ lr=lr,
67
+ vae_reg=vae_reg,
68
+ ode_reg=ode_reg,
69
+ moco_weight=moco_weight,
70
+ device=device,
71
+ )
72
+ self.score = []
73
+
74
+ def load_data(
75
+ self,
76
+ ):
77
+ """
78
+ Sample a batch of data for training.
79
+
80
+ Returns:
81
+ np.ndarray: Batch of data with shape (batch_size, n_var).
82
+ """
83
+ data, idx = self._sample_data()
84
+ self.idx = idx
85
+ return data
86
+
87
+ def step(self, data):
88
+ """
89
+ Perform one training step: update model and compute metrics.
90
+
91
+ Args:
92
+ data (np.ndarray): Batch of training data.
93
+ """
94
+ self.update(data)
95
+ latent = self.take_latent(data)
96
+ score = self._calc_score(latent)
97
+ self.score.append(score)
98
+
99
+ def _sample_data(
100
+ self,
101
+ ):
102
+ """
103
+ Randomly sample a batch of cells from the dataset.
104
+
105
+ Returns:
106
+ tuple: (data, idx) containing:
107
+ - data: Batch data of shape (batch_size, n_var)
108
+ - idx: Indices of sampled cells
109
+ """
110
+ idx = np.random.permutation(self.n_obs)
111
+ idx_ = np.random.choice(idx, self.batch_size)
112
+ data = self.X[idx_, :]
113
+ return data, idx_
114
+
115
+ def _register_anndata(self, adata, layer: str, latent_dim):
116
+ """
117
+ Register and preprocess data from AnnData object.
118
+
119
+ Args:
120
+ adata (AnnData): Annotated data object
121
+ layer (str): Layer name to extract (e.g., 'counts')
122
+ latent_dim (int): Dimension of latent space (used as heuristic for initial clustering)
123
+
124
+ Raises:
125
+ KeyError: If the specified layer does not exist in adata.layers
126
+ """
127
+ # Validate layer exists
128
+ if layer not in adata.layers:
129
+ available_layers = list(adata.layers.keys())
130
+ raise KeyError(
131
+ f"Layer '{layer}' not found in adata.layers. "
132
+ f"Available layers: {available_layers}"
133
+ )
134
+
135
+ # Log1p transform the counts - handle both sparse and dense arrays
136
+ layer_data = adata.layers[layer]
137
+ if hasattr(layer_data, 'toarray'):
138
+ # Sparse matrix
139
+ self.X = np.log1p(layer_data.toarray())
140
+ else:
141
+ # Dense array
142
+ self.X = np.log1p(layer_data)
143
+ self.n_obs = adata.shape[0]
144
+ self.n_var = adata.shape[1]
145
+ # Initialize cluster labels for evaluation using reasonable heuristic
146
+ # Use min of latent_dim or 10 as a reasonable number of clusters
147
+ n_clusters = min(latent_dim, 10)
148
+ self.labels = KMeans(n_clusters=n_clusters, random_state=42).fit_predict(self.X)
149
+ return
CODE/mixin.py ADDED
@@ -0,0 +1,317 @@
1
+ import torch
2
+ import torch.nn.functional as F
3
+ from torchdiffeq import odeint
4
+ import numpy as np
5
+ from sklearn.cluster import KMeans
6
+ from sklearn.metrics import (
7
+ adjusted_mutual_info_score,
8
+ normalized_mutual_info_score,
9
+ silhouette_score,
10
+ calinski_harabasz_score,
11
+ davies_bouldin_score,
12
+ )
13
+ from typing import Optional
14
+
15
+
16
+ class ScviMixin:
17
+ """Mixin class for scVI-related loss functions."""
18
+
19
+ def _normal_kl(self, mu1, lv1, mu2, lv2):
20
+ """
21
+ Calculates the KL divergence between two normal distributions.
22
+
23
+ Args:
24
+ mu1: Mean of the first distribution.
25
+ lv1: Log variance of the first distribution.
26
+ mu2: Mean of the second distribution.
27
+ lv2: Log variance of the second distribution.
28
+
29
+ Returns:
30
+ The KL divergence.
31
+ """
32
+ v1 = torch.exp(lv1)
33
+ v2 = torch.exp(lv2)
34
+ lstd1 = lv1 / 2.0
35
+ lstd2 = lv2 / 2.0
36
+ kl = lstd2 - lstd1 + (v1 + (mu1 - mu2) ** 2.0) / (2.0 * v2) - 0.5
37
+ return kl
38
+
39
+ def _log_nb(self, x, mu, theta, eps=1e-8):
40
+ """
41
+ Calculates the log probability under a negative binomial distribution.
42
+
43
+ Args:
44
+ x: The data.
45
+ mu: The mean of the distribution.
46
+ theta: The dispersion parameter.
47
+ eps: A small constant for numerical stability.
48
+
49
+ Returns:
50
+ The log probability.
51
+ """
52
+ log_theta_mu_eps = torch.log(theta + mu + eps)
53
+ res = (
54
+ theta * (torch.log(theta + eps) - log_theta_mu_eps)
55
+ + x * (torch.log(mu + eps) - log_theta_mu_eps)
56
+ + torch.lgamma(x + theta)
57
+ - torch.lgamma(theta)
58
+ - torch.lgamma(x + 1)
59
+ )
60
+ return res
61
+
62
+ def _log_zinb(self, x, mu, theta, pi, eps=1e-8):
63
+ """
64
+ Calculates the log probability under a zero-inflated negative binomial distribution.
65
+
66
+ Args:
67
+ x: The data.
68
+ mu: The mean of the distribution.
69
+ theta: The dispersion parameter.
70
+ pi: The logits of the zero-inflation mixing weight.
71
+ eps: A small constant for numerical stability.
72
+
73
+ Returns:
74
+ The log probability.
75
+ """
76
+ softplus_pi = F.softplus(-pi)
77
+ log_theta_eps = torch.log(theta + eps)
78
+ log_theta_mu_eps = torch.log(theta + mu + eps)
79
+ pi_theta_log = -pi + theta * (log_theta_eps - log_theta_mu_eps)
80
+
81
+ case_zero = F.softplus(pi_theta_log) - softplus_pi
82
+ mul_case_zero = torch.mul((x < eps).type(torch.float32), case_zero)
83
+
84
+ case_non_zero = (
85
+ -softplus_pi
86
+ + pi_theta_log
87
+ + x * (torch.log(mu + eps) - log_theta_mu_eps)
88
+ + torch.lgamma(x + theta)
89
+ - torch.lgamma(theta)
90
+ - torch.lgamma(x + 1)
91
+ )
92
+ mul_case_non_zero = torch.mul((x > eps).type(torch.float32), case_non_zero)
93
+
94
+ res = mul_case_zero + mul_case_non_zero
95
+ return res
96
+
97
+
98
+ class NODEMixin:
99
+ """Mixin class for Neural ODE related functionalities."""
100
+
101
+ @staticmethod
102
+ def get_step_size(step_size, t0, t1, n_points):
103
+ """
104
+ Gets the step size configuration for the ODE solver.
105
+
106
+ Args:
107
+ step_size: The step size. If None, it is calculated automatically.
108
+ t0: The start time.
109
+ t1: The end time.
110
+ n_points: The number of time points.
111
+
112
+ Returns:
113
+ A dictionary with the ODE solver options.
114
+ """
115
+ if step_size is None:
116
+ return {}
117
+ else:
118
+ if step_size == "auto":
119
+ step_size = (t1 - t0) / (n_points - 1)
120
+ return {"step_size": step_size}
121
+
122
+ def solve_ode(
123
+ self,
124
+ ode_func: torch.nn.Module,
125
+ z0: torch.Tensor,
126
+ t: torch.Tensor,
127
+ method: str = "rk4",
128
+ step_size: Optional[float] = None,
129
+ ) -> torch.Tensor:
130
+ """
131
+ Solves the ODE using torchdiffeq.
132
+
133
+ Args:
134
+ ode_func: The ODE function model.
135
+ z0: The initial state.
136
+ t: The time points.
137
+ method: The solving method.
138
+ step_size: The step size.
139
+
140
+ Returns:
141
+ The ODE solution.
142
+ """
143
+ options = self.get_step_size(step_size, t[0], t[-1], len(t))
144
+
145
+ cpu_z0 = z0.to("cpu")
146
+ cpu_t = t.to("cpu")
147
+
148
+ pred_z = odeint(ode_func, cpu_z0, cpu_t, method=method, options=options)
149
+
150
+ pred_z = pred_z.to(z0.device)
151
+
152
+ return pred_z
153
+
154
+
155
+ class BetaTCMixin:
156
+ """Mixin class for beta-TCVAE loss."""
157
+
158
+ def _betatc_compute_gaussian_log_density(self, samples, mean, log_var):
159
+ import math
160
+
161
+ pi = torch.tensor(math.pi, requires_grad=False)
162
+ normalization = torch.log(2 * pi)
163
+ inv_sigma = torch.exp(-log_var)
164
+ tmp = samples - mean
165
+ return -0.5 * (tmp * tmp * inv_sigma + log_var + normalization)
166
+
167
+ def _betatc_compute_total_correlation(self, z_sampled, z_mean, z_logvar):
168
+ log_qz_prob = self._betatc_compute_gaussian_log_density(
169
+ z_sampled.unsqueeze(dim=1),
170
+ z_mean.unsqueeze(dim=0),
171
+ z_logvar.unsqueeze(dim=0),
172
+ )
173
+ log_qz_product = log_qz_prob.exp().sum(dim=1).log().sum(dim=1)
174
+ log_qz = log_qz_prob.sum(dim=2).exp().sum(dim=1).log()
175
+ return (log_qz - log_qz_product).mean()
176
+
177
+
178
+ class InfoMixin:
179
+ """Mixin class for InfoVAE (MMD) loss."""
180
+
181
+ def _compute_mmd(self, z_posterior_samples, z_prior_samples):
182
+ mean_pz_pz = self._compute_unbiased_mean(
183
+ self._compute_kernel(z_prior_samples, z_prior_samples), unbiased=True
184
+ )
185
+ mean_pz_qz = self._compute_unbiased_mean(
186
+ self._compute_kernel(z_prior_samples, z_posterior_samples), unbiased=False
187
+ )
188
+ mean_qz_qz = self._compute_unbiased_mean(
189
+ self._compute_kernel(z_posterior_samples, z_posterior_samples),
190
+ unbiased=True,
191
+ )
192
+ mmd = mean_pz_pz - 2 * mean_pz_qz + mean_qz_qz
193
+ return mmd
194
+
195
+ def _compute_unbiased_mean(self, kernel, unbiased):
196
+ N, M = kernel.shape
197
+ if unbiased:
198
+ sum_kernel = kernel.sum(dim=(0, 1)) - torch.diagonal(
199
+ kernel, dim1=0, dim2=1
200
+ ).sum(dim=-1)
201
+ mean_kernel = sum_kernel / (N * (N - 1))
202
+ else:
203
+ mean_kernel = kernel.mean(dim=(0, 1))
204
+ return mean_kernel
205
+
206
+ def _compute_kernel(self, z0, z1):
207
+ batch_size, z_size = z0.shape
208
+ z0 = z0.unsqueeze(-2)
209
+ z1 = z1.unsqueeze(-3)
210
+ z0 = z0.expand(batch_size, batch_size, z_size)
211
+ z1 = z1.expand(batch_size, batch_size, z_size)
212
+ kernel = self._kernel_rbf(z0, z1)
213
+ return kernel
214
+
215
+ def _kernel_rbf(self, x, y):
216
+ z_size = x.shape[-1]
217
+ sigma = 2 * 2 * z_size
218
+ kernel = torch.exp(-((x - y).pow(2).sum(dim=-1) / sigma))
219
+ return kernel
220
+
221
+
222
+ class DipMixin:
223
+ """Mixin class for DIP-VAE loss."""
224
+
225
+ def _dip_loss(self, q_m, q_s):
226
+ cov_matrix = self._dip_cov_matrix(q_m, q_s)
227
+ cov_diag = torch.diagonal(cov_matrix)
228
+ cov_off_diag = cov_matrix - torch.diag(cov_diag)
229
+ dip_loss_d = torch.sum((cov_diag - 1) ** 2)
230
+ dip_loss_od = torch.sum(cov_off_diag**2)
231
+ dip_loss = 10 * dip_loss_d + 5 * dip_loss_od
232
+ return dip_loss
233
+
234
+ def _dip_cov_matrix(self, q_m, q_s):
235
+ cov_q_mean = torch.cov(q_m.T)
236
+ E_var = torch.mean(torch.diag(F.softplus(q_s).exp()), dim=0)
237
+ cov_matrix = cov_q_mean + E_var
238
+ return cov_matrix
239
+
240
+
241
+ class EnvMixin:
242
+ """
243
+ Mixin class for environment-related functionalities.
244
+
245
+ Provides methods for computing evaluation scores and clustering metrics
246
+ during training, including correlation analysis of latent dimensions.
247
+ """
248
+
249
+ def _calc_score(self, latent):
250
+ """
251
+ Calculate evaluation scores for latent representations.
252
+
253
+ Args:
254
+ latent (np.ndarray): Latent representations
255
+
256
+ Returns:
257
+ tuple: Evaluation metrics (ARI, NMI, ASW, C_H, D_B, P_C)
258
+ """
259
+ labels = self._calc_label(latent)
260
+ scores = self._metrics(latent, labels)
261
+ return scores
262
+
263
+ def _calc_label(self, latent):
264
+ """
265
+ Compute cluster labels using KMeans.
266
+
267
+ Args:
268
+ latent (np.ndarray): Latent representations
269
+
270
+ Returns:
271
+ np.ndarray: Cluster labels
272
+ """
273
+ # Use the number of unique true labels to determine clusters
274
+ n_clusters = len(np.unique(self.labels))
275
+ labels = KMeans(n_clusters=n_clusters).fit_predict(latent)
276
+ return labels
277
+
278
+ def _calc_corr(self, latent):
279
+ """
280
+ Calculate mean absolute correlation between latent dimensions.
281
+
282
+ Higher values indicate redundant/correlated dimensions, lower values
283
+ indicate more independent/disentangled representations.
284
+
285
+ Args:
286
+ latent (np.ndarray): Latent representations
287
+
288
+ Returns:
289
+ float: Mean absolute correlation (excluding diagonal)
290
+ """
291
+ acorr = abs(np.corrcoef(latent.T))
292
+ return acorr.sum(axis=1).mean().item() - 1
293
+
294
+ def _metrics(self, latent, labels):
295
+ """
296
+ Compute comprehensive clustering and separation metrics.
297
+
298
+ Args:
299
+ latent (np.ndarray): Latent representations
300
+ labels (np.ndarray): Cluster labels
301
+
302
+ Returns:
303
+ tuple: (ARI, NMI, ASW, C_H, D_B, P_C)
304
+ - ARI: Adjusted Mutual Information
305
+ - NMI: Normalized Mutual Information
306
+ - ASW: Average Silhouette Width
307
+ - C_H: Calinski-Harabasz score
308
+ - D_B: Davies-Bouldin score
309
+ - P_C: Pearson Correlation between dimensions
310
+ """
311
+ ARI = adjusted_mutual_info_score(self.labels[self.idx], labels)
312
+ NMI = normalized_mutual_info_score(self.labels[self.idx], labels)
313
+ ASW = silhouette_score(latent, labels)
314
+ C_H = calinski_harabasz_score(latent, labels)
315
+ D_B = davies_bouldin_score(latent, labels)
316
+ P_C = self._calc_corr(latent)
317
+ return ARI, NMI, ASW, C_H, D_B, P_C