Provides core, stateless mathematical functions for Meridian MMM.
meridian
.
model
.
equations
.
ModelEquations
(
model_context
:
meridian
.
model
.
context
.
ModelContext
)
Methods
adstock_hill_media
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
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
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
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
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
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.
