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
.posteriorattribute 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 overagg_dimsfor 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", )