Abacus Core Mixins: MMM Analysis (`mmm_analysis.py`)¶

This module provides the MMMAnalysisMixin class, designed to be inherited by Marketing Mix Model (MMM) classes in Abacus. It offers methods for analysing the relationship between channel spend and contribution, and for visualising the expected impact of hypothetical spend scenarios over time.

MMMAnalysisMixin Class

This mixin assumes the inheriting class provides several attributes and methods, including:

X: The original input DataFrame.
channel_columns: List of channel names.
date_column: Name of the date column in X.
preprocessed_data: A dictionary containing the preprocessed data used for fitting (e.g., preprocessed_data['X']).
target_transformer: The scaler used for the target variable (if applicable).
channel_contributions_forward_pass(channel_data): A method (likely from another mixin or the base class) that calculates channel contributions for given channel input data, returning results in the original target scale.
new_spend_contributions(spend, one_time, ...): A method (likely from MMMPredictMixin) that calculates the contribution trajectory resulting from a new spend scenario.

Methods

get_channel_contributions_forward_pass_grid

def get_channel_contributions_forward_pass_grid(
    self, start: float, stop: float, num: int
) -> DataArray:

Generates channel contributions across a grid of relative spend multipliers applied to the preprocessed channel data.

This method simulates varying levels of spend by multiplying the preprocessed channel input data by factors ranging from start to stop. For each factor (delta), it calculates the resulting channel contributions using the model’s channel_contributions_forward_pass method. The results are returned in the original target variable’s scale.

Parameters:

start (float): The starting multiplier for the spend grid (e.g., 0.0 for zero spend). Must be >= 0.
stop (float): The ending multiplier for the spend grid (e.g., 2.0 for double spend). Must be > start.
num (int): The number of points (spend levels) to calculate within the grid.

Returns:

xr.DataArray: An xarray DataArray containing the channel contributions. Dimensions are (delta, chain, draw, date, channel), where delta corresponds to the spend multipliers in the grid. Values are in the original target scale.

Raises:

ValueError: If start < 0.
RuntimeError: If the model hasn’t been fitted, preprocessed_data is missing, or the required channel_contributions_forward_pass method is not found.

plot_channel_contributions_grid

def plot_channel_contributions_grid(
    self,
    start: float,
    stop: float,
    num: int,
    absolute_xrange: bool = False,
    **plt_kwargs: Any,
) -> plt.Figure:

Plots the total channel contribution (summed over time) against varying spend levels, based on the grid generated by get_channel_contributions_forward_pass_grid.

This visualisation helps understand the response curve for each channel. It shows the mean contribution and a 95% Highest Density Interval (HDI) across the posterior samples. The x-axis can represent either the relative spend multiplier (delta) or the absolute total spend.

Parameters:

start (float): Start multiplier for the spend grid (passed to get_channel_contributions_forward_pass_grid). Must be >= 0.
stop (float): End multiplier for the spend grid (passed to get_channel_contributions_forward_pass_grid). Must be > start.
num (int): Number of points in the grid (passed to get_channel_contributions_forward_pass_grid).
absolute_xrange (bool, optional): If True, the x-axis shows the absolute total spend (calculated as delta * sum of original spend for the channel). If False (default), the x-axis shows the relative spend multiplier delta.
**plt_kwargs: Additional keyword arguments passed to matplotlib.pyplot.subplots.

Returns:

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

Raises:

RuntimeError: If the model hasn’t been fitted or the original input data X is missing (required for calculating absolute spend).

plot_new_spend_contributions

def plot_new_spend_contributions(
    self,
    spend_amount: float,
    one_time: bool = True,
    lower: float = 0.025,
    upper: float = 0.975,
    ylabel: str = "Contribution",
    idx: Optional[slice] = None,
    channels: Optional[List[str]] = None,
    prior: bool = False,
    original_scale: bool = True,
    ax: Optional[plt.Axes] = None,
    **sample_posterior_predictive_kwargs: Any,
) -> plt.Axes:

Plots the expected contribution trajectory over time for selected channels resulting from a specific hypothetical spend scenario.

This method simulates applying a spend_amount to the specified channels (either as a one-time pulse or continuous spend) and plots the resulting mean contribution and a credible interval (defined by lower and upper quantiles) over time since the spend occurred. It relies on the new_spend_contributions method (expected from MMMPredictMixin).

Parameters:

spend_amount (float): The amount of spend to simulate for each selected channel.
one_time (bool, optional): If True (default), the spend is applied only at the first time step. If False, the spend is applied continuously.
lower (float, optional): The lower quantile for the credible interval (default: 0.025).
upper (float, optional): The upper quantile for the credible interval (default: 0.975).
ylabel (str, optional): Label for the y-axis (default: “Contribution”).
idx (slice, optional): A time slice (relative to the spend start time, t=0) to display on the plot. Defaults to showing all time points from t=0 onwards.
channels (Optional[List[str]], optional): A list of channel names to include in the plot. If None (default), all channels in self.channel_columns are plotted.
prior (bool, optional): If True, uses samples from the prior predictive distribution. If False (default), uses samples from the posterior predictive distribution.
original_scale (bool, optional): If True (default), plots contributions in the original target variable’s scale.
ax (Optional[plt.Axes], optional): A matplotlib Axes object to plot on. If None, new axes are created.
**sample_posterior_predictive_kwargs: Additional keyword arguments passed to the underlying sampling method (e.g., sample_posterior_predictive).

Returns:

plt.Axes: The matplotlib Axes object containing the plot.

Raises:

ValueError: If lower or upper are invalid quantiles, lower > upper, or if a specified channel is not found in self.channel_columns.
RuntimeError: If the required new_spend_contributions method is not found in the class.

Abacus Core Mixins: MMM Analysis (mmm_analysis.py)¶

Abacus Core Mixins: MMM Analysis (`mmm_analysis.py`)¶