build_contributions#

pymc_marketing.mmm.utils.build_contributions(idata, var, agg='mean', *, agg_dims=None, index_dims=None, expand_dims=None, cast_regular_to_category=True)[source]#

Build a wide contributions DataFrame from idata.posterior variables.

This function extracts contribution variables from the posterior, aggregates them across sampling dimensions, and returns a wide DataFrame with automatic dimension detection and handling.

Parameters:

idataaz.InferenceData-like: Must have .posterior attribute containing the contribution variables.
varlist or tuple of str: Posterior variable names to include (e.g., contribution variables).
aggstr or callable(), default “mean”: xarray reduction method applied over agg_dims for each variable. Can be “mean”, “median”, “sum”, or any callable reduction function.
agg_dimslist or tuple of str, optional: Sampling dimensions to reduce over. If None, defaults to (“chain”, “draw”) but only includes dimensions that exist.
index_dimslist or tuple of str, optional: Dimensions to preserve as index-like columns. If None, defaults to (“date”,) but only includes dimensions that exist.
expand_dimslist or tuple of str, optional: Dimensions whose coordinates should become separate wide columns. If None, defaults to (“channel”, “control”). Only one such dimension is expected per variable.
cast_regular_to_categorybool, default True: Whether to cast non-index regular dimensions to pandas ‘category’ dtype.

Returns:

pd.DataFrame: Wide DataFrame with columns for: - Index dimensions (e.g., date) - Regular dimensions (e.g., geo, product) - One column per label in each expand dimension (e.g., channel__C1, control__x1) - Single columns for scalar variables (e.g., intercept)

Raises:

ValueError: If none of the requested variables are present in idata.posterior.

Examples

Build contributions DataFrame with default settings:

df = build_contributions(
    idata=mmm.idata,
    var=[
        "intercept_contribution_original_scale",
        "channel_contribution_original_scale",
        "control_contribution_original_scale",
    ],
)

Use median aggregation instead of mean:

df = build_contributions(
    idata=mmm.idata,
    var=["channel_contribution"],
    agg="median",
)