MMMSummaryFactory.roas#

MMMSummaryFactory.roas(hdi_probs=None, frequency=None, method='elementwise', include_carryover=True, num_samples=None, random_state=None, start_date=None, end_date=None, output_format=None)[source]#

Create ROAS (Return on Ad Spend) summary DataFrame.

Computes ROAS = contribution / spend for each channel with mean, median, and HDI bounds.

Parameters:
hdi_probssequence of float, optional

HDI probability levels (default: uses factory default)

frequency{“original”, “weekly”, “monthly”, “quarterly”, “yearly”, “all_time”}, optional

Time aggregation period (default: None, no aggregation)

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

Method for computing ROAS:

  • incremental (recommended): Uses counterfactual analysis accounting for adstock carryover effects. Computes the true incremental return on ad spend as defined in [1] (Formula 10). Requires model to be provided (e.g. via mmm.summary).

  • elementwise: Simple element-wise division of contributions by spend. Does NOT account for carryover effects. Useful for daily efficiency tracking but not true incrementality. Works with data-only factory.

include_carryoverbool, default True

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

num_samplesint or None, optional

Number of posterior samples to use. If None, all samples are used. Only used when method="incremental".

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

Random state for reproducible subsampling. Only used when method="incremental" and num_samples is not None.

start_datestr or pd.Timestamp, optional

Start date for the evaluation window. For method="incremental" this is passed to contribution_over_spend(). Spend before this date still influences ROAS through adstock carryover effects (the counterfactual analysis automatically includes the necessary carry-in context). For method="elementwise" the ROAS result is filtered to dates on or after this value.

end_datestr or pd.Timestamp, optional

End date for the evaluation window. For method="incremental" this is passed to contribution_over_spend(). Spend during the window continues to generate returns after this date through adstock carryover; those trailing effects are included in the ROAS calculation. For method="elementwise" the ROAS result is filtered to dates on or before this value.

output_format{“pandas”, “polars”}, optional

Output DataFrame format (default: uses factory default)

Returns:
pd.DataFrame or pl.DataFrame

Summary DataFrame with columns:

  • date: Time index

  • channel: Channel name

  • mean: Mean ROAS

  • median: Median ROAS

  • abs_error_{prob}_lower: HDI lower bound for each prob

  • abs_error_{prob}_upper: HDI upper bound for each prob

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

>>> df = mmm.summary.roas()
>>> df = mmm.summary.roas(frequency="monthly")
>>> df = mmm.summary.roas(method="incremental", include_carryover=True)
>>> df = factory.roas(method="elementwise")
>>> df = mmm.summary.roas(
...     start_date="2024-01-01",
...     end_date="2024-06-30",
...     frequency="quarterly",
... )