Guide: Interpreting Model Results

This guide explains how to read AMMM V2 outputs by stage, and in what order to trust them.

What This Guide Covers

• Which files matter most in each stage folder
• Convergence, calibration, and Pareto checks
• Decomposition and optimisation interpretation caveats

1. Start With Diagnostic Gating

Before interpreting channel insights, inspect 50_diagnostics/:

• convergence_report.json (converged)
• calibration_report.json (well_calibrated)
• pareto_k_summary.json (ok)

Thresholds used in current diagnostics:

• R-hat warn at > 1.01, fail at > 1.05
• ESS threshold >= 100 × n_chains (bulk and tail)
• Divergences warn at 1+, fail at 10+
• Pareto k marginal (0.5, 0.7], poor > 0.7

If diagnostics_gating: strict and convergence fails, the workflow can halt before downstream stages.

2. Model Fit and Assessment

20_model_fit/

• model.nc: posterior and related groups in InferenceData
• model_summary.csv: posterior summaries (including R-hat and ESS)
• model_trace.png: trace diagnostics
• posterior_forest.png, posterior_forest_all_params.png
• prior_posterior_comparison.png

30_model_assessment/

• model_fit_predictions.png: actuals vs posterior predictions
• model_fit_metrics.csv: fit metrics
• posterior_predictive_check.png: distribution-level PPC

Interpretation:

• Look for systematic bias in fit residuals.
• Check uncertainty width, not just point fit.

3. Decomposition and Response Curves

40_decomposition/

Key files:

• all_decomp.csv
• waterfall_plot_components_decomposition.png
• media_contribution_mean.png, media_contribution_median.png
• media_contribution_per_spend.csv
• media_cost_per_revenue_unit.csv

60_response_curves/

Key files:

• response_curves.png
• all_response_curves.csv
• response_curve_fit_combined.csv

Interpretation:

• Use HDI ranges (94% default) rather than single-point claims.
• Treat contribution/ROI rankings as posterior distributions, not fixed truths.

4. Optimisation Outputs

70_optimisation/

• optimization_results.csv
• budget_optimisation.png
• budget_scenario_results.csv
• scenario comparison plots
• multiperiod_optimization_results.csv and related multi-period plots

Interpretation:

• Optimisation quality depends on model adequacy and calibration.
• Compare recommended allocations to operational constraints before actioning.

5. Interpretation and Reporting

80_interpretation/

• ammm_report.md
• business_report.md
• agentic_report.md (when enabled)
• llm_interpretations.json

Use reports as summaries of artefacts, not as replacements for diagnostics.

6. Practical Review Checklist

1. 10_pre_diagnostics/: stationarity/VIF/prior predictive.
2. 50_diagnostics/: convergence, calibration, Pareto k.
3. 30_model_assessment/: fit and PPC.
4. 40_decomposition/ and 60_response_curves/: channel interpretation.
5. 70_optimisation/: planning outputs.

Important caveat:

• Diagnostic adequacy improves reliability, but does not prove causal validity.