MMMPlotSuite.budget_allocation_roas#

MMMPlotSuite.budget_allocation_roas(samples, dims=None, dims_to_group_by=None, backend=None)[source]#

Plot ROI (Return on Ad Spend) distributions for budget allocation scenarios.

Visualizes the posterior distribution of ROI for each channel given a budget allocation. Useful for comparing ROI across channels and understanding optimization trade-offs.

Parameters:

samplesxr.Dataset

Dataset from budget allocation optimization containing: - ‘channel_contribution_original_scale’: Channel contributions - ‘allocation’: Allocated budget per channel - ‘channel’ dimension

Typically obtained from: mmm.allocate_budget_to_maximize_response(...)

dimsdict[str, str | int | list], optional

Dimension filters to apply. Examples: - {“geo”: “US”} - {“geo”: [“US”, “UK”]}

If provided, only the selected slice(s) will be plotted.

dims_to_group_bylist[str] | str | None, optional

Dimension(s) to group by for overlaying distributions. When specified, all ROI distributions for each coordinate of that dimension will be plotted together for comparison.

None (default): Each distribution plotted separately
Single string: Group by that dimension (e.g., “geo”)
List of strings: Group by multiple dimensions (e.g., [“geo”, “segment”])

backendstr | None, optional

Backend to use for plotting. If None, uses global backend configuration.

Returns:

PlotCollection

arviz_plots PlotCollection object containing the plot.

Use .show() to display or .save("filename") to save.

Raises:

ValueError: If ‘channel’ dimension not found in samples.
ValueError: If required variables not found in samples.

See also

LegacyMMMPlotSuite.budget_allocation: Legacy bar chart method (different purpose)

Notes

This method is NEW in MMMPlotSuite v2 and serves a different purpose than the legacy budget_allocation() method:

New method (this): Shows ROI distributions (KDE plots)
Legacy method: Shows bar charts comparing spend vs contributions

To use the legacy method, set: mmm_plot_config["plot.use_v2"] = False

Examples

Basic usage with budget optimization results:

allocation_results = mmm.allocate_budget_to_maximize_response(
    total_budget=100_000, budget_bounds={"lower": 0.5, "upper": 2.0}
)
pc = mmm.plot.budget_allocation_roas(allocation_results)
pc.show()

Group by geography to compare ROI across regions:

pc = mmm.plot.budget_allocation_roas(
    allocation_results, dims_to_group_by="geo"
)
pc.show()

Filter and group:

pc = mmm.plot.budget_allocation_roas(
    allocation_results, dims={"segment": "premium"}, dims_to_group_by="geo"
)
pc.show()