FrequencyReachAdditiveEffect

class pymc_marketing.mmm.additive_effect.frequency_reach_effect.FrequencyReachAdditiveEffect(**data)

Additive mu effect from frequency & reach observations.

Follows the Meridian-style reach-frequency modelling approach: saturation is applied to frequency only, reach enters linearly, and the product is passed through adstock before being scaled by a per-channel beta coefficient.

R&F channels live in a dedicated rf_channel coordinate and are fully independent of the standard MMM channel_columns.

Parameters:

df_frequency_reachpd.DataFrame

Long-format DataFrame with columns at least: date, channel, frequency, reach. Additional columns matching mmm.dims (e.g. geo) are optional and will be preserved.

saturationHillShapeSaturation

Shape-only Hill saturation applied to frequency. Must not contain an internal amplitude parameter to keep the model identifiable (that role is played by beta).

adstockAdstockTransformation

Adstock kernel applied to the effective-exposure signal (reach × saturated_frequency).

beta_priorPrior, optional

Prior for the per-channel scaling coefficient beta. Defaults to HalfNormal(sigma=1), which enforces non-negative contributions (semantically appropriate for R&F channels). Any Prior instance is accepted; dims must not be set — they are assigned automatically to "rf_channel" at model build time.

cost_per_unitpd.DataFrame, optional

Cost per impression for each R&F channel, optionally varying by date. Wide-format DataFrame with a date column and one column per channel name matching those in df_frequency_reach. All values must be positive. Required when budget optimization is used.

assumed_frequencyfloat or dict[str, float], optional

Fixed average-frequency assumption used during budget optimization to split total impressions into reach and frequency. A scalar applies to all channels; a dict maps channel names to per-channel values. When None (default), the historical per-channel median frequency is used.

prefixstr, optional

Variable-name prefix for all PyMC random and deterministic variables created by this effect. Defaults to "frequency_reach".

date_columnstr, optional

Name of the date column in df_frequency_reach. Defaults to "date".

channel_columnstr, optional

Name of the channel column in df_frequency_reach. Defaults to "channel".

Notes

The PyMC coordinate for R&F channels is always "rf_channel" regardless of channel_column. This ensures that R&F channel names cannot collide with standard media channel coordinates.

Methods

FrequencyReachAdditiveEffect.__init__(**data)	Create a new model by parsing and validating input data from keyword arguments.
FrequencyReachAdditiveEffect.build_rf_optimization_tensors(...)	Build (reach, frequency) PyTensor tensors for optimizer graph injection.
FrequencyReachAdditiveEffect.construct([...])
FrequencyReachAdditiveEffect.copy(*[, ...])	Returns a copy of the model.
FrequencyReachAdditiveEffect.create_data(mmm)	Register pm.Data nodes required for the effect.
FrequencyReachAdditiveEffect.create_effect(mmm)	Build the Meridian-style R&F pipeline and return the aggregate effect.
FrequencyReachAdditiveEffect.dict(*[, ...])
FrequencyReachAdditiveEffect.from_orm(obj)
FrequencyReachAdditiveEffect.get_assumed_frequency_array()	Return a per-channel frequency array for use during optimization.
FrequencyReachAdditiveEffect.json(*[, ...])
FrequencyReachAdditiveEffect.model_parametrized_name(params)	Compute the class name for parametrizations of generic classes.
FrequencyReachAdditiveEffect.parse_file(path, *)
FrequencyReachAdditiveEffect.parse_obj(obj)
FrequencyReachAdditiveEffect.parse_raw(b, *)
FrequencyReachAdditiveEffect.schema([...])
FrequencyReachAdditiveEffect.schema_json(*)
FrequencyReachAdditiveEffect.set_data(mmm, ...)	Update reach & frequency data for prediction (e.g. future) dates.
FrequencyReachAdditiveEffect.update_forward_refs(...)
FrequencyReachAdditiveEffect.validate(value)

Attributes

cost_per_unit_xarray	Parse cost_per_unit DataFrame into a DataArray.
model_computed_fields
model_config	Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
model_extra	Get extra fields set during validation.
model_fields
model_fields_set	Returns the set of fields that have been explicitly set on this model instance.
rf_channels	Sorted list of R&F channel names from the DataFrame.
df_frequency_reach
saturation
adstock
beta_prior
cost_per_unit
assumed_frequency
prefix
date_column
channel_column