meridian.model.model.Meridian

Contains the main functionality for fitting the Meridian MMM model.

meridian.model.model.Meridian(
    input_data: meridian.data.input_data.InputData,
    model_spec: (meridian.model.spec.ModelSpec | None) = None,
    inference_data: (az.InferenceData | None) = None
)

input_data An InputData object containing the input data for the model.
model_spec A ModelSpec object containing the model specification.
inference_data A mutable arviz.InferenceData object containing the resulting data from fitting the model.
n_geos Number of geos in the data.
n_media_channels Number of media channels in the data.
n_rf_channels Number of reach and frequency (RF) channels in the data.
n_organic_media_channels Number of organic media channels in the data.
n_organic_rf_channels Number of organic reach and frequency (RF) channels in the data.
n_controls Number of control variables in the data.
n_non_media_channels Number of non-media treatment channels in the data.
n_times Number of time periods in the KPI or spend data.
n_media_times Number of time periods in the media data.
is_national A boolean indicating whether the data is national (single geo) or not (multiple geos).
knot_info A KnotInfo derived from input data and model spec.
kpi A tensor constructed from input_data.kpi.
revenue_per_kpi A tensor constructed from input_data.revenue_per_kpi. If input_data.revenue_per_kpi is None, then this is also None.
controls A tensor constructed from input_data.controls.
non_media_treatments A tensor constructed from input_data.non_media_treatments.
population A tensor constructed from input_data.population.
media_tensors A collection of media tensors derived from input_data.
rf_tensors A collection of Reach & Frequency (RF) media tensors.
organic_media_tensors A collection of organic media tensors.
organic_rf_tensors A collection of organic Reach & Frequency (RF) media tensors.
total_spend A tensor containing total spend, including media_tensors.media_spend and rf_tensors.rf_spend.
total_outcome A tensor containing the total outcome, aggregated over geos and times.
controls_transformer A ControlsTransformer to scale controls tensors using the model's controls data.
non_media_transformer A CenteringAndScalingTransformer to scale non-media treatmenttensors using the model's non-media treatment data.
kpi_transformer A KpiTransformer to scale KPI tensors using the model's KPI data.
controls_scaled The controls tensor normalized by population and by the median value.
non_media_treatments_scaled The non-media treatment tensor normalized by population and by the median value.
kpi_scaled The KPI tensor normalized by population and by the median value.
media_effects_dist A string to specify the distribution of media random effects across geos.
unique_sigma_for_each_geo A boolean indicating whether to use a unique residual variance for each geo.
prior_broadcast A PriorDistribution object containing broadcasted distributions.
baseline_geo_idx The index of the baseline geo.
holdout_id A tensor containing the holdout id, if present.
adstock_decay_spec Returns AdstockDecaySpec object with correctly mapped channels.
non_media_treatments_normalized Normalized non-media treatments.

The non-media treatments values are scaled by population (for channels where non_media_population_scaling_id is True) and normalized by centering and scaling with means and standard deviations.

posterior_sampler_callable A PosteriorMCMCSampler callable bound to this model.
prior_sampler_callable A PriorDistributionSampler callable bound to this model.

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 self.n_media_times, in which case n_times_output defaults to self.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 self.n_media_times, in which case n_times_output defaults to self.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.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.

create_inference_data_coords

View source

create_inference_data_coords(
    n_chains: int, n_draws: int
) -> Mapping[str, np.ndarray | Sequence[str]]

Creates data coordinates for inference data.

create_inference_data_dims

View source

create_inference_data_dims() -> Mapping[str, Sequence[str]]

expand_selected_time_dims

View source

expand_selected_time_dims(
    start_date: meridian.data.time_coordinates.Date = None,
    end_date: meridian.data.time_coordinates.Date = None
) -> (list[str] | None)

Validates and returns time dimension values based on the selected times.

If both start_date and end_date are None, returns None. If specified, both start_date and end_date are inclusive, and must be present in the time coordinates of the input data.

Args
start_date Start date of the selected time period. If None, implies the earliest time dimension value in the input data.
end_date End date of the selected time period. If None, implies the latest time dimension value in the input data.

Returns
A list of time dimension values (as Meridian-formatted strings) in the input data within the selected time period, or do nothing and pass through None if both arguments are Nones, or if start_date and end_date correspond to the entire time range in the input data.

Raises
ValueError if start_date or end_date is not in the input data time dimensions.

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.

populate_cached_properties

View source

populate_cached_properties()

Eagerly activates all cached properties.

This is useful for creating a tf.function computation graph with this Meridian object as part of a captured closure. Within the computation graph, internal state mutations are problematic, and so this method freezes the object's states before the computation graph is created.

sample_posterior

View source

sample_posterior(
    n_chains: (Sequence[int] | int),
    n_adapt: int,
    n_burnin: int,
    n_keep: int,
    current_state: (Mapping[str, backend.Tensor] | None) = None,
    init_step_size: (int | None) = None,
    dual_averaging_kwargs: (Mapping[str, int] | None) = None,
    max_tree_depth: int = 10,
    max_energy_diff: float = 500.0,
    unrolled_leapfrog_steps: int = 1,
    parallel_iterations: int = 10,
    seed: (Sequence[int] | int | None) = None,
    **pins
)

Runs Markov Chain Monte Carlo (MCMC) sampling of posterior distributions.

For more information about the arguments, see windowed_adaptive_nuts.

Drawn samples are merged into this model's Arviz inference_data property.

Args
n_chains Number of MCMC chains. Given a sequence of integers, windowed_adaptive_nuts will be called once for each element. The n_chains argument of each windowed_adaptive_nuts call will be equal to the respective integer element. Using a list of integers, one can split the chains of a windowed_adaptive_nuts call into multiple calls with fewer chains per call. This can reduce memory usage. This might require an increased number of adaptation steps for convergence, as the optimization is occurring across fewer chains per sampling call.
n_adapt Number of adaptation draws per chain.
n_burnin Number of burn-in draws per chain. Burn-in draws occur after adaptation draws and before the kept draws.
n_keep Integer number of draws per chain to keep for inference.
current_state Optional structure of tensors at which to initialize sampling. Use the same shape and structure as model.experimental_pin(**pins).sample(n_chains).
init_step_size Optional integer determining where to initialize the step size for the leapfrog integrator. The structure must broadcast with current_state. For example, if the initial state is: { 'a': tf.zeros(n_chains), 'b': tf.zeros([n_chains, n_features]), } then any of 1., {'a': 1., 'b': 1.}, or {'a': tf.ones(n_chains), 'b': tf.ones([n_chains, n_features])} will work. Defaults to the dimension of the log density to the ¼ power.
dual_averaging_kwargs Optional dict keyword arguments to pass to tfp.mcmc.DualAveragingStepSizeAdaptation. By default, a target_accept_prob of 0.85 is set, acceptance probabilities across chains are reduced using a harmonic mean, and the class defaults are used otherwise.
max_tree_depth Maximum depth of the tree implicitly built by NUTS. The maximum number of leapfrog steps is bounded by 2**max_tree_depth, for example, the number of nodes in a binary tree max_tree_depth nodes deep. The default setting of 10 takes up to 1024 leapfrog steps.
max_energy_diff Scalar threshold of energy differences at each leapfrog, divergence samples are defined as leapfrog steps that exceed this threshold. Default is 1000.
unrolled_leapfrog_steps The number of leapfrogs to unroll per tree expansion step. Applies a direct linear multiplier to the maximum trajectory length implied by max_tree_depth. Defaults is 1.
parallel_iterations Number of iterations allowed to run in parallel. Must be a positive integer. For more information, see tf.while_loop.
seed An int32[2] Tensor or a Python list or tuple of 2 ints, which will be treated as stateless seeds; or a Python int or None, which will be treated as stateful seeds. See tfp.random.sanitize_seed.
**pins These are used to condition the provided joint distribution, and are passed directly to joint_dist.experimental_pin(**pins).

Throws
MCMCOOMError If the model is out of memory. Try reducing n_keep or pass a list of integers as n_chains to sample chains serially. For more information, see ResourceExhaustedError when running Meridian.sample_posterior.

sample_prior

View source

sample_prior(
    n_draws: int, seed: (int | None) = None
)

Draws samples from the prior distributions.

Drawn samples are merged into this model's Arviz inference_data property.

Args
n_draws Number of samples drawn from the prior distribution.
seed Used to set the seed for reproducible results. For more information, see PRNGS and seeds.