Plot Diagnostics (`sketch.plot_diagnostics`)

This module provides core predictive diagnostics and trace/distribution plots for sketch workflows.

Model type used by this module is DelayedSaturatedMMMv2 (core.mmm_model_v2).

Import style:

from sketch.plot_diagnostics import (
    plot_posterior_predictions,
    plot_model_trace,
    plot_posterior_distributions,
    plot_model_structure,
)
# Compatibility form in some environments:
# from src.sketch.plot_diagnostics import ...

plot_posterior_predictions(X, y, X_test, y_test, mmm, config, output_dir, n_points=52, show_oos_r2=False)

Plots actuals vs posterior predictive with HDI fans and residual panel.

Saved artefacts:

• model_fit_predictions.png → 30_model_assessment/
• model_fit_metrics.csv → 30_model_assessment/

plot_model_trace(model, results_dir)

Plots ArviZ traces for key posterior variables.

Saved artefact:

• model_trace.png → 20_model_fit/

plot_posterior_distributions(idata, results_dir, filename="posterior_distributions.png")

Plots posterior distributions for parameters in idata.posterior.

Saved artefact:

• posterior_distributions.png (or custom filename) → 40_decomposition/

Note: this helper still exists, but V2 workflow now also generates dedicated posterior diagnostics from src/diagnostics/ (for example forest and prior-posterior comparison plots).

plot_model_structure(model)

Returns a Graphviz model graph (pm.model_to_graphviz).

• No file is saved automatically.
• Persisting the rendered graph is caller-managed (for example with graph.render(...)).

V2 diagnostic plots now generated outside sketch.plot_diagnostics

In V2, many diagnostic plots are produced by src/diagnostics/ modules and saved directly to stage folders:

• Convergence (50_diagnostics/): rank_trace.png, energy_diagnostic.png → Convergence Diagnostics
• Calibration (50_diagnostics/): calibration_pit_histogram.png, calibration_pit_ecdf.png, calibration_coverage.png → Calibration Diagnostics
• Pareto-k (50_diagnostics/): pareto_k.png → Pareto-k Diagnostics
• Pair plot (50_diagnostics/): pair_plot.png → Structural Diagnostics
• Residual structure (50_diagnostics/): residuals_vs_{channel}.png → Structural Diagnostics
• Posterior forest (20_model_fit/): posterior_forest.png, posterior_forest_all_params.png → Posterior Plots
• Prior/posterior comparison (20_model_fit/): prior_posterior_comparison.png → Posterior Plots
• PPC density (30_model_assessment/): posterior_predictive_check.png → Posterior Plots
• Prior predictive (10_pre_diagnostics/): prior_predictive_check.png → Prior Predictive

Usage example

from sketch.plot_diagnostics import plot_posterior_predictions, plot_model_trace

plot_posterior_predictions(X, y, X_test, y_test, mmm, config, output_dir=results_dir)
plot_model_trace(mmm, results_dir)