Abacus Sketch: Plot Results (plot_results.py)

This module provides functions for visualising key results derived from a fitted Abacus Marketing Mix Model (MMM), such as contribution breakdowns, Return on Investment (ROI), and component decomposition.

Functions

all_contributions_plot

def all_contributions_plot(model, config: dict, results_dir: str) -> None:

Generates a stacked area plot showing the mean contributions of media channels and the combined baseline components (intercept + extra features) over time.

Parameters:

  • model: A fitted Abacus MMM instance with compute_mean_contributions_over_time and compute_channel_contribution_original_scale methods.

  • config (dict): Configuration dictionary used to identify date column and extra feature columns for baseline calculation.

  • results_dir (str): Directory where the plot (weekly_media_and_baseline_contribution.png) will be saved.

Returns:

  • None: Saves the plot to the specified directory.

Raises:

  • AttributeError: If model is missing required contribution methods.

  • ValueError: If the date column or required baseline component columns are not found in the contribution data.

plot_channel_contributions

def plot_channel_contributions(model, config: dict, results_dir: str) -> None:

Generates a stacked area plot showing the mean contributions of only the media channels over time.

Parameters:

  • model: A fitted Abacus MMM instance with the compute_channel_contribution_original_scale method.

  • config (dict): Configuration dictionary (used to get the date column name).

  • results_dir (str): Directory where the plot (weekly_media_contribution.png) will be saved.

Returns:

  • None: Saves the plot to the specified directory.

Raises:

  • AttributeError: If model is missing the required contribution method.

  • ValueError: If the date column is not found in the contribution data.

plot_roi

def plot_roi(model, data: pd.DataFrame, config: dict, results_dir: str) -> None:

Generates two bar plots showing the mean and median Return on Investment (ROI) for each media channel.

ROI is calculated based on the model’s estimated channel contributions and the historical spend data.

Parameters:

  • model: A fitted Abacus MMM instance with the compute_channel_contribution_original_scale method.

  • data (pd.DataFrame): DataFrame containing historical spend data for the channels specified in config.

  • config (dict): Configuration dictionary specifying media channel spend columns.

  • results_dir (str): Directory where the plots (media_roi_mean.png, media_roi_median.png) will be saved.

Returns:

  • None: Saves the plots to the specified directory.

Raises:

  • AttributeError: If model is missing the required contribution method.

  • ValueError: If required spend columns are missing from data.

plot_roi_distribution

def plot_roi_distribution(model, data: pd.DataFrame, config: dict, results_dir: str) -> None:

Generates histograms with Kernel Density Estimate (KDE) overlays showing the posterior distribution of Return on Investment (ROI) for each media channel.

This provides a more detailed view of the uncertainty around the ROI estimates compared to just plotting the mean or median.

Parameters:

  • model: A fitted Abacus MMM instance with the compute_channel_contribution_original_scale method.

  • data (pd.DataFrame): DataFrame containing historical spend data for the channels specified in config.

  • config (dict): Configuration dictionary specifying media channel spend columns.

  • results_dir (str): Directory where the plot (roi_distribution.png) will be saved.

Returns:

  • None: Saves the plot to the specified directory.

Raises:

  • AttributeError: If model is missing the required contribution method.

  • ValueError: If required spend columns are missing from data.

plot_waterfall_components_decomposition

def plot_waterfall_components_decomposition(
    model=None, original_scale: bool = True, figsize: tuple = (14, 7), **kwargs
) -> plt.Figure:

Creates a waterfall chart visualising the decomposition of the total predicted response into contributions from each model component (baseline features, media channels).

The chart shows how each component adds or subtracts from the cumulative total, starting from zero. Bars are coloured based on positive or negative contribution, and annotated with the absolute contribution value and percentage share.

Parameters:

  • model: A fitted Abacus MMM instance with the compute_mean_contributions_over_time method. Defaults to None, but will raise an error if not provided.

  • original_scale (bool, optional): If True (default), plots contributions in the original target variable’s scale.

  • figsize (tuple, optional): Figure size. Defaults to (14, 7).

  • **kwargs: Additional keyword arguments passed to matplotlib.pyplot.subplots.

Returns:

  • plt.Figure: The matplotlib Figure object containing the waterfall plot.

Raises:

  • ValueError: If model is None or has not been fitted.

  • AttributeError: If model is missing the compute_mean_contributions_over_time method.

(Private helper function _process_decomposition_components is used internally by plot_waterfall_components_decomposition to aggregate contributions by component and calculate percentages.)