frequency_reach_effect#

Frequency-Reach additive effect.

Implements an additive mu effect based on pre-computed (or provided) empirical frequency / reach observations per channel over time, following the Google Meridian style reach-frequency modelling guidance: https://developers.google.com/meridian/docs/advanced-modeling/reach-frequency

The objective is to transform raw marketing activity that is represented in terms of observed average frequency (times a reached individual is exposed) and reach (portion of the target population reached) into an effective “exposure pressure” term which is then passed through the existing adstock and saturation pipeline (re-using the same transformation classes already available to standard channel contributions) and added additively to the model mean (mu).

Data Requirements#

df_frequency_reach must contain at least the following columns:

  • date: datetime-like date of the observation.

  • channel: str categorical identifying the R&F channel.

  • frequency: numeric (>=0) average frequency among the reached population.

  • reach: numeric in [0, 1] proportion of the target population reached.

Optionally additional dimensions aligned with mmm.dims can be included and will be preserved (e.g. geo). They must exactly match those dims’ names.

R&F channels are independent of the standard MMM channel_columns. They use a dedicated rf_channel coordinate in the PyMC model. R&F is an alternative representation of media activity for those channels — the reach and frequency data replaces impressions or spend, not supplements it. Any channel name that appears in df_frequency_reach must not also appear in channel_columns of the parent MMM: create_data raises a ValueError if this constraint is violated, mirroring Meridian’s own InputData._validate_media_channels check.

Transformation Logic (Meridian-style)#

  1. Register two raw tensors: {prefix}_reach_raw and {prefix}_frequency_raw with dims (date, *mmm.dims, rf_channel).

  2. Apply the provided saturation transformation ONLY to frequency_raw to get frequency_sat (reach remains linear / unsaturated).

  3. Form effective_exposure_raw = reach_raw * frequency_sat (element-wise).

  4. Apply the adstock transformation to effective_exposure_raw producing effective_exposure_adstocked.

  5. Draw per-channel scaling coefficients beta[rf_channel] and compute channel_contribution = beta * effective_exposure_adstocked.

  6. Aggregate over rf_channel to obtain total_effect added to model mean.

  7. Expose intermediate deterministics for diagnostics: frequency_sat, effective_exposure_raw, effective_exposure_adstocked, channel_contribution, total_effect.

Budget Optimization#

When cost_per_unit is provided on this effect, the BudgetOptimizer can optimize spend across R&F channels jointly with standard media channels.

The conversion chain per channel i during optimization is:

spend_i → ÷ cost_per_unit_i → impressions_i
impressions_i = reach_i × frequency_i*
frequency_i* = assumed_frequency (fixed; historical median if not set)
reach_i = impressions_i / frequency_i*

This follows the same approach as Meridian: frequency is fixed during budget optimization (either at a user-supplied value or at the historical median), and only the total spend per channel is optimized.

Assumptions#

  • Frequencies and reaches are already on the relevant date granularity of the model.

  • Reach is a proportion in [0, 1]; frequency is >= 0.

  • Missing combinations (date, channel, extra dims) are zero-filled internally.

  • Saturation acts only on frequency to avoid stacking nonlinearities on both multiplicative terms (improves identifiability of beta).

  • R&F channels are disjoint from channel_columns of the parent MMM.

Edge Cases & Validation#

  • Negative frequency or reach outside [0, 1] raises ValueError.

  • Duplicate rows for the same (date, dims, channel) are aggregated (mean).

  • cost_per_unit, if provided, must have a date column and one column per R&F channel, with all-positive values.

References#

Jin, Y., Wang, Y., Sun, Y., Chan, D., & Koehler, J. (2017). Bayesian Methods for Media Mix Modeling with Carryover and Shape Effects. Google Inc.

Guo, R., Chan, D., Koehler, J., Jin, Y., Wang, Y., & Sun, Y. (2021). Bayesian Hierarchical Media Mix Model Incorporating Reach and Frequency Data. https://research.google/pubs/bayesian-hierarchical-media-mix-model-incorporating-reach-and-frequency-data/

Classes

FrequencyReachAdditiveEffect(**data)

Additive mu effect from frequency & reach observations.