habit.viz: publication overlays

Publication figures and image overlays for HABIT results.

This package is the home for HABIT visualization: habitat-core figures (overlays, partition triptych, auto-K curves, volume/MSI/ITH, label compare), graph / voxel-texture panels, greyscale intensity slices for image preprocessing (plot_intensity_slice()), habitat-clustering PCA, optional napari (view_habitat_napari()), plus ROC / survival / regression helpers. New drawing / viewing code should land here rather than in CLI or habit.api helpers.

Most functions in this package are PURE matplotlib helpers: they take contract objects (or plain arrays), draw on a Figure, and return that figure. Nothing here touches the filesystem – there is no savefig, no output- directory parameter. Where a figure ends up is entirely the caller’s decision. The optional napari helper is the one exception that may open a Qt window; it still takes arrays only and never reads or writes image files.

Two consequences of that rule:

• a figure’s geometry, typography and palette come from a STYLE PRESET (use_style()), never from a per-plot hard-coding, so one figure can be re-rendered for a different journal without touching the plotting code;

• every piece of text drawn on a figure is guaranteed ASCII via sanitize_label(), because data-driven labels (a feature or group name) can otherwise leak non-ASCII characters onto an axis that a journal will reject.

User guide: Habitat Guide Volume and fractions.

matplotlib is imported lazily inside each function, so importing habit never pulls a plotting backend. All figure labels are English-only.

Interactive overlay (needs napari): view_habitat_napari(). Static PNG: plot_habitat_overlay() (pass an ImageVolume so coronal/sagittal keep superior up).

Classes

StyleSpec

A named bundle of figure-geometry and typography choices.

Functions

Style helpers

use_style	Apply a preset's rcParams for the duration of the block.
get_style	Return the preset registered under name.
register_style	Register a custom preset, making it usable by name in use_style().
available_styles	Return the registered preset names, sorted.
sanitize_label	Return value as a printable ASCII string safe for a figure.

Habitat clustering and overlay

plot_habitat_clustering_pca_2d	Two-dimensional PCA scatter of habitat clustering units.
plot_habitat_clustering_pca_3d	Three-dimensional PCA scatter of habitat clustering units.
plot_habitat_clustering_pca_3d_interactive	Interactive 3D PCA scatter using plotly (optional dependency).
plot_habitat_overlay	Draw habitat labels as an opaque colour overlay on the source image.
plot_cluster_validation_curves	Plot auto-K / cluster-validation score curves (one panel per method).
plot_cluster_validation_from_report	Draw validation curves from a habitat-model selection_report.
plot_habitat_volume_fractions	Bar chart of per-habitat volume fractions (of non-background VOI).
plot_msi_matrix	Heatmap of a spatial interaction (MSI) matrix.
plot_ith_summary	One-panel bar chart: global ITH, then optional per-habitat ITH.
plot_habitat_label_compare	Side-by-side habitat overlays, optional disagreement mask.
plot_label_overlap_matrix	Heatmap of the voxel-overlap table of two label maps of the same voxels.
plot_prototype_matching	Habitat summaries of every subject, coloured by their shared prototype.
plot_partition_triptych	Two-step partition view: greyscale | supervoxel overlay | habitat overlay.
plot_precision_icc	Draw per-feature ICC points with 95% CI whiskers.
plot_habitat_feature_heatmap	Habitat x feature heatmap (cohort mean or one subject).
plot_habitat_feature_effect	Habitat-pair effect sizes (Cliff's delta or Cohen's d).
plot_habitat_feature_components	Habitat contrast on a few CVA or PCA component scores.
plot_habitat_feature_violin	Grouped violins (or box + strip when n is small) for a feature shortlist.
plot_habitat_feature_bars	One bar panel per feature (independent y-axis).
plot_habitat_graph_slice	Draw the colored habitat map at the largest cross-section (2D).
plot_habitat_graph_network_2d	Draw the intra/inter habitat graphs built from the 2D slice habitat map.
plot_graph_feature_heatmap	Draw a subject x graph-feature heatmap (not habitat x texture).
render_habitat_graph_surface_3d	Render a 3D surface view of the habitat volume (PyVista).
render_habitat_graph_network_3d	Render the 3D feature-aligned spatial graph on a dark scene (PyVista).
dense_voxel_feature_map	Scatter one VoxelFeatureField column into a dense volume.
plot_intensity_slice	Display a whole-FOV greyscale anatomy / intensity slice.
plot_voxel_texture_slice	Display a voxel-level texture / feature map as 2D publication panels.
view_habitat_napari	Open (or populate) a napari viewer with image layer(s) + habitat labels.

Ingestion and preprocessing diagrams

Teaching diagrams for the gallery: how data enters HABIT (directory tree, SimpleITK objects, NumPy arrays, NIfTI file pairs) and how clustering features are preprocessed. The right-hand panel is a real cropped data view.

plot_directory_ingest	Diagram for the directory-ingestion route: tree -> Subject with ROI.
plot_simpleitk_ingest	Diagram for the SimpleITK route: voxel-cube badge -> habitat overlay.
plot_numpy_ingest	Diagram for the array route: the data itself drawn as a colour matrix.
plot_nifti_ingest	Diagram for the file-pair route: image.nii.gz + mask.nii.gz.
plot_feature_preprocessing_chain	Diagram of the clustering-feature preprocessing chain.

Supporting plots (survival / classification / SHAP)

Bookmarks for table-ML figures. Not the habitat core.

plot_kaplan_meier	Kaplan-Meier curves, optionally stratified, with a numbers-at-risk table.
plot_risk_triptych	Three-panel risk-stratification figure.
plot_time_dependent_auc	Uno's cumulative/dynamic AUC as a function of follow-up time.
plot_survival_calibration	Calibration of the predicted horizon survival against Kaplan-Meier truth.
plot_brier_curve	Brier score of the predicted survival function across follow-up time.
plot_cox_forest	Forest plot of hazard ratios with 95% confidence intervals (log scale).
plot_predicted_vs_observed	Predicted-against-observed scatter with the identity line.
plot_residuals	Residuals against fitted values, to expose heteroscedasticity and bias.
plot_residual_qq	Quantile-quantile plot of the residuals against a normal reference.
plot_bland_altman	Bland-Altman limits-of-agreement plot.
plot_coefficient_forest	Forest-style plot of regression coefficients with optional CIs.
plot_roc	Receiver-operating-characteristic curve(s) with AUC in the legend.
plot_precision_recall	Precision-recall curve(s) with average precision in the legend.
plot_calibration	Reliability diagram (calibration curve) against the identity line.
plot_decision_curve	Decision-curve analysis with Treat-All / Treat-None references.
plot_confusion_matrix	Confusion-matrix heatmap for discrete class predictions.
plot_shap_summary	Beeswarm-style SHAP summary for one attribution matrix.
plot_shap_bar	Global mean-absolute SHAP bar chart (shap.plots.bar).
plot_shap_violin	Violin-style SHAP summary (summary_plot(plot_type='violin')).
plot_shap_heatmap	Instance x feature SHAP heatmap (shap.plots.heatmap).
plot_shap_dependence	SHAP dependence plot for one feature (pure; no filesystem).
plot_shap_waterfall	Per-sample SHAP waterfall explanation (pure; no filesystem).
plot_shap_decision	SHAP decision paths for a handful of samples.
plot_shap_force	Static matplotlib force plot for one sample.
plot_permutation_importance	Horizontal bar chart of permutation importances (pure; no filesystem).
rank_shap_feature_indices	Rank features by mean absolute SHAP attribution (descending).
select_representative_sample_indices	Pick sample indices spanning the score range (low / mid / high).
net_benefit	Decision-curve net benefit at one threshold probability.