Sketch: Plot Diagnostics (`plot_diagnostics.py`)

Purpose: predictive-fit and posterior-visualisation utilities used by the V2 workflow.

Import

Preferred:

from sketch.plot_diagnostics import (
    plot_posterior_predictions,
    plot_model_structure,
    plot_model_trace,
    plot_posterior_distributions,
)

Compatibility:

from src.sketch.plot_diagnostics import (
    plot_posterior_predictions,
    plot_model_structure,
    plot_model_trace,
    plot_posterior_distributions,
)

Functions and Outputs

plot_posterior_predictions(...)

Creates observed-versus-predicted time-series diagnostics and fit metrics.

Outputs:

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

plot_model_structure(model)

Returns a Graphviz model graph object when Graphviz is available.

Output:

• No file is saved by this function directly.

plot_model_trace(model, results_dir)

Plots MCMC traces for core parameters.

Output:

• 20_model_fit/model_trace.png

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

Plots posterior marginals from idata.posterior.

Output:

• 40_decomposition/{filename}

V2 Diagnostic Plot Split

The following diagnostics are produced by s../../diagnostics/ modules rather than sketch.plot_diagnostics:

• Convergence: rank_trace.png, energy_diagnostic.png
• Calibration: calibration_pit_histogram.png, calibration_pit_ecdf.png, calibration_coverage.png
• Pareto-k: pareto_k.png
• Structural diagnostics: pair_plot.png, residuals_vs_{channel}.png
• Prior/posterior and forest plots: prior_posterior_comparison.png, posterior_forest.png, posterior_forest_all_params.png
• Posterior predictive density overlay: posterior_predictive_check.png

See Diagnostics reference.

Caveat

These plots support computational and predictive assessment; they do not, on their own, establish causal validity.