Skip to content

v0.1.3

Choose a tag to compare

View all tags
@KrotosBenjamin KrotosBenjamin released this 03 May 15:26
v0.1.3
dfc7d02

[0.1.3] — 2026-05-03

IsoGraph v0.1.3 adds a full module interpretation workflow for explaining isoform-switch networks after model fitting. This release introduces transcript-level driver tables, publication-ready explanation plots, GTF-based structural annotations, and VAE-based attribution methods. It also removes the experimental gpu_latent backend after benchmarking showed poor module recovery relative to regular latent implementation (CPU only).

Added

  • Module explanation CLI: added isograph explain-module to explain fitted modules at transcript-feature resolution. Outputs include gene_driver_table.parquet, transcript_polarity_table.parquet, high_vs_low_table.parquet, and a shared module_explanation_manifest.json. Python API: isograph.explain.explain_module.
  • Publication-ready explanation plots: added optional --plot support for top-driver barplots, transcript usage gradient plots, and positive/negative driver heatmaps. Output format is controlled with --output-format png|pdf.
  • Structural transcript-switch annotation: added isograph annotate-structure to annotate transcript switch pairs using GTF-derived structural labels, including first/last exon changes, CDS/UTR shifts, biotype switches, and shared exon fraction. Supports GENCODE and Ensembl GTF conventions, with optional GTF parse caching via --gtf-cache.
  • Annotation-aware explanations: isograph explain-module can now incorporate structural annotations via --annotation-table.
  • VAE decoder attribution: added --vae-attribution to compute finite-difference decoder Jacobian scores for high-confidence module drivers. Requires vae_checkpoint.pt in the artifact directory and writes vae_drivers.parquet per module.
  • Captum Integrated Gradients attribution: added --integrated-gradients for encoder-based attribution of module eigengene prediction to transcript features. Requires pip install isograph[torch-explain] and writes ig_attributions.parquet per module. Supports zero and mean baselines.

Changed

  • Expanded backend support in fit: isograph fit now supports --backend baseline|latent|graph|vae|wgcna, with VAE as the default backend in fit.yaml.
  • Improved CUDA handling: added device selection for VAE/GPU latent models and fixed VAE reparameterization on CUDA.
  • Clearer dependency guidance: added the mpmath dependency and clarified PyTorch installation instructions.
  • Latent backend warning: documentation now notes that the CPU latent backend forms a feature-by-feature covariance matrix and may become memory-prohibitive for large feature spaces; VAE is recommended for large datasets.

Removed

  • Removed gpu_latent backend: benchmarking showed substantially worse module recovery than the CPU latent backend (FA), with no runtime advantage and high GPU memory requirements. Use backend=vae instead for large datasets.

Pull Requests

  • #3 Add device selection to VaeNetworkModel and GpuLatentNetworkModel
  • #4 Add mpmath dependency and clarify PyTorch install
  • #5 Fix VAE reparameterization on CUDA
  • #6 Remove gpu_latent backend; add latent memory-scale warnings
  • #7 Add Stage 8A module explanation
  • #8 Add Stage 8B publication-ready module explanation plots
  • #9 Add Stage 8C GTF-based structural annotation
  • #10 Add Stage 8D VAE attribution
  • #11 Add Stage 8E Captum Integrated Gradients encoder attribution

Full Changelog: v0.1.2...v0.1.3

Assets 2
Loading