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 channel (aligned with MMM coords)

• 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.

Transformation Logic (Meridian-style default)

1. Register two raw tensors: reach_raw and frequency_raw with dims

   (date, *mmm.dims, 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[channel] and compute

   channel_contribution = beta * effective_exposure_adstocked.

6. Aggregate over 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.

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).

Edge Cases & Validation

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

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

• If channels present in the DataFrame are not a subset of the MMM channel coordinate, a ValueError is raised.

Extensibility

• Alternate effective exposure formulas (e.g. reach transform variants).

• Hierarchical priors for beta across channels / geos.

• Alternative adstock kernels via the injected transformation object.

• Additional nonlinear transforms on reach if strongly justified (not default).

Classes

FrequencyReachAdditiveEffect(**data)

Additive mu effect from frequency & reach observations.