meridian.model.equations.ModelEquations

Provides core, stateless mathematical functions for Meridian MMM.

meridian.model.equations.ModelEquations(
    model_context: meridian.model.context.ModelContext
)

Methods

adstock_hill_media

View source

adstock_hill_media(
    *,
    media: meridian.backend.Tensor,
    alpha: meridian.backend.Tensor,
    ec: meridian.backend.Tensor,
    slope: meridian.backend.Tensor,
    decay_functions: (str | Sequence[str]) = constants.GEOMETRIC_DECAY,
    n_times_output: (int | None) = None
) -> meridian.backend.Tensor

Transforms media or using Adstock and Hill functions in the desired order.

Args
media	Tensor of dimensions (n_geos, n_media_times, n_media_channels) containing non-negative media execution values. Typically this is impressions, but it can be any metric, such as media_spend. Clicks are often used for paid search ads.
alpha	Uniform distribution for Adstock and Hill calculations.
ec	Shifted half-normal distribution for Adstock and Hill calculations.
slope	Deterministic distribution for Adstock and Hill calculations.
decay_functions	String or sequence of strings denoting the adstock decay function(s) for each channel. Default: 'geometric'.
n_times_output	Number of time periods to output. This argument is optional when the number of time periods in media equals n_media_times, in which case n_times_output defaults to n_times.

Returns
Tensor with dimensions [..., n_geos, n_times, n_media_channels] representing Adstock and Hill-transformed media.

adstock_hill_rf

View source

adstock_hill_rf(
    *,
    reach: meridian.backend.Tensor,
    frequency: meridian.backend.Tensor,
    alpha: meridian.backend.Tensor,
    ec: meridian.backend.Tensor,
    slope: meridian.backend.Tensor,
    decay_functions: (str | Sequence[str]) = constants.GEOMETRIC_DECAY,
    n_times_output: (int | None) = None
) -> meridian.backend.Tensor

Transforms reach and frequency (RF) using Hill and Adstock functions.

Args
reach	Tensor of dimensions (n_geos, n_media_times, n_rf_channels) containing non-negative media for reach.
frequency	Tensor of dimensions (n_geos, n_media_times, n_rf_channels) containing non-negative media for frequency.
alpha	Uniform distribution for Adstock and Hill calculations.
ec	Shifted half-normal distribution for Adstock and Hill calculations.
slope	Deterministic distribution for Adstock and Hill calculations.
decay_functions	String or sequence of strings denoting the adstock decay function(s) for each channel. Default: 'geometric'.
n_times_output	Number of time periods to output. This argument is optional when the number of time periods in reach equals n_media_times, in which case n_times_output defaults to n_times.

Returns
Tensor with dimensions [..., n_geos, n_times, n_rf_channels] representing Hill and Adstock-transformed RF.

calculate_beta_x

View source

calculate_beta_x(
    *,
    is_non_media: bool,
    incremental_outcome_x: meridian.backend.Tensor,
    linear_predictor_counterfactual_difference: meridian.backend.Tensor,
    eta_x: meridian.backend.Tensor,
    beta_gx_dev: meridian.backend.Tensor
) -> meridian.backend.Tensor

Calculates coefficient mean parameter for any treatment variable type.

The "beta_x" in the function name refers to the coefficient mean parameter of any treatment variable. The "x" can represent "m", "rf", "om", or "orf". This function can also be used to calculate "gamma_n" for any non-media treatments.

Args
is_non_media	Boolean indicating whether the treatment variable is a non-media treatment. This argument is used to determine whether the coefficient random effects are normal or log-normal. If True, then random effects are assumed to be normal. Otherwise, the distribution is inferred from self._context.media_effects_dist.
incremental_outcome_x	The incremental outcome of the treatment variable, which depends on the parameter values of a particular prior or posterior draw. The "_x" indicates that this is a tensor with length equal to the dimension of the treatment variable.
linear_predictor_counterfactual_difference	The difference between the treatment variable and its counterfactual on the linear predictor scale. "Linear predictor" refers to the quantity that is multiplied by the geo-level coefficient. For media variables, this is the output of the hill/adstock transformation function. For non-media treatments, this is simply the treatment variable after centering/scaling transformations. This tensor has dimensions for geo, time, and channel.
eta_x	The random effect standard deviation parameter values. For media variables, the "x" represents "m", "rf", "om", or "orf". For non-media treatments, this argument should be set to xi_n, which is analogous to "eta".
beta_gx_dev	The latent standard normal parameter values of the geo-level coefficients. For media variables, the "x" represents "m", "rf", "om", or "orf". For non-media treatments, this argument should be set to gamma_gn_dev, which is analogous to "beta_gx_dev".

Returns
The coefficient mean parameter of the treatment variable, which has dimension equal to the number of treatment channels..

compute_non_media_treatments_baseline

View source

compute_non_media_treatments_baseline(
    non_media_baseline_values: (Sequence[str | float] | None) = None
) -> meridian.backend.Tensor

Computes the baseline for each non-media treatment channel.

Args

non_media_baseline_values

Optional list of shape (n_non_media_channels,). Each element is either a float (which means that the fixed value will be used as baseline for the given channel) or one of the strings "min" or "max" (which mean that the global minimum or maximum value will be used as baseline for the values of the given non_media treatment channel). If float values are provided, it is expected that they are scaled by population for the channels where model_spec.non_media_population_scaling_id is True. If None, the model_spec.non_media_baseline_values is used, which defaults to the minimum value for each non_media treatment channel.

Returns
A tensor of shape (n_non_media_channels,) containing the baseline values for each non-media treatment channel.

linear_predictor_counterfactual_difference_media

View source

linear_predictor_counterfactual_difference_media(
    *,
    media_transformed: meridian.backend.Tensor,
    alpha_m: meridian.backend.Tensor,
    ec_m: meridian.backend.Tensor,
    slope_m: meridian.backend.Tensor
) -> meridian.backend.Tensor

Calculates linear predictor counterfactual difference for non-RF media.

For non-RF media variables (paid or organic), this function calculates the linear predictor difference between the treatment variable and its counterfactual. "Linear predictor" refers to the output of the hill/adstock function, which is multiplied by the geo-level coefficient.

This function does the calculation efficiently by only calculating calling the hill/adstock function if the prior counterfactual is not all zeros.

Args
media_transformed	The output of the hill/adstock function for actual historical media data.
alpha_m	The adstock alpha parameter values.
ec_m	The adstock ec parameter values.
slope_m	The adstock hill slope parameter values.

Returns
The linear predictor difference between the treatment variable and its counterfactual.

linear_predictor_counterfactual_difference_rf

View source

linear_predictor_counterfactual_difference_rf(
    *,
    rf_transformed: meridian.backend.Tensor,
    alpha_rf: meridian.backend.Tensor,
    ec_rf: meridian.backend.Tensor,
    slope_rf: meridian.backend.Tensor
) -> meridian.backend.Tensor

Calculates linear predictor counterfactual difference for RF media.

For RF media variables (paid or organic), this function calculates the linear predictor difference between the treatment variable and its counterfactual. "Linear predictor" refers to the output of the hill/adstock function, which is multiplied by the geo-level coefficient.

This function does the calculation efficiently by only calculating calling the hill/adstock function if the prior counterfactual is not all zeros.

Args
rf_transformed	The output of the hill/adstock function for actual historical media data.
alpha_rf	The adstock alpha parameter values.
ec_rf	The adstock ec parameter values.
slope_rf	The adstock hill slope parameter values.

Returns
The linear predictor difference between the treatment variable and its counterfactual.