v0.1.5

IsoGraph v0.1.5 — Residualization Safety and Stability Improvements

IsoGraph v0.1.5 corrects how residualized data are retained by the VAE backend, preventing covariates from being removed twice in downstream analyses. The release also adds residualization quality-control metrics and clearer warnings when requested covariates cannot be used.

Changed

• Residualization is now a discovery-only setting for the vae backend. VAE embedding and Leiden clustering continue to use the residualized matrix, so module discovery is unchanged for a fixed covariate set. However, FitArtifacts.feature_scores now retains the raw, pre-residualization values from switch_matrix_raw.

  Previously, feature_scores contained residualized values. Downstream models that adjusted for the same covariates could therefore remove those effects a second time.

  Module eigengenes and traits.parquet are now calculated from the raw feature values. The built-in trait test is not covariate-adjusted; covariates should be applied once in the user’s downstream association model.

  The baseline, graph, latent, and wgcna backends are unchanged and continue to retain the residualized matrix.

Added

• Residualization quality control through FitArtifacts.residualization_qc. For each feature, the VAE backend now reports:

  • var_before
  • var_after
  • var_retained_frac
  • confound_r2_before
  • confound_r2_after

  These metrics are joined to the available feature identifiers. A successful residualization should reduce confound_r2_after toward zero, while var_retained_frac indicates how much feature variance was preserved.

  The table is generated by residualization_qc() in features/residualize.py whenever at least one usable covariate is resolved. It is available through the Python API but is not currently written to disk by isograph fit.

Fixed

• Improved validation of residualization covariates. build_design_matrix now emits a RuntimeWarning when an entry in residualize_covariates:

  • is missing from the sample table;
  • contains a constant numeric value; or
  • is a categorical variable with only one observed level.

  Constant and single-level covariates are excluded from the design matrix rather than silently producing no adjustment or introducing rank-deficient columns.

• Improved VAE stability, Leiden determinism, feature estimability, and loading calculations.

• Fixed Leiden giant-component capping and collapse behavior.

• Improved promotion of estimability from single latent representations.

• Fixed trait-analysis KeyError and sign-stability issues.

• Cleaned up fit.yaml and corrected the package __version__ mismatch.

• Synchronized the documentation and Read the Docs content with the current release.

Pull Requests

• [#15](#15) VAE stability, Leiden determinism, and estimability/loading features
• [#16](#16) Fix Leiden collapse and giant-component cap behavior
• [#17](#17) Promote single-representation estimability
• [#18](#18) Fix trait KeyError and sign stability
• [#19](#19) Clean up fit.yaml and fix __version__ mismatch
• [#20](#20) Synchronize documentation and Read the Docs

Full Changelog: v0.1.4...v0.1.5