MMMPlotSuite.waterfall_components_decomposition#

MMMPlotSuite.waterfall_components_decomposition(var=None, original_scale=True, dims=None, split_by=None, figsize=None, subplot_kwargs=None, **kwargs)[source]#

Create a waterfall plot showing the decomposition of the target into its components.

This plot visualizes how different model components (channels, controls, intercept, seasonality, etc.) contribute to the overall prediction. Each component is shown as a horizontal bar with its contribution value and percentage.

Parameters:

varlist of str, optional: List of contribution variable names from the posterior to include in the plot. If None, automatically detects all contribution variables from the posterior. Example: [“intercept_contribution_original_scale”,

“channel_contribution_original_scale”, “control_contribution_original_scale”]
original_scalebool, default True: If True and var is None, use original scale contribution variables (ending with “_contribution_original_scale”). If False and var is None, use non-original scale contribution variables. Ignored if var is explicitly provided.
dimsdict[str, str | int | list], optional: Dimension filters to apply. Example: {“geo”: “US”}. If provided, only the selected slice(s) will be included in the plot.
split_bystr or list of str, optional: Dimension(s) to create separate subplots for. Each unique combination of values in these dimensions will get its own waterfall plot. Example: “geo” or [“geo”, “product”].
figsizetuple of int, optional: The size of the figure in inches (width, height). If None, defaults to (14, 7) for single plots, or auto-calculated based on number of subplots.
subplot_kwargsdict, optional: Additional keyword arguments for subplot layout configuration. Supports “nrows” or “ncols” to control grid arrangement. Only one of nrows or ncols should be specified.
**kwargs: Additional keyword arguments passed to matplotlib’s subplots function.

Returns:

figmatplotlib.figure.Figure: The Figure object containing the plot(s).
ax_or_axesmatplotlib.axes.Axes or np.ndarray of Axes: If split_by is None: single Axes object. If split_by is provided: 2D array of Axes objects.

Raises:

ValueError: If no posterior data is found in idata. If none of the requested variables are present in idata.posterior. If split_by dimension is not found in the data. If both nrows and ncols are specified in subplot_kwargs.

Examples

Create a waterfall plot with all contribution variables (auto-detected):

fig, ax = mmm.plot.waterfall_components_decomposition()

Create a waterfall plot with specific contribution variables:

fig, ax = mmm.plot.waterfall_components_decomposition(
    var=[
        "intercept_contribution_original_scale",
        "channel_contribution_original_scale",
        "control_contribution_original_scale",
    ]
)

With custom figure size:

fig, ax = mmm.plot.waterfall_components_decomposition(figsize=(18, 10))

Filter by dimension:

fig, ax = mmm.plot.waterfall_components_decomposition(dims={"geo": "US"})

Create subplots split by dimension:

fig, axes = mmm.plot.waterfall_components_decomposition(split_by="geo")

Control subplot layout:

fig, axes = mmm.plot.waterfall_components_decomposition(
    split_by="geo",
    subplot_kwargs={"ncols": 2},
)