Backend Reference

IsoGraph exposes five model backends, each selectable via backend=<name> in the benchmark config or as a Hydra override on the CLI.

Baseline

BaselineNetworkModel is the deterministic regression target. It computes gene-level switch coordinates, optionally residualizes covariates, estimates a sparse partial correlation network, and extracts modules as connected components.

Use it when you want:

  • the simplest reproducible backend

  • the current custom-data CLI path through isograph fit

  • a stable reference point for regression testing

Latent

LatentNetworkModel adds sklearn Factor Analysis denoising before partial-correlation network inference. Component count is selected by cross-validated log-likelihood (default) or fixed. Also records calibration metrics: held-out log-likelihood, reconstruction RMSE, mean noise variance, and convergence status.

Use it when you want:

  • a more noise-tolerant backend than the baseline

  • automatic or fixed latent-dimensionality control

  • stability selection for real data without ground-truth modules

Memory note: The latent backend constructs a full p×p covariance matrix internally. For datasets with >> features (roughly > 1 000 genes), this becomes memory-prohibitive. Use the VAE backend for large feature spaces.

Graph

GraphNetworkModel extends the latent backend with graph-Laplacian smoothing over a gene graph prior to Factor Analysis.

Use it when you want:

  • graph-aware regularization

  • diagnostics on graph structure and smoothing strength

  • a bridge between the latent and graph-prior formulations

VAE (default)

VaeNetworkModel is the default production backend and the most flexible option. It uses a variational autoencoder to learn a nonlinear low-dimensional representation of the feature matrix, then infers modules from Pearson correlations on the decoded signal. For multiplex runs, the feature matrix includes abundance and switch channels. Supports early stopping, posterior-collapse detection, latent-dimension grid search, and optional checkpoint saving.

Use it when you want:

  • the best out-of-the-box module recovery on realistic bulk RNA-seq fixtures

  • nonlinear latent representations

  • operation at 6 000–12 000 gene scale (25:1–50:1 genes-to-samples)

  • multi-channel multiplex discovery: abundance channel (all genes) + switch channel (multi-isoform genes); per-channel thresholds (alpha_switch, alpha_abundance) with auto-calibration via alpha_abundance_grid

  • checkpointed model state (vae_checkpoint.pt), required for VAE decoder attribution (--vae-attribution) and Captum Integrated Gradients (--integrated-gradients)

Requires PyTorch. Install a build appropriate for your CPU/GPU/CUDA stack before use. IsoGraph installs mpmath for modern SymPy compatibility, but it does not install PyTorch automatically.

WGCNA

WgcnaNetworkModel wraps R’s WGCNA::blockwiseModules for direct benchmark comparison. For datasets above 5 000 genes the runner uses blockwise mode automatically (avoids full O(n²) TOM matrix). Edge tables are populated only in non-blockwise mode. The subprocess timeout is configurable through WgcnaModelConfig.timeout_seconds.

Use it when you want:

  • a standard community comparison baseline

  • signed or unsigned weighted correlation network analysis

  • a baseline comparison for multiplex stress runs, where over-segmentation should be assessed alongside recovery

Requires R with the WGCNA package installed and Rscript on PATH. The backend calls R via subprocess — no Python R bridge is needed.

Important Notes

The benchmark and fit commands can both drive all five backends. VAE is the default for both. For fit with Hydra overrides, append -- followed by <backend>.<field>=<value> (e.g. -- vae.hidden_dim=256).

All backends support the multiplex edge-policy fields when multiplex channels are present: allow_abundance_abundance, alpha_switch, alpha_abundance, alpha_abundance_grid. The VAE backend supports vae_checkpoint.pt saving for decoder and encoder attribution. All backends populate module_gene_roles.parquet when multiplex channels are detected.