MMM.compute_mean_contributions_over_time#

MMM.compute_mean_contributions_over_time(central_tendency='median')[source]#

Posterior-mean counterfactual contributions as a DataFrame.

Convenience wrapper around compute_counterfactual_contributions_dataset() that averages over (chain, draw) and returns a flat pd.DataFrame.

Each column answers a counterfactual question: “how much would the predicted \(\hat y(t)\) decrease if we removed this component?”

Formally, for component \(j\) with value \(v_j(t)\) in the linear predictor:

\[\text{contribution}_j(t) = \mathbb{E}\bigl[\text{inv}(\mu) \cdot s - \text{inv}(\mu - v_j) \cdot s\bigr]\]

where \(\text{inv}\) is the inverse link function and \(s\) is target_scale. The difference is formed per draw before averaging; by linearity of expectation this equals \(\mathbb{E}[\text{inv}(\mu)] \cdot s - \mathbb{E}[\text{inv}(\mu - v_j)] \cdot s\) for the posterior mean returned here, while keeping the full-posterior form (see compute_counterfactual_contributions_dataset()) correct for credible intervals.

For identity-link (additive) models this reduces to \(\mathbb{E}[v_j] \cdot s\), and the columns sum exactly to \(\hat y(t)\).

For log-link (multiplicative) models this computes a genuine per-component counterfactual. Because interaction effects are counted by every component that participates in them, the columns sum to more than \(\hat y(t)\). This is an expected property of per-component counterfactuals in a multiplicative model, not a defect. Under the log link \(\exp(\mu)\) is the conditional median; pass central_tendency="mean" for the conditional-mean scale (see compute_counterfactual_contributions_dataset()).

This method does not require add_original_scale_contribution_variable() to have been called.

Parameters:

central_tendency{“median”, “mean”}, default “median”: Forwarded to compute_counterfactual_contributions_dataset().

Returns:

pd.DataFrame

Wide-format DataFrame with one row per observation (date x extra dims). Columns include:

date – date coordinate
Extra dimension columns (e.g. geo) when the model is multidimensional
One column per channel (named after channel coordinate labels)
One column per control variable (if present)
yearly_seasonality (if yearly seasonality is enabled)
One column per mu_effect (if present)
intercept

Raises:

ValueError: If the model has not been fitted (no idata).