autoencodix 0.2.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.

Potentially problematic release.


This version of autoencodix might be problematic. Click here for more details.

Files changed (91) hide show
  1. autoencodix/__init__.py +27 -0
  2. autoencodix/base/.ipynb_checkpoints/_base_pipeline-checkpoint.py +1274 -0
  3. autoencodix/base/.ipynb_checkpoints/_base_trainer-checkpoint.py +247 -0
  4. autoencodix/base/__init__.py +21 -0
  5. autoencodix/base/_base_autoencoder.py +138 -0
  6. autoencodix/base/_base_dataset.py +103 -0
  7. autoencodix/base/_base_evaluator.py +34 -0
  8. autoencodix/base/_base_loss.py +311 -0
  9. autoencodix/base/_base_pipeline.py +1355 -0
  10. autoencodix/base/_base_predictor.py +6 -0
  11. autoencodix/base/_base_preprocessor.py +1033 -0
  12. autoencodix/base/_base_trainer.py +259 -0
  13. autoencodix/base/_base_visualizer.py +578 -0
  14. autoencodix/base/sampleconfig.yaml +132 -0
  15. autoencodix/configs/__init__.py +21 -0
  16. autoencodix/configs/default_config.py +652 -0
  17. autoencodix/configs/disentanglix_config.py +15 -0
  18. autoencodix/configs/maskix_config.py +39 -0
  19. autoencodix/configs/ontix_config.py +35 -0
  20. autoencodix/configs/stackix_config.py +33 -0
  21. autoencodix/configs/vanillix_config.py +18 -0
  22. autoencodix/configs/varix_config.py +15 -0
  23. autoencodix/configs/xmodalix_config.py +43 -0
  24. autoencodix/disentanglix.py +72 -0
  25. autoencodix/evaluate/.ipynb_checkpoints/evaluate-checkpoint.py +532 -0
  26. autoencodix/evaluate/__init__.py +4 -0
  27. autoencodix/evaluate/_general_evaluator.py +730 -0
  28. autoencodix/evaluate/_xmodalix_evaluator.py +376 -0
  29. autoencodix/imagix.py +76 -0
  30. autoencodix/losses/disentanglix_loss.py +215 -0
  31. autoencodix/losses/maskix_loss.py +94 -0
  32. autoencodix/losses/vanillix_loss.py +28 -0
  33. autoencodix/losses/varix_loss.py +102 -0
  34. autoencodix/losses/xmodal_loss.py +304 -0
  35. autoencodix/maskix.py +108 -0
  36. autoencodix/modeling/.ipynb_checkpoints/__init__-checkpoint.py +16 -0
  37. autoencodix/modeling/.ipynb_checkpoints/_captum_forward-checkpoint.py +16 -0
  38. autoencodix/modeling/__init__.py +20 -0
  39. autoencodix/modeling/_captum_forward.py +20 -0
  40. autoencodix/modeling/_classifier.py +45 -0
  41. autoencodix/modeling/_imagevae_architecture.py +296 -0
  42. autoencodix/modeling/_imgfast_architecture.py +288 -0
  43. autoencodix/modeling/_layer_factory.py +71 -0
  44. autoencodix/modeling/_maskix_architecture.py +190 -0
  45. autoencodix/modeling/_ontix_architecture.py +305 -0
  46. autoencodix/modeling/_vanillix_architecture.py +136 -0
  47. autoencodix/modeling/_varix_architecture.py +192 -0
  48. autoencodix/notebooks/__init__.py +0 -0
  49. autoencodix/ontix.py +136 -0
  50. autoencodix/py.typed +0 -0
  51. autoencodix/stackix.py +122 -0
  52. autoencodix/trainers/__init__.py +6 -0
  53. autoencodix/trainers/_general_trainer.py +525 -0
  54. autoencodix/trainers/_maskix_trainer.py +116 -0
  55. autoencodix/trainers/_ontix_trainer.py +77 -0
  56. autoencodix/trainers/_stackix_orchestrator.py +522 -0
  57. autoencodix/trainers/_stackix_trainer.py +209 -0
  58. autoencodix/trainers/_xmodal_trainer.py +1006 -0
  59. autoencodix/utils/.ipynb_checkpoints/_explainer-checkpoint.py +118 -0
  60. autoencodix/utils/.ipynb_checkpoints/_model_output-checkpoint.py +30 -0
  61. autoencodix/utils/.ipynb_checkpoints/_utils-checkpoint.py +626 -0
  62. autoencodix/utils/.ipynb_checkpoints/adata_converter-checkpoint.py +99 -0
  63. autoencodix/utils/.ipynb_checkpoints/feature_importance-checkpoint.py +823 -0
  64. autoencodix/utils/__init__.py +22 -0
  65. autoencodix/utils/_annealer.py +193 -0
  66. autoencodix/utils/_bulkreader.py +232 -0
  67. autoencodix/utils/_explainer.py +246 -0
  68. autoencodix/utils/_imgreader.py +404 -0
  69. autoencodix/utils/_internals.py +23 -0
  70. autoencodix/utils/_llm_explainer.py +318 -0
  71. autoencodix/utils/_losses.py +20 -0
  72. autoencodix/utils/_model_output.py +30 -0
  73. autoencodix/utils/_result.py +393 -0
  74. autoencodix/utils/_screader.py +76 -0
  75. autoencodix/utils/_traindynamics.py +187 -0
  76. autoencodix/utils/_utils.py +690 -0
  77. autoencodix/utils/adata_converter.py +111 -0
  78. autoencodix/utils/example_data.py +398 -0
  79. autoencodix/utils/feature_importance.py +829 -0
  80. autoencodix/utils/prompts.py +21 -0
  81. autoencodix/vanillix.py +141 -0
  82. autoencodix/varix.py +80 -0
  83. autoencodix/visualize/__init__.py +5 -0
  84. autoencodix/visualize/_general_visualizer.py +913 -0
  85. autoencodix/visualize/_imagix_visualizer.py +111 -0
  86. autoencodix/visualize/_xmodal_visualizer.py +841 -0
  87. autoencodix/visualize/visualize.py +1214 -0
  88. autoencodix/xmodalix.py +318 -0
  89. autoencodix-0.2.0.dist-info/METADATA +143 -0
  90. autoencodix-0.2.0.dist-info/RECORD +91 -0
  91. autoencodix-0.2.0.dist-info/WHEEL +4 -0
@@ -0,0 +1,823 @@
1
+ import os
2
+ import warnings
3
+ from typing import Dict
4
+
5
+ import anndata as ad
6
+ import gseapy as gp
7
+ import matplotlib.pyplot as plt
8
+ import numpy as np
9
+ import pandas as pd
10
+ import scanpy as sc
11
+ import scipy
12
+ import seaborn as sns
13
+ import torch
14
+ import torch.nn as nn
15
+ from captum.attr import (
16
+ LRP,
17
+ DeepLiftShap,
18
+ GradientShap,
19
+ IntegratedGradients,
20
+ Lime,
21
+ LimeBase,
22
+ )
23
+ from IPython.display import HTML, Image, clear_output, display
24
+
25
+ from autoencodix.modeling._captum_forward import CaptumForward
26
+ from autoencodix.utils.adata_converter import AnnDataConverter
27
+
28
+ warnings.filterwarnings("ignore")
29
+
30
+
31
+ class Vanillix_EncoderSingleDim(nn.Module):
32
+ def __init__(self, vae_model, dim):
33
+ super(Vanillix_EncoderSingleDim, self).__init__()
34
+ # Accessing the required components from the original VAE model
35
+ self.encoder = vae_model._encoder
36
+ self.input_dim = vae_model.input_dim
37
+ self.dim = dim # latent dim
38
+
39
+ def forward(self, x):
40
+ if x.shape[1] != self.input_dim:
41
+ raise ValueError(
42
+ f"Expected input with {self.input_dim} features, but got {x.shape[1]} features. "
43
+ f"This may indicate missing data modalities or incorrect data preparation."
44
+ )
45
+
46
+ total_elements = x.numel()
47
+ assert (
48
+ total_elements % self.input_dim == 0
49
+ ), f"Total elements {total_elements} is not a multiple of input_dim {self.input_dim}"
50
+
51
+ batch_size = x.size(0)
52
+ x = x.view(batch_size, -1)
53
+ latent = self.encoder(x)
54
+ output = latent[:, self.dim]
55
+ output = output.unsqueeze(1) # Equivalent to output.reshape(output.shape[0], 1)
56
+ return output
57
+
58
+
59
+ def make_DeepLiftShap_Vanillix_dim(model, inputs, baselines, latent_dimension):
60
+ model_encoder_dim = Vanillix_EncoderSingleDim(model, dim=latent_dimension)
61
+ deeplift = DeepLiftShap(model_encoder_dim)
62
+ attributions, convergence = deeplift.attribute(
63
+ inputs=inputs, baselines=baselines, return_convergence_delta=True
64
+ )
65
+ avg_abs_attributions = attributions.abs().mean(dim=0)
66
+ return avg_abs_attributions, convergence
67
+
68
+
69
+ def make_feature_importance_Vanillix(
70
+ input_adata,
71
+ van,
72
+ method="DeepLiftShap",
73
+ n_subset=100,
74
+ seed_int=12,
75
+ baseline_type="mean",
76
+ baseline_group="all",
77
+ obs_col=None,
78
+ ):
79
+ """
80
+ Computes attributions for a trained Vanillix model.
81
+
82
+ Parameters
83
+ ----------
84
+ van : object
85
+ Object containing the trained Vanillix model and input data as an AnnData object.
86
+
87
+ method : str, {'DeepLiftShap', 'IntegratedGradients'}, default='DeepLiftShap'
88
+ post-hoc feature importance assessment method
89
+ - 'DeepLiftShap': method from pytorch Captum library, approximates SHAP values using Deeplift
90
+ - 'IntegratedGradients': method from pytorch Captum library, attribution via Integrated gradients
91
+
92
+ n_subset : int, default=100
93
+ Subset of randomly selected cells to compute attributions on.
94
+
95
+ seed_int : int, default=12
96
+ Seed for reproducible random sampling (NumPy & PyTorch).
97
+
98
+ baseline_type : str, {'mean', 'random_sample'}, default='mean'
99
+ How to generate the baseline:
100
+ - 'mean': average expression of the group
101
+ - 'random_sample': a randomly picked cell from the group
102
+
103
+ baseline_group : str, default='all'
104
+ Which group of cells to use as the baseline.
105
+ Use 'all' or a specific group label from `adata.obs[obs_col]`.
106
+
107
+ obs_col : str or None, default=None
108
+ Column in `adata.obs` that defines groups. Required if `baseline_group` is not 'all'.
109
+
110
+ Returns
111
+ -------
112
+ df_attributions : pandas.DataFrame
113
+ Gene-level attribution scores per latent dimension.
114
+ """
115
+ if baseline_group != "all" and obs_col is None:
116
+ raise ValueError(
117
+ "obs_col must be provided when using a group-specific baseline."
118
+ )
119
+ np.random.seed(seed_int)
120
+ torch.manual_seed(seed_int)
121
+ model = van.result.model
122
+ # input_adata = van.raw_user_data["multi_sc"]["multi_sc"].mod["user-data"]
123
+ inputs = torch.tensor(
124
+ input_adata.X.toarray()
125
+ if scipy.sparse.issparse(input_adata.X)
126
+ else input_adata.X
127
+ )
128
+ if baseline_group == "all":
129
+ if baseline_type == "mean":
130
+ baseline_mean = inputs.mean(axis=0) # gene_means
131
+ baselines = torch.tensor(np.tile(baseline_mean, (inputs.shape[0], 1)))
132
+ if baseline_type == "random_sample":
133
+ baseline_random = inputs[torch.randint(0, inputs.size(0), (1,)).item()]
134
+ baselines = torch.tensor(np.tile(baseline_random, (inputs.shape[0], 1)))
135
+ else:
136
+ input_adata_filtered = input_adata[input_adata.obs[obs_col] == baseline_group]
137
+ inputs_filtered = torch.tensor(
138
+ input_adata_filtered.X.toarray()
139
+ if scipy.sparse.issparse(input_adata_filtered.X)
140
+ else input_adata_filtered.X
141
+ )
142
+ if baseline_type == "mean":
143
+ baseline_mean = inputs_filtered.mean(axis=0) # gene_means
144
+ baselines = torch.tensor(np.tile(baseline_mean, (inputs.shape[0], 1)))
145
+ if baseline_type == "random_sample":
146
+ baseline_random = inputs_filtered[
147
+ torch.randint(0, inputs_filtered.size(0), (1,)).item()
148
+ ]
149
+ baselines = torch.tensor(np.tile(baseline_random, (inputs.shape[0], 1)))
150
+ gene_names = input_adata.var_names
151
+ cell_IDs = input_adata.obs_names
152
+
153
+ latent_dimensions = list(range(0, van.result.adata_latent.shape[1]))
154
+ indices_DeepLiftShap = np.random.choice(
155
+ inputs.shape[0], size=n_subset, replace=False
156
+ )
157
+ all_attr = []
158
+ for latent_dim in latent_dimensions:
159
+ if method == "DeepLiftShap":
160
+ avg_abs_attributions, convergence = make_DeepLiftShap_Vanillix_dim(
161
+ model=model,
162
+ inputs=inputs[indices_DeepLiftShap].float(),
163
+ baselines=baselines[indices_DeepLiftShap].float(),
164
+ latent_dimension=latent_dim,
165
+ )
166
+ if method == "IntegratedGradients":
167
+ avg_abs_attributions, convergence = make_IntegratedGradients_Vanillix_dim(
168
+ model=model,
169
+ inputs=inputs[indices_DeepLiftShap].float(),
170
+ baselines=baselines[indices_DeepLiftShap].float(),
171
+ latent_dimension=latent_dim,
172
+ )
173
+
174
+ all_attr.append(avg_abs_attributions.detach().cpu())
175
+
176
+ attr_matrix = torch.stack(all_attr).T.numpy()
177
+
178
+ df_attributions = pd.DataFrame(
179
+ attr_matrix,
180
+ index=list(gene_names),
181
+ columns=[f"latent_dimension_{i}" for i in latent_dimensions],
182
+ )
183
+ return df_attributions
184
+
185
+
186
+ def get_top_kgenes_per_latent_dimension(df_attributions, latent_dim=0, topk=10):
187
+ """
188
+ Returns the top-k genes with the highest attribution for a given latent dimension.
189
+
190
+ Parameters
191
+ ----------
192
+ df_attributions : pandas.DataFrame
193
+ DataFrame with genes as rows and latent dimensions as columns
194
+
195
+ latent_dim : int, default=0
196
+ Index of the latent dimension to extract top genes from
197
+
198
+ topk : int, default=10
199
+ Number of top genes to return.
200
+
201
+ Returns
202
+ -------
203
+ topk_genes : list of str
204
+ List of gene names with the highest attributions for the selected latent dimension.
205
+ """
206
+ topk_genes = (
207
+ df_attributions["latent_dimension_" + str(latent_dim)]
208
+ .nlargest(topk)
209
+ .index.tolist()
210
+ )
211
+ return topk_genes
212
+
213
+
214
+ def plot_union_top_genes_heatmap(df, top_n=50, cmap="viridis", save=None):
215
+ """
216
+ Plots a heatmap for all latent dimensions, showing the union of the top N genes per dimension.
217
+
218
+ Parameters:
219
+ - df (pd.DataFrame): DataFrame with feature attributions.
220
+ Rows = genes/features, Columns = latent dimensions.
221
+ - top_n (int): Number of top genes to select per latent dimension (default: 50).
222
+ - cmap (str): Colormap for the heatmap (default: 'viridis').
223
+ - save (str) : path for saving
224
+ """
225
+
226
+ # Collect top N genes per latent dimension
227
+ top_genes_sets = []
228
+ for col in df.columns:
229
+ top_genes = df[col].nlargest(top_n).index
230
+ top_genes_sets.append(set(top_genes))
231
+
232
+ # Union of all top genes across dimensions
233
+ union_genes = sorted(set.union(*top_genes_sets))
234
+
235
+ # Subset the dataframe to only these genes
236
+ data = df.loc[union_genes]
237
+
238
+ # Plot heatmap
239
+ plt.figure(figsize=(len(df.columns) * 0.1 + 3, max(6, 0.14 * len(union_genes))))
240
+ ax = sns.heatmap(
241
+ data,
242
+ cmap=cmap,
243
+ annot=False,
244
+ linewidths=0.5,
245
+ linecolor="gray",
246
+ cbar_kws={"label": "Attribution Score"},
247
+ )
248
+
249
+ # Format ticks (centered)
250
+ # ax.set_xticks([i + 0.5 for i in range(len(data.columns))])
251
+ ax.set_xticklabels(data.columns, rotation=90, ha="right", fontsize=9)
252
+
253
+ ax.set_yticks([i + 0.5 for i in range(len(data.index))])
254
+ ax.set_yticklabels(data.index, rotation=0, fontsize=8)
255
+
256
+ plt.title(f"attribution of top {top_n} genes per latent dimension", fontsize=10)
257
+
258
+ plt.tight_layout()
259
+ if save is not None:
260
+ plt.savefig(save, bbox_inches="tight")
261
+ plt.show()
262
+
263
+
264
+ def get_top_genes_per_dimension(df, top_n=100):
265
+ """
266
+ Get top N genes per latent dimension.
267
+ Returns a dict: {dimension_name: [list of top genes]}
268
+ """
269
+ top_genes = {}
270
+ for dim in df.columns:
271
+ top_genes[dim] = df[dim].nlargest(top_n).index.tolist()
272
+ return top_genes
273
+
274
+
275
+ def run_go_enrichment(
276
+ top_genes_dict,
277
+ n_top_pathways=10,
278
+ gene_set_library="GO_Biological_Process_2021",
279
+ organism="Human",
280
+ ):
281
+ """
282
+ Run GO enrichment using Enrichr (via gseapy).
283
+ Returns a dict of DataFrames with results per latent dimension.
284
+ """
285
+ results = {}
286
+ for dim, gene_list in top_genes_dict.items():
287
+ enr = gp.enrichr(
288
+ gene_list=gene_list,
289
+ gene_sets=gene_set_library,
290
+ organism=organism,
291
+ outdir=None, # no file output
292
+ cutoff=0.05,
293
+ )
294
+ results[dim] = enr.results.sort_values("Adjusted P-value").head(n_top_pathways)
295
+ return results
296
+
297
+
298
+ def plot_GO_log_odds_all(PE_dict, top_n=10, base_save_identifier=None):
299
+ """
300
+ Plots log odds ratio of top enriched GO terms for each latent dimension.
301
+
302
+ Parameters:
303
+ - PE_dict (dict): Dict of DataFrames, keyed by latent dimension name.
304
+ - top_n (int): Number of top GO terms to plot per dimension.
305
+ """
306
+ for dim, df in PE_dict.items():
307
+ if df.empty or "Odds Ratio" not in df.columns:
308
+ print(f"Skipping {dim}: empty or missing required columns.")
309
+ continue
310
+
311
+ # Compute log odds ratio
312
+ df["log_odds_ratio"] = np.log(df["Odds Ratio"])
313
+
314
+ # Select top_n terms
315
+ plot_df = df.sort_values(by="log_odds_ratio", ascending=True).tail(top_n)
316
+
317
+ # Plot
318
+ plt.figure(figsize=(10, 0.5 * top_n)) # wider and taller
319
+ bars = plt.barh(
320
+ plot_df["Term"],
321
+ plot_df["log_odds_ratio"],
322
+ color="#D4AF3A",
323
+ height=0.6, # makes bars thicker
324
+ )
325
+
326
+ # Add value labels
327
+ for bar in bars:
328
+ plt.text(
329
+ bar.get_width() - 1.05,
330
+ bar.get_y() + bar.get_height() / 2,
331
+ f"{bar.get_width():.2f}",
332
+ va="center",
333
+ ha="left",
334
+ fontsize=8,
335
+ color="#C40308",
336
+ )
337
+
338
+ plt.xlabel("log(odds Ratio)", fontsize=10)
339
+ plt.title(f"{dim} — top {top_n} Enriched GO terms", fontsize=12)
340
+ plt.xticks(fontsize=8)
341
+ plt.yticks(fontsize=9) # smaller tick labels
342
+ plt.tight_layout()
343
+ if base_save_identifier is not None:
344
+ plt.savefig(
345
+ base_save_identifier + "_" + str(dim) + ".pdf", bbox_inches="tight"
346
+ )
347
+ plt.show()
348
+
349
+
350
+ def do_miraculix_visualization():
351
+ display(HTML('<p style="font-size:20px;">Calculate feature importance</p>'))
352
+ display(Image(filename="miraculix_zaubertrank.gif"))
353
+ clear_output(wait=True)
354
+
355
+
356
+ def do_feature_importance_Vanillix(
357
+ van,
358
+ method="DeepLiftShap",
359
+ baseline_type="mean",
360
+ baseline_group="all",
361
+ obs_col=None,
362
+ n_subset=100,
363
+ seed_int=12,
364
+ do_visualizations=True,
365
+ top_n_genes_heatmap=50,
366
+ top_n_foreground_pathways=30,
367
+ gene_set_library=None,
368
+ organism="Human",
369
+ n_top_pathways=10,
370
+ save_out_path=None,
371
+ do_miraculix_vis=False,
372
+ ):
373
+ """
374
+ Computes DeepLiftShap attributions for a trained Vanillix model and visulaization.
375
+
376
+ Parameters
377
+ ----------
378
+ van : object
379
+ Object containing the trained Vanillix model and input data as an AnnData object.
380
+
381
+ method : str, {'DeepLiftShap', 'IntegratedGradients'}, default='DeepLiftShap'
382
+ post-hoc feature importance assessment method
383
+ - 'DeepLiftShap': method from pytorch Captum library, approximates SHAP values using Deeplift
384
+ - 'IntegratedGradients': method from pytorch Captum library, attribution via Integrated gradients
385
+
386
+ n_subset : int, default=100
387
+ Subset of randomly selected cells to compute attributions on.
388
+
389
+ seed_int : int, default=12
390
+ Seed for reproducible random sampling (NumPy & PyTorch).
391
+
392
+ baseline_type : str, {'mean', 'random_sample'}, default='mean'
393
+ How to generate the baseline:
394
+ - 'mean': average expression of the group
395
+ - 'random_sample': a randomly picked cell from the group
396
+
397
+ baseline_group : str, default='all'
398
+ Which group of cells to use as the baseline.
399
+ Use 'all' or a specific group label from `adata.obs[obs_col]`.
400
+
401
+ obs_col : str or None, default=None
402
+ Column in `adata.obs` that defines groups. Required if `baseline_group` is not 'all'.
403
+
404
+ top_n_genes_heatmap : int, default=50
405
+ Number of top genes (with highest attribution scores) per latent dimension to visualize in the heatmap.
406
+
407
+ top_n_foreground_pathways : int, default=30
408
+ Number of top genes to include as "foreground" in enrichment analysis.
409
+
410
+ gene_set_library : str, default=None,
411
+ The gene set library to use for enrichment analysis (from Enrichr), e.g. "GO_Biological_Process_2021".
412
+
413
+ organism : str, default='Human'
414
+ The organism relevant to the gene sets used in enrichment.
415
+
416
+ n_top_pathways : int, default=10
417
+ Number of top enriched pathways to visualize in the results per latent dimension.
418
+
419
+ save_out_path : str or None, default=None
420
+ File path to save the output results figures.
421
+ If None, results will not be saved to disk.
422
+
423
+ do_miraculix_vis : bool, default=True
424
+ Show Miraculix-style GIF.
425
+
426
+ Returns
427
+ -------
428
+ df_attributions : pandas.DataFrame
429
+ Gene-level attribution scores per latent dimension.
430
+ """
431
+ feature_importance_methods = {"DeepLiftShap", "IntegratedGradients"}
432
+ if method not in feature_importance_methods:
433
+ raise ValueError(
434
+ f"Invalid method '{method}'. Must be one of: {', '.join(feature_importance_methods)}."
435
+ )
436
+
437
+ # baseline_type
438
+ if do_miraculix_vis:
439
+ do_miraculix_visualization()
440
+
441
+ input_data: Dict[str, ad.Anndata] = AnnDataConverter.dataset_to_adata(
442
+ datasetcontainer=van.result.datasets
443
+ )
444
+ for data_name, adata in input_data.items():
445
+ df_attributions = make_feature_importance_Vanillix(
446
+ input_adata=adata,
447
+ van=van,
448
+ method=method,
449
+ n_subset=n_subset,
450
+ seed_int=seed_int,
451
+ baseline_type=baseline_type,
452
+ baseline_group=baseline_group,
453
+ obs_col=obs_col,
454
+ )
455
+ if save_out_path is not None:
456
+ save_path = os.path.join(save_out_path, "df_attributions.csv")
457
+ df_attributions.to_csv(save_path)
458
+
459
+ """
460
+ if not do_visualizations:
461
+ display(HTML('<p style="font-size:20px;">Feature importance completed!</p>'))
462
+ """
463
+
464
+ # top genes plot
465
+ if do_visualizations:
466
+ if save_out_path is not None:
467
+ save_path = os.path.join(save_out_path, "top_attributions.pdf")
468
+ plot_union_top_genes_heatmap(
469
+ df=df_attributions,
470
+ top_n=top_n_genes_heatmap,
471
+ cmap="plasma",
472
+ save=save_path,
473
+ )
474
+ else:
475
+ plot_union_top_genes_heatmap(
476
+ df=df_attributions, top_n=top_n_genes_heatmap, cmap="plasma", save=None
477
+ )
478
+
479
+ dict_top_genes = get_top_genes_per_dimension(
480
+ df=df_attributions, top_n=top_n_foreground_pathways
481
+ )
482
+ PE_dict = run_go_enrichment(
483
+ top_genes_dict=dict_top_genes,
484
+ n_top_pathways=n_top_pathways,
485
+ gene_set_library=gene_set_library,
486
+ organism=organism,
487
+ )
488
+
489
+ if save_out_path is not None:
490
+ base_save_identifier = os.path.join(save_out_path, "GO_pathways")
491
+ plot_GO_log_odds_all(
492
+ PE_dict=PE_dict,
493
+ top_n=n_top_pathways,
494
+ base_save_identifier=base_save_identifier,
495
+ )
496
+ else:
497
+ plot_GO_log_odds_all(
498
+ PE_dict=PE_dict, top_n=n_top_pathways, base_save_identifier=None
499
+ )
500
+ return df_attributions
501
+
502
+
503
+ class Varix_EncoderSingleDim(nn.Module):
504
+ def __init__(self, vae_model, dim):
505
+ super(Varix_EncoderSingleDim, self).__init__()
506
+ # Accessing the required components from the original VAE model
507
+ self.encoder = vae_model._encoder
508
+ self.mu = vae_model._mu
509
+ self.logvar = vae_model._logvar
510
+ self.reparameterize = vae_model.reparameterize
511
+ self.input_dim = vae_model.input_dim
512
+ self.dim = dim # latent dim
513
+
514
+ def forward(self, x):
515
+ if x.shape[1] != self.input_dim:
516
+ raise ValueError(
517
+ f"Expected input with {self.input_dim} features, but got {x.shape[1]} features. "
518
+ f"This may indicate missing data modalities or incorrect data preparation."
519
+ )
520
+
521
+ total_elements = x.numel()
522
+ assert (
523
+ total_elements % self.input_dim == 0
524
+ ), f"Total elements {total_elements} is not a multiple of input_dim {self.input_dim}"
525
+
526
+ batch_size = x.size(0)
527
+ x = x.view(batch_size, -1)
528
+ latent = self.encoder(x)
529
+ mu = self.mu(latent)
530
+ logvar = self.logvar(latent)
531
+ z = self.reparameterize(mu, logvar)
532
+ output = z[:, self.dim]
533
+ output = output.unsqueeze(1) # Equivalent to output.reshape(output.shape[0], 1)
534
+ return output
535
+
536
+
537
+ def make_DeepLiftShap_Varix_dim(model, inputs, baselines, latent_dimension):
538
+ model_encoder_dim = Varix_EncoderSingleDim(model, dim=latent_dimension)
539
+ deeplift = DeepLiftShap(model_encoder_dim)
540
+ attributions, convergence = deeplift.attribute(
541
+ inputs=inputs, baselines=baselines, return_convergence_delta=True
542
+ )
543
+ avg_abs_attributions = attributions.abs().mean(dim=0)
544
+ return avg_abs_attributions, convergence
545
+
546
+
547
+ def make_feature_importance_Varix(
548
+ van,
549
+ method="DeepLiftShap",
550
+ n_subset=100,
551
+ seed_int=12,
552
+ baseline_type="mean",
553
+ baseline_group="all",
554
+ obs_col=None,
555
+ ):
556
+ """
557
+ Computes DeepLiftShap attributions for a trained Varix model .
558
+
559
+ Parameters
560
+ ----------
561
+ van : object
562
+ Object containing the trained Varix model and input data as an AnnData object.
563
+
564
+ method : str, {'DeepLiftShap', 'IntegratedGradients'}, default='DeepLiftShap'
565
+ post-hoc feature importance assessment method
566
+ - 'DeepLiftShap': method from pytorch Captum library, approximates SHAP values using Deeplift
567
+ - 'IntegratedGradients': method from pytorch Captum library, attribution via Integrated gradients
568
+
569
+ n_subset : int, default=100
570
+ Subset of randomly selected cells to compute attributions on.
571
+
572
+ seed_int : int, default=12
573
+ Seed for reproducible random sampling (NumPy & PyTorch).
574
+
575
+ baseline_type : str, {'mean', 'random_sample'}, default='mean'
576
+ How to generate the baseline:
577
+ - 'mean': average expression of the group
578
+ - 'random_sample': a randomly picked cell from the group
579
+
580
+ baseline_group : str, default='all'
581
+ Which group of cells to use as the baseline.
582
+ Use 'all' or a specific group label from `adata.obs[obs_col]`.
583
+
584
+ obs_col : str or None, default=None
585
+ Column in `adata.obs` that defines groups. Required if `baseline_group` is not 'all'.
586
+
587
+ Returns
588
+ -------
589
+ df_attributions : pandas.DataFrame
590
+ Gene-level attribution scores per latent dimension.
591
+ """
592
+ if baseline_group != "all" and obs_col is None:
593
+ raise ValueError(
594
+ "obs_col must be provided when using a group-specific baseline."
595
+ )
596
+ np.random.seed(seed_int)
597
+ torch.manual_seed(seed_int)
598
+ model = van.result.model
599
+
600
+ input_adata = van.raw_user_data["multi_sc"]["multi_sc"].mod["user-data"]
601
+ inputs = torch.tensor(
602
+ input_adata.X.toarray()
603
+ if scipy.sparse.issparse(input_adata.X)
604
+ else input_adata.X
605
+ )
606
+ if baseline_group == "all":
607
+ if baseline_type == "mean":
608
+ baseline_mean = inputs.mean(axis=0) # gene_means
609
+ baselines = torch.tensor(np.tile(baseline_mean, (inputs.shape[0], 1)))
610
+ if baseline_type == "random_sample":
611
+ baseline_random = inputs[torch.randint(0, inputs.size(0), (1,)).item()]
612
+ baselines = torch.tensor(np.tile(baseline_random, (inputs.shape[0], 1)))
613
+ else:
614
+ input_adata_filtered = input_adata[input_adata.obs[obs_col] == baseline_group]
615
+ inputs_filtered = torch.tensor(
616
+ input_adata_filtered.X.toarray()
617
+ if scipy.sparse.issparse(input_adata_filtered.X)
618
+ else input_adata_filtered.X
619
+ )
620
+ if baseline_type == "mean":
621
+ baseline_mean = inputs_filtered.mean(axis=0) # gene_means
622
+ baselines = torch.tensor(np.tile(baseline_mean, (inputs.shape[0], 1)))
623
+ if baseline_type == "random_sample":
624
+ baseline_random = inputs_filtered[
625
+ torch.randint(0, inputs_filtered.size(0), (1,)).item()
626
+ ]
627
+ baselines = torch.tensor(np.tile(baseline_random, (inputs.shape[0], 1)))
628
+ gene_names = input_adata.var_names
629
+ cell_IDs = input_adata.obs_names
630
+
631
+ latent_dimensions = list(range(0, van.result.adata_latent.shape[1]))
632
+ indices_DeepLiftShap = np.random.choice(
633
+ inputs.shape[0], size=n_subset, replace=False
634
+ )
635
+ all_attr = []
636
+ for latent_dim in latent_dimensions:
637
+ if method == "DeepLiftShap":
638
+ avg_abs_attributions, convergence = make_DeepLiftShap_Varix_dim(
639
+ model=model,
640
+ inputs=inputs[indices_DeepLiftShap].float(),
641
+ baselines=baselines[indices_DeepLiftShap].float(),
642
+ latent_dimension=latent_dim,
643
+ )
644
+ if method == "IntegratedGradients":
645
+ avg_abs_attributions, convergence = make_IntegratedGradients_Varix_dim(
646
+ model=model,
647
+ inputs=inputs[indices_DeepLiftShap].float(),
648
+ baselines=baselines[indices_DeepLiftShap].float(),
649
+ latent_dimension=latent_dim,
650
+ )
651
+
652
+ all_attr.append(avg_abs_attributions.detach().cpu())
653
+ attr_matrix = torch.stack(all_attr).T.numpy()
654
+
655
+ df_attributions = pd.DataFrame(
656
+ attr_matrix,
657
+ index=list(gene_names),
658
+ columns=[f"latent_dimension_{i}" for i in latent_dimensions],
659
+ )
660
+ return df_attributions
661
+
662
+
663
+ def do_feature_importance_Varix(
664
+ van,
665
+ method="DeepLiftShap",
666
+ baseline_type="mean",
667
+ baseline_group="all",
668
+ obs_col=None,
669
+ n_subset=100,
670
+ seed_int=12,
671
+ do_visualizations=True,
672
+ top_n_genes_heatmap=50,
673
+ top_n_foreground_pathways=30,
674
+ gene_set_library=None,
675
+ organism="Human",
676
+ n_top_pathways=10,
677
+ save_out_path=None,
678
+ do_miraculix_vis=False,
679
+ ):
680
+ """
681
+ Computes DeepLiftShap attributions for a trained Varix model and visulaization.
682
+
683
+ Parameters
684
+ ----------
685
+ van : object
686
+ Object containing the trained Varix model and input data as an AnnData object.
687
+
688
+ method : str, {'DeepLiftShap', 'IntegratedGradients'}, default='DeepLiftShap'
689
+ post-hoc feature importance assessment method
690
+ - 'DeepLiftShap': method from pytorch Captum library, approximates SHAP values using Deeplift
691
+ - 'IntegratedGradients': method from pytorch Captum library, attribution via Integrated gradients
692
+
693
+ n_subset : int, default=100
694
+ Subset of randomly selected cells to compute attributions on.
695
+
696
+ seed_int : int, default=12
697
+ Seed for reproducible random sampling (NumPy & PyTorch).
698
+
699
+ baseline_type : str, {'mean', 'random_sample'}, default='mean'
700
+ How to generate the baseline:
701
+ - 'mean': average expression of the group
702
+ - 'random_sample': a randomly picked cell from the group
703
+
704
+ baseline_group : str, default='all'
705
+ Which group of cells to use as the baseline.
706
+ Use 'all' or a specific group label from `adata.obs[obs_col]`.
707
+
708
+ obs_col : str or None, default=None
709
+ Column in `adata.obs` that defines groups. Required if `baseline_group` is not 'all'.
710
+
711
+ top_n_genes_heatmap : int, default=50
712
+ Number of top genes (with highest attribution scores) per latent dimension to visualize in the heatmap.
713
+
714
+ top_n_foreground_pathways : int, default=30
715
+ Number of top genes to include as "foreground" in enrichment analysis.
716
+
717
+ gene_set_library : str, default=None,
718
+ The gene set library to use for enrichment analysis (from Enrichr), e.g. "GO_Biological_Process_2021".
719
+
720
+ organism : str, default='Human'
721
+ The organism relevant to the gene sets used in enrichment.
722
+
723
+ n_top_pathways : int, default=10
724
+ Number of top enriched pathways to visualize in the results per latent dimension.
725
+
726
+ save_out_path : str or None, default=None
727
+ File path to save the output results figures.
728
+ If None, results will not be saved to disk.
729
+
730
+ do_miraculix_vis : bool, default=True
731
+ Show Miraculix-style GIF.
732
+
733
+ Returns
734
+ -------
735
+ df_attributions : pandas.DataFrame
736
+ Gene-level attribution scores per latent dimension.
737
+
738
+ """
739
+ feature_importance_methods = {"DeepLiftShap", "IntegratedGradients"}
740
+ if method not in feature_importance_methods:
741
+ raise ValueError(
742
+ f"Invalid method '{method}'. Must be one of: {', '.join(feature_importance_methods)}."
743
+ )
744
+
745
+ # baseline_type
746
+ if do_miraculix_vis:
747
+ do_miraculix_visualization()
748
+ df_attributions = make_feature_importance_Varix(
749
+ van,
750
+ method=method,
751
+ n_subset=n_subset,
752
+ seed_int=seed_int,
753
+ baseline_type=baseline_type,
754
+ baseline_group=baseline_group,
755
+ obs_col=obs_col,
756
+ )
757
+ if save_out_path is not None:
758
+ save_path = os.path.join(save_out_path, "df_attributions.csv")
759
+ df_attributions.to_csv(save_path)
760
+
761
+ """
762
+ if not do_visualizations:
763
+ display(HTML('<p style="font-size:20px;">Feature importance completed!</p>'))
764
+ """
765
+
766
+ # top genes plot
767
+ if do_visualizations:
768
+ if save_out_path is not None:
769
+ save_path = os.path.join(save_out_path, "top_attributions.pdf")
770
+ plot_union_top_genes_heatmap(
771
+ df=df_attributions,
772
+ top_n=top_n_genes_heatmap,
773
+ cmap="plasma",
774
+ save=save_path,
775
+ )
776
+ else:
777
+ plot_union_top_genes_heatmap(
778
+ df=df_attributions, top_n=top_n_genes_heatmap, cmap="plasma", save=None
779
+ )
780
+
781
+ if gene_set_library is not None:
782
+ dict_top_genes = get_top_genes_per_dimension(
783
+ df=df_attributions, top_n=top_n_foreground_pathways
784
+ )
785
+ PE_dict = run_go_enrichment(
786
+ top_genes_dict=dict_top_genes,
787
+ n_top_pathways=n_top_pathways,
788
+ gene_set_library=gene_set_library,
789
+ organism=organism,
790
+ )
791
+
792
+ if save_out_path is not None:
793
+ base_save_identifier = os.path.join(save_out_path, "GO_pathways")
794
+ plot_GO_log_odds_all(
795
+ PE_dict=PE_dict,
796
+ top_n=n_top_pathways,
797
+ base_save_identifier=base_save_identifier,
798
+ )
799
+ else:
800
+ plot_GO_log_odds_all(
801
+ PE_dict=PE_dict, top_n=n_top_pathways, base_save_identifier=None
802
+ )
803
+ return df_attributions
804
+
805
+
806
+ def make_IntegratedGradients_Varix_dim(model, inputs, baselines, latent_dimension):
807
+ model_encoder_dim = Varix_EncoderSingleDim(model, dim=latent_dimension)
808
+ integrated_gradients = IntegratedGradients(model_encoder_dim)
809
+ attributions, convergence = integrated_gradients.attribute(
810
+ inputs=inputs, baselines=baselines, return_convergence_delta=True
811
+ )
812
+ avg_abs_attributions = attributions.abs().mean(dim=0)
813
+ return avg_abs_attributions, convergence
814
+
815
+
816
+ def make_IntegratedGradients_Vanillix_dim(model, inputs, baselines, latent_dimension):
817
+ model_encoder_dim = Vanillix_EncoderSingleDim(model, dim=latent_dimension)
818
+ integrated_gradients = IntegratedGradients(model_encoder_dim)
819
+ attributions, convergence = integrated_gradients.attribute(
820
+ inputs=inputs, baselines=baselines, return_convergence_delta=True
821
+ )
822
+ avg_abs_attributions = attributions.abs().mean(dim=0)
823
+ return avg_abs_attributions, convergence