Abacus Sketch: Plot Diagnostics (`plot_diagnostics.py`)¶

This module provides functions for generating diagnostic plots to evaluate the fitted Abacus Marketing Mix Model (MMM). These plots help assess model fit, convergence of the sampling algorithm, and the model’s predictive capabilities.

Functions

plot_posterior_predictions

def plot_posterior_predictions(
    X: pd.DataFrame,
    y: pd.Series,
    X_test: pd.DataFrame,
    y_test: pd.Series,
    mmm, # Fitted MMM instance
    config: dict,
    output_dir: str,
    n_points: int = 52
) -> None:

Plots the model’s posterior predictions against actual observed values for both in-sample and (if available) out-of-sample data.

This function generates a time series plot showing:

Actual observed target values (points).
Median posterior prediction (dashed line).
95% Highest Density Interval (HDI) of the posterior predictions (shaded area).

It plots the last n_points of the in-sample data and all available out-of-sample data. It also calculates and includes the R-squared values for both in-sample and out-of-sample predictions in the plot title.

Parameters:

X (pd.DataFrame): Full feature DataFrame (including date column).
y (pd.Series): Full target variable Series.
X_test (pd.DataFrame): Feature DataFrame for the test/out-of-sample period. Can be empty.
y_test (pd.Series): Target variable Series for the test/out-of-sample period. Can be empty.
mmm: The fitted Abacus MMM instance. Must have a sample_posterior_predictive method.
config (dict): Configuration dictionary (used for date and target column names).
output_dir (str): Directory where the plot (model_fit_predictions.png) will be saved.
n_points (int, optional): Number of recent in-sample data points to include in the plot. Defaults to 52.

Returns:

None: Saves the plot to the specified directory.

Raises:

AttributeError: If mmm lacks the sample_posterior_predictive method.
ValueError: If date columns are missing or have incorrect types.

plot_model_structure

def plot_model_structure(model) -> Optional['graphviz.Digraph']:

Generates a visual representation of the PyMC model structure using Graphviz.

Requires the graphviz library and its backend (e.g., the Graphviz executables) to be installed.

Parameters:

model: The fitted Abacus MMM instance containing the PyMC model object (expected at model.model).

Returns:

graphviz.Digraph or None: The Graphviz object representing the model graph if successful, otherwise None (e.g., if Graphviz is not installed).

plot_model_trace

def plot_model_trace(model, results_dir: str) -> None:

Generates trace plots for key model parameters using ArviZ’s plot_trace.

Trace plots show the time series of samples for each parameter across all chains (left column) and the corresponding posterior density estimate (right column). They are essential for diagnosing MCMC convergence issues.

Parameters:

model: The fitted Abacus MMM instance containing the idata (InferenceData) attribute with posterior samples.
results_dir (str): Directory where the plot (model_trace.png) will be saved.

Returns:

None: Saves the plot to the specified directory.

Raises:

AttributeError: If model does not have an idata attribute.
ValueError: If model.idata is None or lacks posterior samples.

plot_posterior_distributions

def plot_posterior_distributions(
    idata: az.InferenceData,
    results_dir: str,
    filename: str = 'posterior_distributions.png'
) -> None:

Plots the marginal posterior distributions for all parameters found in the posterior group of the InferenceData object.

Uses ArviZ’s plot_posterior function to create histograms or kernel density estimates for each parameter.

Parameters:

idata (az.InferenceData): The InferenceData object containing the posterior samples.
results_dir (str): Directory where the plot will be saved.
filename (str, optional): Name for the output PNG file. Defaults to 'posterior_distributions.png'.

Returns:

None: Saves the plot to the specified directory.

Abacus Sketch: Plot Diagnostics (plot_diagnostics.py)¶

Abacus Sketch: Plot Diagnostics (`plot_diagnostics.py`)¶