Abacus Core: Decomposition (_decomp.py)

This module provides functions for decomposing the model’s predictions into baseline components (intercept, trend, seasonality, etc.) and media contributions after model fitting. It helps in understanding the drivers of the target variable.

Functions

get_baseline_breakdown_df

def get_baseline_breakdown_df(
    media_mix_model: abacusMMM,
    input_data: InputData,
    data_to_fit: DataToFit,
    degrees_seasonality: int | None,
) -> pd.DataFrame:

Break down the baseline into its component pieces for the training period and return a DataFrame with the results.

This function calculates the contribution of each baseline component (intercept, trend, seasonality, weekday effect for daily data, and extra features) using the median values of the corresponding parameters from the model trace.

Parameters:

• media_mix_model (abacusMMM): An instance of the fitted Abacus MMM model.

• input_data (InputData): An instance containing the original input data configuration.

• data_to_fit (DataToFit): An instance containing the prepared data used for fitting the model (scaled features, target, etc.).

• degrees_seasonality (int | None): The number of degrees used for the seasonality component during model fitting.

Returns:

• pd.DataFrame: A DataFrame indexed by date, containing columns for each baseline component’s contribution (inverse-transformed back to the original target scale). It includes:

  • intercept: Contribution of the model intercept.

  • trend: Contribution of the trend component.

  • seasonality: Contribution of the seasonality component.

  • weekday (optional): Contribution of the day-of-week effect (if time_granularity is daily).

  • Columns for each extra feature specified in data_to_fit.extra_features_names.

  • sum_of_medians: The row-wise sum of the median-based component contributions calculated by this function.

  • chart_baseline_value: The baseline contribution calculated by create_media_baseline_contribution_df (from abacus.core.decomp), included for comparison as it uses the full parameter distributions.

Notes:

• The baseline breakdown calculated here uses the median of each parameter’s posterior distribution. This provides a point estimate but might differ from calculations considering the full distribution (like chart_baseline_value).

---

get_all_breakdown_df

def get_all_breakdown_df(
    media_mix_model: abacusMMM,
    input_data: InputData,
    data_to_fit: DataToFit,
    degrees_seasonality: int,
) -> pd.DataFrame:

Break down the baseline components and combine them with media contributions for the entire dataset (training and testing periods, if applicable).

Similar to get_baseline_breakdown_df, this function calculates baseline components using median parameter values. It then merges these with the media and baseline contributions derived from create_media_baseline_contribution_df (from abacus.core.decomp, which uses the full posterior distributions) to provide a comprehensive decomposition.

Parameters:

• media_mix_model (abacusMMM): An instance of the fitted Abacus MMM model.

• input_data (InputData): An instance containing the original input data configuration.

• data_to_fit (DataToFit): An instance containing the prepared data used for fitting the model (scaled features, target, etc.), potentially including test data.

• degrees_seasonality (int): The number of degrees used for the seasonality component during model fitting.

Returns:

• pd.DataFrame: A DataFrame indexed by date, covering the full time range (train + test). It contains columns for:

  • Baseline components calculated using median parameters (intercept, trend, seasonality, weekday (optional), extra features).

  • sum_of_medians: The row-wise sum of the median-based baseline component contributions.

  • Columns for each media channel’s contribution (e.g., channel_1 contribution).

  • baseline contribution: The baseline contribution calculated by create_media_baseline_contribution_df.

  • Other contribution columns potentially generated by create_media_baseline_contribution_df.

Notes:

• This function provides a more complete picture by including media contributions alongside the baseline breakdown for the entire dataset duration.

• It relies on create_media_baseline_contribution_df for the final media and baseline contribution values, which are generally preferred due to using full posterior distributions.

---

(Private helper functions _dump_baseline_breakdown and _dump_all_breakdown are used internally to save the generated DataFrames to baseline_breakdown.csv and all_decomp.csv respectively in the results directory.)