MMMPlotlyFactory.roas

MMMPlotlyFactory.roas(hdi_prob=0.94, frequency='all_time', method='elementwise', include_carryover=True, num_samples=None, random_state=None, start_date=None, end_date=None, round_digits=3, auto_facet=True, single_dim_facet='col', **plotly_kwargs)

Plot ROAS (Return on Ad Spend) bar chart.

Creates an interactive Plotly bar chart showing ROAS for each channel, with optional HDI error bars and faceting for multi-dimensional models.

Parameters:

hdi_probfloat, optional

HDI probability for error bars (default: 0.94). If None, no error bars.

frequencystr, optional

Time aggregation (default: “all_time”). Options: “original”, “weekly”, “monthly”, “quarterly”, “yearly”, “all_time”.

method{“incremental”, “elementwise”}, default “elementwise”

ROAS computation method. "incremental" uses counterfactual analysis accounting for adstock carryover as defined in [1] (Formula 10); "elementwise" uses simple contribution/spend division.

include_carryoverbool, default True

Include adstock carryover effects. Only used when method=”incremental”.

num_samplesint or None, optional

Number of posterior samples. Only used when method=”incremental”.

random_stateint, np.random.Generator, np.random.RandomState, or None, optional

Random state for reproducibility. Only used when method=”incremental”.

start_datestr or pd.Timestamp, optional

Start date for the evaluation window. When method="incremental", spend before this date still influences ROAS through adstock carryover effects (the counterfactual analysis automatically includes the necessary carry-in context). Passed through to roas().

end_datestr or pd.Timestamp, optional

End date for the evaluation window. When method="incremental", spend during the window continues to generate returns after this date through adstock carryover; those trailing effects are included in the ROAS calculation. Passed through to roas().

round_digitsint, default 3

Number of decimal places for rounding values in hover text.

auto_facetbool, default True

Automatically detect and apply faceting for custom dimensions.

single_dim_facet{“col”, “row”}, default “col”

When auto_facet is enabled and there is exactly one custom dimension, this controls whether it is applied as facet_col or facet_row.

**plotly_kwargs

Additional Plotly Express arguments including: - title: Figure title (default: “Return on Ad Spend”) - facet_row: Column for row facets (e.g., “country”) - facet_col: Column for column facets (e.g., “brand”) - facet_col_wrap: Max columns before wrapping - barmode: “group” or “stack”

Returns:

go.Figure

Interactive Plotly figure

References

[1]

Jin, Y., Wang, Y., Sun, Y., Chan, D., & Koehler, J. (2017). Bayesian Methods for Media Mix Modeling with Carryover and Shape Effects. Google Inc. https://research.google/pubs/bayesian-methods-for-media-mix-modeling-with-carryover-and-shape-effects/

Examples

>>> # Basic ROAS plot (element-wise)
>>> fig = mmm.plot_interactive.roas()
>>> fig.show()

>>> # ROAS by country (auto-faceted)
>>> fig = mmm.plot_interactive.roas(facet_col="country")
>>> fig.show()

>>> # Incremental ROAS (carryover-aware)
>>> fig = mmm.plot_interactive.roas(method="incremental")
>>> fig.show()

>>> # ROAS for a specific date range
>>> fig = mmm.plot_interactive.roas(
...     start_date="2024-01-01", end_date="2024-06-30"
... )
>>> fig.show()