Module: meridian.protos

Table of Contents

Top

date_interval.proto

DateInterval

Field Type Description
start_date Date The start date of the interval. Inclusive. Required.
end_date Date The end date of the interval. Exclusive. Required.
tag string A tag to identify the date interval. Optional.

Top

estimate.proto

Estimate

Contains an estimate value of estimand and associated quantified uncertainties.

Field Type Description
value double The estimate value of an estimand. Required.
uncertainties Uncertainty The quantified uncertainties.

Estimate.Uncertainty

The uncertainty of an estimate quantified by probability interval.

Field Type Description
probability double The probability that a value is inside an interval bounded by lowerbound and upperbound. Required.
lowerbound double The lowerbound of the interval. Required.
upperbound double The upperbound of the interval. Required.

Top

model_fit.proto

ModelFit

Field Type Description
results Result Different results for different purposes. For example, one could divide a data to training set, testing set, and validation set. Required.

Performance

The model fit performance indicated by different metrics.

Field Type Description
r_squared double
mape double Mean absolute percentage error.
weighted_mape double Is equal to sum_i(actual_i - pred_i) / sum_i(actual_i)
rmse double Root mean square error.

Prediction

A prediction contains the predicted KPI and the ground truth at a specific time.

Field Type Description
date_interval DateInterval The time associated to this prediction point. Required.
predicted_outcome Estimate The predicted outcome. Required.
predicted_baseline Estimate The predicted baseline. Optional.
actual_value double The actual value observed in the data. Required.

Result

Field Type Description
name string The name of the result. Required.
predictions Prediction The predictions over different times. Required.
performance Performance The performance of the model fit. Required.

Top

kpi_type.proto

KpiType

Different KPI types used in marketing performance and optimization.

Name Number Description
KPI_TYPE_UNSPECIFIED 0
NON_REVENUE 1 Some generic user-defined KPI unit.
REVENUE 2 KPI defined as revenue specifically, or some KPI unit after conversion to revenue.

Top

outcome.proto

Contribution

A contribution is defined as the value difference caused by adding a new outcome.

Field Type Description
value Estimate The contribution value. Required.
share Estimate Share of contribution = contribution / total contribution from all outcomes.

Effectiveness

Effectiveness calculates how much incremental KPI is generated per media unit (e.g. impressions or clicks), i.e. contribution / media unit.

Field Type Description
media_unit string The media unit of the effectiveness. Required.
value Estimate The value of the effectiveness. Required.

Outcome

An outcome analysis on KPI which can be defined as revenue or other generic non-revenue type.

Field Type Description
kpi_type KpiType The type of this KPI (i.e. REVENUE or NON_REVENUE) Note that a model input with non-revenue (generic KPI) data can still have revenue-based KPI outcomes defined, provided that revenue_per_kpi is defined.
contribution Contribution The contribution to a KPI. If kpi_type == REVENUE, this is the revenue KPI value. If kpi_type == NON_REVENUE, AND there is a revenue_per_kpi conversion, this is the derived kpi * revenue_per_kpi value. Otherwise, this is simply the (non-revenue, user-defined) KPI value.
effectiveness Effectiveness The effectiveness of this outcome.
roi Estimate ROI = contribution / spend. See contribution definition above.
marginal_roi Estimate Marginal ROI shows the additional ROI gained from additional spend. See ROI definition above.
cost_per_contribution Estimate Cost per incremental outcome (which could be revenue or some generic KPI). E.g. when contribution is thousand impression, it is CPM; when contribution is acquisition, this is CPA.

Top

response_curve.proto

ResponseCurve

A response curve is used to show how much incremental outcome moves in response to changes to the input value (e.g. spend amount on a paid media channel, advertising impressions in a channel, etc).

Field Type Description
input_name string The name of the input. Required.
response_points ResponsePoint The response points. Required.

ResponsePoint

Field Type Description
input_value double The amount of the input that drives the incremental KPI. Required.
incremental_kpi double The incremental KPI caused by the input. Required.

Top

media_analysis.proto

MediaAnalysis

An analysis on a media channel between its spend variable and KPI(s) outcome.

Field Type Description
channel_name string The name of the media channel. Required.
spend_info SpendInfo The spend information of this media channel. This is optional and is left unset for a non-paid media channel analysis.
media_outcomes Outcome The marketing outcomes of advertising from this media channel. Required. The outcome(s) calculated based on revenue and/or generic non-revenue KPI. One or more outcome values are set when revenue and/or generic non-revenue KPI outcome information is available. For a non-paid media, the spend-related fields in Outcome won't be set.
response_curve ResponseCurve A response curve for the media channel. When the media is a non-paid media, response curve is not available due to the lack of spend information.

SpendInfo

Field Type Description
spend double The amount spent on the media channel. Required
spend_share double Spend share = spend / total spend. Required

Top

non_media_analysis.proto

NonMediaAnalysis

The analysis on non-media factor.

Field Type Description
non_media_name string The name of the non-media factor. Required.
non_media_outcomes Outcome The marketing outcomes from this non-media factor. Required. The non-media outcome(s) calculated based on revenue and/or generic non-revenue KPI. One or more outcome values are set when revenue and/or generic non-revenue KPI outcome information is available. The spend-related fields herein won't be set as non-media factor doesn't have spend.

Top

marketing_analysis.proto

MarketingAnalysis

The marketing analysis.

Field Type Description
date_interval DateInterval The date interval that the analysis covers. Required.
media_analyses MediaAnalysis Analysis on different media channels. Required.
non_media_analyses NonMediaAnalysis Analysis on different non-media factors.

MarketingAnalysisList

A list of marketing analyses.

Field Type Description
marketing_analyses MarketingAnalysis The marketing analyses for different time ranges. Required.

Top

target_metric.proto

TargetMetric

Target metrics for marketing performance optimizations. Note that each of these metric variants can be interpreted in terms of either revenue or non-revenue KPI type. See: common.KpiType.

Name Number Description
TARGET_METRIC_UNSPECIFIED 0
KPI 1 Any KPI type (revenue if the model data can be converted to revenue, or some generic KPI otherwise).
ROI 2 ROI = net KPI change / spend.
MARGINAL_ROI 3 Marginal ROI is defined at channel level and is applied across all channels. mROI = changed in incremental KPI / spend.
COST_PER_INCREMENTAL_KPI 4 CPIK = total spend / change in incremental KPI.

Top

marketing_data.proto

ControlVariable

The control variable. A control variable is not directly being studied but included in the model to account for potential confounding effects on the relationship between the primary independent and dependent variables. Examples: seasonality factors, and macroeconomic factors.

Field Type Description
name string The name of the variable. Required.
value double The value of the variable. Required.

GeoInfo

Field Type Description
geo_id string The ID of the geo location. Required.
population int64 The population of the geo location. Required.

Kpi

A KPI (key performance indicator) can either be revenue directly, or some other metric that indirectly contributes to revenue eventually (e.g. sales units, conversions, impressions, etc) with a multiplier value to roughly translates said non-revenue KPI unit into revenue.

Field Type Description
name string The name of the KPI. Required.
revenue Revenue
non_revenue NonRevenue

Kpi.NonRevenue

A non-revenue type of KPI.

Field Type Description
value double The value of the non-revenue KPI.
revenue_per_kpi double Used to convert non-revenue KPI value to revenue. Needs to be non-negative.

Kpi.Revenue

A revenue KPI.

Field Type Description
value double The revenue value.

MarketingData

A collection of marketing data points for different combinations of geo locations and times, used for model training.

Field Type Description
marketing_data_points MarketingDataPoint The marketing data points. Required.
metadata MarketingDataMetadata Metadata support useful to recreate a model data in its domain language.

MarketingDataMetadata

Metadata support useful to validate data points and recreate a model data in its domain language.

Field Type Description
time_dimensions TimeDimension One or more sets of time coordinates. Required.
geo_dimension GeoDimension The geo dimension of the model. Required.
channel_dimensions ChannelDimension One or more sets of channel names. Required.
control_names string Control variable names.
kpi_type string The KPI type.
non_media_treatment_names string Non-media treatment variable names.

MarketingDataMetadata.ChannelDimension

A named set of channel name coordinates.

Field Type Description
name string A name for this set of channel names in this dimension. Optional.
channels string The channel names in this set's dimensional coordinates. Required.

MarketingDataMetadata.GeoDimension

Field Type Description
geo_coordinates string

MarketingDataMetadata.TimeDimension

A named set of time coordinates.

Field Type Description
name string A name for this set of time coordinates. Optional.
dates Date The coordinates of this time dimension in the model, as dates. Required.

MarketingDataPoint

A data point contains marketing information at specific geo and time.

Field Type Description
geo_info GeoInfo Geo info of this data point. If unset, this data point is aggregated across all geos in the model's geo coordinates.
date_interval DateInterval Date interval covered by this data point. Required. This can represent either a coordinate point, or an aggregation over a time dimension's coordinates. In the case of the latter, this field should be defined with [start, end + interval] value, where start and end are the first and last coordinate in that time dimension, respectively.
control_variables ControlVariable The control variables associated to the marketing at this geo and time.
media_variables MediaVariable The media variables associated to the marketing at this geo and time. If a media variable is from a paid media channel and its media spend breakdown by geo and time is not available (i.e. media spend is aggregated across all geos and times), then there should be a separate MarketingDataPoint message with media_spend where geo_info is unset and date_interval spans the entire time dimension's coordinates. Media channel names should be unique across this group of media variables.
reach_frequency_variables ReachFrequencyVariable The reach and frequency variables associated to the marketing at this geo and time. If a reach and frequency variable is from a paid media channel and its spend breakdown by geo and time is not available (i.e. spend is aggregated across all geos and times), then there should be a separate MarketingDataPoint message with spend where geo_info is unset and date_interval spans the entire time dimension's coordinates. Reach and frequency variable names should be unique across this group of reach and frequency variables.
kpi Kpi The KPI associated to the marketing at this geo and time. Kpi type must be consistent across all data points.
non_media_treatment_variables NonMediaTreatmentVariable Non-media treatment variables associated with this data point.

MediaVariable

The media variable.

Field Type Description
channel_name string The name of the media channel. Required.
scalar_metric ScalarMetric Scalar metric measured on the channel. Required.
media_spend double Spend on the media. If the media variable is a paid media, spend is required.

NonMediaTreatmentVariable

The non-media treatment variable. A marketing activity that is not directly related to media, such as running a promotion, the price of a product, and a change in a product's packaging or design.

Field Type Description
name string The name of the variable. Required.
value double The value of the variable. Required.

ReachFrequencyVariable

The reach and frequency variable.

Field Type Description
channel_name string The name of the reach and frequency variable. Required.
reach int64 The reach value. Required.
average_frequency double The average frequency value. Required.
spend double The spend value. If the reach and frequency variable is a paid media, spend is required.

ScalarMetric

Scalar type of metrics. Ex: Impressions, clicks, costs, and etc.

Field Type Description
name string The name of the scalar metric. Required.
value double The value of the scalar metric. Required.

Top

new_marketing_data.proto

NewMarketingData

A collection of independent marketing data points for different combinations of geo locations and times, used to override training data for model inference. This can span any time period, including times overlapping with and beyond the modeling period.

Field Type Description
marketing_data_points NewMarketingDataPoint The independent marketing data points for each geo and time.

NewMarketingDataPoint

A new marketing data point used for model inference. This contains independent marketing data at a specific geo and time.

Field Type Description
geo_info GeoInfo Geo info of this data point. Required for a geo model.
date_interval DateInterval Date interval covered by this data point. This can represent either a coordinate point, or an aggregation over a time dimension's coordinates. In the case of the latter, this field should be defined with [start, end + interval] value, where start and end are the first and last coordinate in that time dimension, respectively.
media_variables MediaVariable The media variables associated with the marketing at this geo and time.
reach_frequency_variables ReachFrequencyVariable The reach and frequency variables associated with the marketing at this geo and time.
revenue_per_kpi double The revenue per KPI associated with the marketing at this geo and time. Required for revenue analysis.

Top

constraints.proto

BudgetConstraint

Field Type Description
min_budget double Required. Absolute minimum budget value.
max_budget double Required. Absolute maximum budget value.

FrequencyConstraint

Field Type Description
min_frequency double Required.
max_frequency double Required.

TargetMetricConstraint

The constraint of target metrics.

Field Type Description
target_metric TargetMetric The type of the target metric that is constrained. Required.
target_value double The constraint on the target metric value. Required. Whether this target value represents a lower or upper bound depends on the target metric set above.

Top

budget_optimization.proto

BudgetOptimization

Field Type Description
results BudgetOptimizationResult Optimization results for different scenarios.

BudgetOptimizationResult

The budget optimization finds the result of optimal budget allocation given an optimization spec.

Field Type Description
name string The name of the budget optimization. Required.
group_id string An optional identifier for a result that belongs to a group of related results (of different types). Note that no two BudgetOptimizationResults should share the same group ID Simple UUID strings are recommended.
spec BudgetOptimizationSpec The optimization spec used to generate the result. Required.
optimized_marketing_analysis MarketingAnalysis The analysis on marketing outcome when using the optimized budget. Required. The non-media outcomes are not optimized, but some fields might be impacted by the change of media outcomes. For example, total contribution would change, so the contribution share values have to modified accordingly.
nonoptimized_marketing_analysis MarketingAnalysis The non-optimized marketing outcome. Required. In a fixed budget scenario, non-optimized marketing outcome is based on the budget amount. In a flexible budget scenario, the outcome is based on the historical spend.
incremental_outcome_grid IncrementalOutcomeGrid Optional search grid that describes incremental outcomes of spends on channels. Useful for speeding up optimization analysis.

BudgetOptimizationSpec

Input to the optimizer.

Field Type Description
date_interval DateInterval The date interval defines the selection of the time points that the optimization is based upon.
objective TargetMetric The objective to maximize in the budget optimization. Required.
kpi_type KpiType The type of KPI used to derive the optimization objective. Required.
new_marketing_data NewMarketingData The new marketing data to override the flighting pattern and CPM. If not provided, the optimization will be based on the historical data.
use_optimal_frequency bool Whether to use the optimal frequency, If set to False, max_frequency is ignored.
max_frequency float The max frequency to use for the optimal frequency search space, this field is ignored if use_optimal_frequency is unset or is set to False. If not set when use_optimal_frequency is set to True, the max frequency of the input data is used. max_frequency must be greater than 1 if set.
fixed_budget_scenario FixedBudgetScenario A fixed budget optimization tries to maximize an objective by optimizing the budget allocations over channels without changing the total budget amount. For instance, in Meridian, the objective function is chosen to be the posterior mean of the expected KPI (e.g. sales, revenue, etc).
flexible_budget_scenario FlexibleBudgetScenario A flexible budget optimization tries to maximize an objective by optimizing the budget allocations over channels with a flexible total budget amount. For instance, in Meridian, the expected KPI (e.g. revenue) can be optimized while allowing the total budget to vary: this flexible optimization in Meridian is constrained on either the minimal marginal ROI or the target ROI constraints.
channel_constraints ChannelConstraint The constraints on channels. If a media channel that is present in the model is not represented here, it will be given the default constraint of [0, max_budget].

ChannelConstraint

Channel level constraint

Field Type Description
channel_name string The name of the channel. Required.
budget_constraint BudgetConstraint The budget constraint on the channel.

FixedBudgetScenario

A fixed budget scenario for optimizing budget allocations over channels.

Field Type Description
total_budget double The budget amount. Required.

FlexibleBudgetScenario

A flexible budget scenario for optimizing budget allocations over channels.

Field Type Description
total_budget_constraint BudgetConstraint The constraint parameters on the total budget.
target_metric_constraints TargetMetricConstraint The constraints on target metrics (e.g. KPI, ROI, etc).

IncrementalOutcomeGrid

A message representing a grid that details the incremental outcome of marketing spend by channel.

Note that this grid is constructed under the assumption that there is no interaction effect across channels, i.e. the spend on one channel will not affect other channels.

Field Type Description
name string The name of the grid. Required.
spend_step_size double The uniform step size between consecutive spend values within a channel. Required.
channel_cells ChannelCells The collection of cells representing all combinations of spend and incremental outcome across channels. Required. Each channel can have a different spend range, but all spend values within a channel must be spaced evenly using the specified step size.

IncrementalOutcomeGrid.Cell

A data point within the grid representing the outcome of a specific spend on a particular channel.

Field Type Description
spend double The amount of marketing spend allocated to the channel.
incremental_outcome Estimate The incremental outcome achieved through the channel spend. The type should be indicated by the objective in the optimization spec. This is calculated as the difference between the outcome with the given spend and the outcome with zero spend (outcome(spend) - outcome(0)).

IncrementalOutcomeGrid.ChannelCells

A collection of cells in a channel.

Field Type Description
channel_name string The name of the marketing channel.
cells Cell The cells in the channel.

Top

reach_frequency_optimization.proto

FrequencyOutcomeGrid

A message representing a grid that details the outcome of reach frequency by channel.

Note that this grid is constructed under the assumption that there is no interaction effect across channels, i.e. the reach frequency on one channel will not affect other channels.

Field Type Description
name string The name of the grid. Required.
frequency_step_size double The uniform step size between consecutive frequency values within a channel. Required.
channel_cells ChannelCells The collection of cells representing all combinations of reach frequency and outcome across channels. Required.

FrequencyOutcomeGrid.Cell

A data point within the grid representing the outcome of a specific reach frequency on a particular channel.

Field Type Description
reach_frequency ReachFrequency The reach and frequency of the channel.
outcome Estimate The outcome achieved through the channel reach frequency. The type should be indicated by the objective in the optimization spec.

FrequencyOutcomeGrid.ChannelCells

A collection of cells in a channel.

Field Type Description
channel_name string The name of the marketing channel.
cells Cell The cells in the channel.

OptimizedChannelFrequency

Reach frequency optimization result for channel that has reach frequency information.

Field Type Description
channel_name string The name of the channel. Required.
optimal_average_frequency double The optimal average frequency of the channel. Required.

ReachFrequency

Reach and frequency metric.

Field Type Description
reach int64 Reach value. Required.
average_frequency double Average frequency value. Required.

ReachFrequencyOptimization

Field Type Description
results ReachFrequencyOptimizationResult Optimization results for different scenarios.

ReachFrequencyOptimizationResult

Field Type Description
name string The name of the reach frequency optimization. Required.
group_id string An optional identifier for a result that belongs to a group of related results (of different types). Note that no two ReachFrequencyOptimizationResults should share the same group ID. Simple UUID strings are recommended.
spec ReachFrequencyOptimizationSpec The optimization spec used to generate the result. Required.
optimized_channel_frequencies OptimizedChannelFrequency Optimal average frequency results by channel. Required. Media channels without reach frequency data won't be shown.
optimized_marketing_analysis MarketingAnalysis The analysis on marketing outcome when using the optimal channel frequencies. Required. The non-media outcomes are not optimized, but some fields might be impacted by the change of media outcomes. For example, total contribution would change, so the contribution share values have to modified accordingly.
frequency_outcome_grid FrequencyOutcomeGrid Optional grid that describes the outcomes of reach frequency on channels.

ReachFrequencyOptimizationSpec

Field Type Description
date_interval DateInterval The date interval defines the selection of the time points that the optimization is based upon.
objective TargetMetric The objective to maximize in the reach frequency optimization. Required.
kpi_type KpiType The type of KPI used to derive the optimization objective. Required.
target_metric_constraints TargetMetricConstraint The constraints on target metrics (e.g. KPI, ROI, etc).
total_budget_constraint BudgetConstraint The constraint on the total budget.
rf_channel_constraints RfChannelConstraint The constraints on channels that have reach frequency information.

RfChannelConstraint

Channel level constraint for channel that has reach frequency information.

Field Type Description
channel_name string The name of the channel. Required.
budget_constraint BudgetConstraint The budget constraint on the channel.
frequency_constraint FrequencyConstraint The frequency constraint on the channel.

Top

marketing_optimization.proto

MarketingOptimization

Marketing optimization contains all optimization related results.

Field Type Description
budget_optimization BudgetOptimization Budget optimization that contains results for different scenarios.
reach_frequency_optimization ReachFrequencyOptimization Reach frequency optimization that contains results for different scenarios.

Top

mmm_kernel.proto

MmmKernel

Field Type Description
marketing_data MarketingData The marketing data that is used to train the marketing mix model and later analyzed by the model.
model Any The details about the model implementation. This should contain a trained marketing mix model along with model-specific information such as model convergence, flags of model usage.

Top

mmm.proto

Mmm

A schema that contains derived metrics and modeled analysis by a trained marketing mix model.

Field Type Description
mmm_kernel MmmKernel A MMM kernel contains the core information about the model used to generate this output.
model_fit ModelFit Model fit result.
marketing_analysis_list MarketingAnalysisList A list of marketing analysis generated by the MMM kernel.
marketing_optimization MarketingOptimization Marketing optimization on different perspectives using the MMM kernel.

Top

eda_spec.proto

AggregationConfig

A configuration for customizing variable aggregation functions.

Variables not specified will default to SUM.

Field Type Description
control_variables ControlVariablesEntry A map from control variable names to their aggregation functions.
non_media_treatments NonMediaTreatmentsEntry A map from non-media treatment names to their aggregation functions.

AggregationConfig.ControlVariablesEntry

Field Type Description
key string
value AggregationFunction

AggregationConfig.NonMediaTreatmentsEntry

Field Type Description
key string
value AggregationFunction

AggregationFunction

Represents an aggregation function used in EDA.

Field Type Description
function_key string A key that maps to a custom function in the user-provided function registry. The registry allows the EDA spec to be serialized without including the function's code, enabling a more secure deserialization process. Required.

EDASpec

A container for all user-configurable EDA check specs.

Field Type Description
aggregation_config AggregationConfig Configuration for custom variable aggregation functions.
vif_spec VIFSpec Specification for the EDA VIF check.
function_registry FunctionRegistryEntry Lookup table that contains function names mapped to hashed functions used by various aggregation functions.

EDASpec.FunctionRegistryEntry

Field Type Description
key string
value string

VIFSpec

A spec for the EDA VIF check.

Field Type Description
geo_threshold double The threshold for geo-level VIF. (Python default: 1000.0)
overall_threshold double The threshold for overall VIF. (Python default: 1000.0)
national_threshold double The threshold for national VIF. (Python default: 1000.0)

Top

meridian_model.proto

AdstockDecayByChannel

Specifies the adstock decay function for each channel.

Field Type Description
channel_decays ChannelDecaysEntry A map where keys are channel names and values are the adstock decay function to use for that channel. Allowed values are 'geometric' or 'binomial'.

AdstockDecayByChannel.ChannelDecaysEntry

Field Type Description
key string
value string

Distribution

Represents Tensorflow statistical distributions that are used in user priors in a Meridian model. All fields are required unless otherwise specified. See: https://www.tensorflow.org/probability/api_docs/python/tfp/distributions

Field Type Description
name string The canonical name of this distribution in the Meridian model framework.
batch_broadcast BatchBroadcast
deterministic Deterministic
half_normal HalfNormal
log_normal LogNormal
normal Normal
transformed Transformed
truncated_normal TruncatedNormal
uniform Uniform
beta Beta

Distribution.BatchBroadcast

A distribution that broadcasts an underlying distribution's batch shape.

Field Type Description
distribution Distribution The underlying (pre-broadcast) distribution.
batch_shape TensorShapeProto The shape of the broadcast distribution.

Distribution.Beta

A Beta distribution with alpha and beta parameters. See: https://www.tensorflow.org/probability/api_docs/python/tfp/distributions/Beta

Field Type Description
alpha double The alpha parameter of the underlying Beta distribution.
beta double The beta parameter of the underlying Beta distribution.

Distribution.Bijector

Represents Tensorflow bijectors. All fields are required unless otherwise specified. See: https://www.tensorflow.org/probability/api_docs/python/tfp/bijectors

Field Type Description
name string The name of this bijector.
shift Shift
scale Scale
reciprocal Reciprocal

Distribution.Bijector.Reciprocal

A bijector that reciprocates the input.

Distribution.Bijector.Scale

A bijector that scales the input by a scalar or log scale.

Field Type Description
scales double The scale to apply to the input. Should be not be set if log_scales is set.
log_scales double The log scale to apply to the input. Should be not be set if scales is set.

Distribution.Bijector.Shift

A bijector that shifts the input by a scalar.

Field Type Description
shifts double The shift to apply to the input.

Distribution.Deterministic

A scalar deterministic distribution on the real line.

Field Type Description
locs double The batch of points on which this distribution is supported.

Distribution.HalfNormal

A half-normal distribution with scales.

Field Type Description
scales double The scales of the distribution.

Distribution.LogNormal

A log-normal distribution with locs (means) and scales (stddevs).

Field Type Description
locs double The means of the underlying Normal distribution.
scales double The standard deviations of the underlying normal distribution.

Distribution.Normal

A normal distribution with locs (means) and scales (stddevs).

Field Type Description
locs double The means of the underlying Normal distribution.
scales double The standard deviations of the underlying normal distribution. Must contain only positive values.

Distribution.Transformed

A distribution that is transformed by a bijector.

Field Type Description
distribution Distribution The underlying (pre-transformed) distribution.
bijector Bijector The transforming bijector.

Distribution.TruncatedNormal

A truncated Normal distribution, bounded between low and high.

Field Type Description
locs double The means of the underlying Normal distribution.
scales double The standard deviations of the underlying Normal distribution.
low double Lower bound of the distribution's support. Must be less than high.
high double Upper bound of the distribution's support. Must be greater than low.
lows double Lower bounds of the distribution's support. Each value in lows must be less than the corresponding value in highs.
highs double Upper bounds of the distribution's support. Each value in highs must be greater than the corresponding value in lows.

Distribution.Uniform

A uniform distribution on the real line.

Field Type Description
low double Lower boundary of the output interval. Must be less than high.
high double Upper boundary of the output interval. Must be greater than low.
lows double Lower boundaries of the output interval. Each value in lows must be less than the corresponding value in highs.
highs double Upper boundaries of the output interval. Each value in highs must be greater than the corresponding value in lows.

Hyperparameters

Hyperparameters for the MMM model.

Field Type Description
media_effects_dist MediaEffectsDistribution Specifies the distribution of media random effects across geos. This hyperparameter is ignored in a national-level model.
hill_before_adstock bool Indicates whether to apply the Hill function before Adstock function. This hyperparameter does not apply to RF channels.
max_lag uint32 The maximum number of lag periods (>= 0) to include in the Adstock calculation. If unset, then max lag is interpreted as infinite.
unique_sigma_for_each_geo bool Indicates whether to use a unique residual variance for each geo. If False, then a single residual variance is used for all geos.
paid_media_prior_type PaidMediaPriorType Prior type for the media coefficients. If paid_media_prior_type is 'coefficient', then the model usesbeta_[m
media_prior_type PaidMediaPriorType Prior type for the (paid, non-rf) media coefficients. If media_prior_type is 'coefficient', then the model usesbeta_mdistribution in the priors. Ifmedia_prior_type' is 'roi' or 'mroi', then the roi_m or mroi_m is used, respectively. If media_prior_type is 'contribution', then the contribution_m is used.
rf_prior_type PaidMediaPriorType Prior type for the (paid) rf coefficients. If rf_prior_type is 'coefficient', then the model usesbeta_rfdistribution in the priors. Ifrfprior_type' is 'roi' or 'mroi', then the roi_rf or mroi_rf is used, respectively. If rf_prior_type is 'contribution', then the contribution_rf is used.
organic_media_prior_type NonPaidTreatmentsPriorType Prior type for the organic media coefficients. If organic_media_prior_type is 'coefficient', then the model usesbeta_omdistribution in the priors. Iforganic_media_prior_typeis'contribution', then thecontribution_om` is used.
organic_rf_prior_type NonPaidTreatmentsPriorType Prior type for the organic rf coefficients. If organic_rf_prior_type is 'coefficient', then the model usesbeta_orfdistribution in the priors. Iforganic_rf_prior_typeis'contribution', then thecontribution_orf` is used.
non_media_treatments_prior_type NonPaidTreatmentsPriorType Prior type for the non-media treatments coefficients. If non_media_treatments_prior_type is 'coefficient', then the model usesgamma_ndistribution in the priors. Ifnon_media_treatments_prior_typeis'contribution', then thecontribution_n` is used.
roi_calibration_period TensorProto A boolean tensor in the shape (n_media_times, n_media_channels). This indicates the subset of time coordinates in the model for media ROI calibration. If unset, all time coordinates are used for media ROI calibration.
rf_roi_calibration_period TensorProto A boolean tensor in the shape (n_media_times, n_rf_channels). This indicates the subset of time coordinates in the model for reach and frequency ROI calibration. If unset, all time coordinates are used for R&F ROI calibration.
knots int32 A (single-value) integer or a list of integers, indicating the knots used to estimate time effects. If provided as a list of integers, its indices correspond to the indices of the time coordinates in the model. If provided as a single integer, then there are knots with locations equally spaced across time periods. If unset, then the number of knots used is equal to the number of time periods in the case of a geo model (i.e. each time period has its own regression coefficient). If unset in a national model, then the model uses 1 as the number of knots.
enable_aks bool A boolean indicating whether to use the Automatic Knot Selection algorithm to select optimal number of knots for running the model instead of the default 1 for national and n_times for non-national models. If this is set to true and the knots arg is provided, then an error will be raised when deserialized back to ModelSpec. Default: False.
baseline_geo_int_deprecated double Deprecated. Use baseline_geo_int instead.
baseline_geo_int int32 Integer representation of baseline geo.
baseline_geo_string string
holdout_id TensorProto A boolean tensor in the shape (n_geos, n_times) for a geo-level model or (n_times,) for a national model. This indicates which observations are part of the holdout sample, which are excluded from the training sample. For more details on the holdout sample, see: meridian.model.spec.ModelSpec
holdout_ratio double The ratio of holdout data to use for the goodness of fit check. Used as inputs and this will be implemented in training module right before feeding into Meridian. The holdout only applied to date as of Q1 2025.
control_population_scaling_id TensorProto A boolean tensor in the shape (n_controls,). This indicates the control variables for which the control value will be scaled by population. If unset, no control variables are scaled by population.
non_media_population_scaling_id TensorProto A boolean tensor in the shape (n_non_media_channels,). This indicates the non-media treatments channels for which the value will be scaled by population. If unset, no non-media treatments channels are scaled by population.
global_adstock_decay string The global adstock decay function to use for all channels. Allowed values are 'geometric' or 'binomial'.
adstock_decay_by_channel AdstockDecayByChannel Channel-specific adstock decay functions. Defaults to 'geometric' for channels not specified in the map.
non_media_baseline_values NonMediaBaselineValue A list with the 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 function strings "min" or "max" (which mean that the global minimum or maximum value will be used as baseline for the scaled values of the given non_media treatments channel). If None, the minimum value is used as baseline for each non-media treatments channel. This attribute is used as the default value for the corresponding argument to Analyzer methods.

InferenceData

InferenceData data contains none, only prior, or both prior and posterior sampled parameters and their sampling states and trace from fitting the model. https://python.arviz.org/en/stable/api/generated/arviz.InferenceData.html

All fields inside this container are xarray.Datasets that are byte-serialized in NetCDF format. See: https://docs.xarray.dev/en/stable/user-guide/io.html

Field Type Description
prior bytes Sampled prior parameters as an xarray.Dataset serialized in NetCDF4 format.
posterior bytes Sampled posterior parameters as an xarray.Dataset serialized in NetCDF4 format.
auxiliary_data AuxiliaryDataEntry Contains "sample_stats", "trace", and other auxiliary data that are useful for debugging. "sample_stats" and "trace" specifically are available when posterior is available.

InferenceData.AuxiliaryDataEntry

Field Type Description
key string
value bytes

McmcSamplingTrace

The trace of MCMC sampling.

Field Type Description
num_chains uint32
num_draws uint32
step_size TensorProto
tune TensorProto
target_log_prob TensorProto
diverging TensorProto
accept_ratio TensorProto
n_steps TensorProto
is_accepted TensorProto

MeridianModel

Meridian model schema.

Field Type Description
model_id string The unique identifier of this model.
model_version string The semantic version of the Meridian library used to generate this model.
hyperparameters Hyperparameters
prior_distributions PriorDistributions
prior_tfp_distributions PriorTfpDistributions
inference_data InferenceData Inference data contains sampled priors and posteriors.
convergence_info ModelConvergence Contains the information about model convergence status.
eda_spec EDASpec User-configurable EDA check specs.

ModelConvergence

Field Type Description
mcmc_sampling_trace McmcSamplingTrace
convergence bool Convergence heuristic check for the MCMC sampling.
r_hat_diagnostic RHatDiagnostic

NonMediaBaselineValue

A container for non-media baseline function or float values. If float, then that value is used as the baseline for all non-media channels. Otherwise, the min or max value is used as the baseline for the corresponding non-media channel.

Field Type Description
value float
function_value NonMediaBaselineFunction

Parameter

A named tensor parameter.

Field Type Description
name string
tensor TensorProto

PriorDistributions

A container for user prior distribution parameters in a Meridian model. These distributions are in their mathematical forms when representing user priors in the model spec and are part of the user input in a pre-fitted model.

After priors sampling, these distributions are broadcast and should all contain Distribution.BatchBroadcast types.

All parameter distributions are optional. If a distribution is left unspecified for a given parameter, Meridian will select its default prior distribution.

See: meridian.model.prior_distribution module. See: https://developers.google.com/meridian/docs/advanced-modeling/default-prior-distributions

Field Type Description
knot_values Distribution
tau_g_excl_baseline Distribution
beta_m Distribution
beta_rf Distribution
eta_m Distribution
eta_rf Distribution
gamma_c Distribution
xi_c Distribution
alpha_m Distribution
alpha_rf Distribution
ec_m Distribution
ec_rf Distribution
slope_m Distribution
slope_rf Distribution
sigma Distribution
roi_m Distribution
roi_rf Distribution
mroi_m Distribution
mroi_rf Distribution
contribution_m Distribution
contribution_rf Distribution
contribution_om Distribution
contribution_orf Distribution
contribution_n Distribution
beta_om Distribution
beta_orf Distribution
eta_om Distribution
eta_orf Distribution
gamma_n Distribution
xi_n Distribution
alpha_om Distribution
alpha_orf Distribution
ec_om Distribution
ec_orf Distribution
slope_om Distribution
slope_orf Distribution

PriorTfpDistributions

A container for user prior distribution parameters in a Meridian model. These distributions are in their mathematical forms when representing user priors in the model spec and are part of the user input in a pre-fitted model.

After priors sampling, these distributions are broadcast and should all contain Distribution.BatchBroadcast types.

All parameter distributions are optional. If a distribution is left unspecified for a given parameter, Meridian will select its default prior distribution.

See: meridian.model.prior_distribution module. See: https://developers.google.com/meridian/docs/advanced-modeling/default-prior-distributions

Field Type Description
knot_values TfpDistribution
tau_g_excl_baseline TfpDistribution
beta_m TfpDistribution
beta_rf TfpDistribution
eta_m TfpDistribution
eta_rf TfpDistribution
gamma_c TfpDistribution
xi_c TfpDistribution
alpha_m TfpDistribution
alpha_rf TfpDistribution
ec_m TfpDistribution
ec_rf TfpDistribution
slope_m TfpDistribution
slope_rf TfpDistribution
sigma TfpDistribution
roi_m TfpDistribution
roi_rf TfpDistribution
mroi_m TfpDistribution
mroi_rf TfpDistribution
contribution_m TfpDistribution
contribution_rf TfpDistribution
contribution_om TfpDistribution
contribution_orf TfpDistribution
contribution_n TfpDistribution
beta_om TfpDistribution
beta_orf TfpDistribution
eta_om TfpDistribution
eta_orf TfpDistribution
gamma_n TfpDistribution
xi_n TfpDistribution
alpha_om TfpDistribution
alpha_orf TfpDistribution
ec_om TfpDistribution
ec_orf TfpDistribution
slope_om TfpDistribution
slope_orf TfpDistribution
function_registry FunctionRegistryEntry Lookup table that contains function names mapped to hashed functions used by various tfp.distributions.

PriorTfpDistributions.FunctionRegistryEntry

Field Type Description
key string
value string

RHatDiagnostic

Diagnostic of MCMC sampling by computing r_hat value for each parameters.

Field Type Description
parameter_r_hats Parameter The r-hat values of model parameters. Current list of parameters: (see InferenceData.parameters above)

TfpBijector

Represents a constructor parameter for a tfp.bijectors class. All fields are required unless otherwise specified. See: https://www.tensorflow.org/probability/api_docs/python/tfp/bijectors

Field Type Description
bijector_type string A tfp.bijectors class name. e.g. "Shift", "Scale", etc.
parameters ParametersEntry Parameters for the specific bijector type.

TfpBijector.ParametersEntry

Field Type Description
key string
value TfpParameterValue

TfpDistribution

Represents TensorFlow statistical distribution spec that are used in user priors in a Meridian model. All fields are required unless otherwise specified. See: https://www.tensorflow.org/probability/api_docs/python/tfp/distributions

Field Type Description
distribution_type string A tfp.distributions class name. e.g. "Normal", "TransformedDistribution", etc.
parameters ParametersEntry Parameters for the specific distribution type.

TfpDistribution.ParametersEntry

Field Type Description
key string
value TfpParameterValue

TfpParameterValue

Represents a constructor parameter for a tfp.distributions class.

Field Type Description
scalar_value float Primitive distribution parameter value types.
int_value int32
bool_value bool
string_value string
none_value bool
distribution_value TfpDistribution For nested distribution parameter (e.g. for TransformedDistribution)
bijector_value TfpBijector For nested bijector parameter (e.g. for TransformedDistribution)
list_value List For a parameter that takes a list of parameters.
dict_value Dict For a parameter that takes a dict.
tensor_value TensorProto For a parameter that takes a Tensor.
fully_reparameterized bool Whether the distribution should be fully reparameterized. See: https://www.tensorflow.org/probability/api_docs/python/tfp/distributions/ReparameterizationType
function_param FunctionParam For a parameter that takes a function.

TfpParameterValue.Dict

For parameter values that are dicts.

Field Type Description
value_map ValueMapEntry

TfpParameterValue.Dict.ValueMapEntry

Field Type Description
key string
value TfpParameterValue

TfpParameterValue.FunctionParam

For parameter values that are functions.

Field Type Description
function_key string A key that maps to a custom function in the user-provided function registry. The registry allows the model to be serialized without including the function's code, enabling a more secure deserialization process.
uses_default bool Whether the Distribution uses the default function implementation.

TfpParameterValue.List

For parameter values that are lists or tuples.

Field Type Description
values TfpParameterValue

MediaEffectsDistribution

Possible distribution types for media random effects across geos.

Name Number Description
MEDIA_EFFECTS_DISTRIBUTION_UNSPECIFIED 0
NORMAL 1
LOG_NORMAL 2

NonMediaBaselineValue.NonMediaBaselineFunction

Possible non-media baseline function values. If used, then the min or max value of the non-media treatment is used as the baseline for the corresponding non-media channel instead of a fixed, user-specified value.

Name Number Description
NON_MEDIA_BASELINE_FUNCTION_UNSPECIFIED 0
MIN 1
MAX 2

NonPaidTreatmentsPriorType

Possible non-paid treatments prior types.

Name Number Description
NON_PAID_TREATMENTS_PRIOR_TYPE_UNSPECIFIED 0
NON_PAID_TREATMENTS_PRIOR_TYPE_COEFFICIENT 1
NON_PAID_TREATMENTS_PRIOR_TYPE_CONTRIBUTION 2

PaidMediaPriorType

Possible paid media prior types.

Name Number Description
PAID_MEDIA_PRIOR_TYPE_UNSPECIFIED 0
ROI 1
MROI 2
COEFFICIENT 3
CONTRIBUTION 4

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-08 UTC.