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:
  • idata (xr.DataTree-like) – Must have .posterior attribute containing the contribution variables.

  • var (list[str] | tuple[str, ...]) – Posterior variable names to include (e.g., contribution variables).

  • agg (str | Callable) – xarray reduction method applied over agg_dims for each variable. Can be “mean”, “median”, “sum”, or any callable reduction function.

  • agg_dims (list[str] | tuple[str, ...] | None) – Sampling dimensions to reduce over. If None, defaults to (“chain”, “draw”) but only includes dimensions that exist.

  • index_dims (list[str] | tuple[str, ...] | None) – Dimensions to preserve as index-like columns. If None, defaults to (“date”,) but only includes dimensions that exist.

  • expand_dims (list[str] | tuple[str, ...] | None) – 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_category (bool) – Whether to cast non-index regular dimensions to pandas ‘category’ dtype.

Return type:

pd.DataFrame

Returns:

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",
)