Document MMM schema.

PiperOrigin-RevId: 786067236

Author: ronellecaguioa

meridian/__init__.py

@@ -13,11 +13,13 @@
 # limitations under the License.
 
 """Meridian API."""
+
 from meridian import analysis
 from meridian import data
 from meridian import model
 from meridian.version import __version__
 
+
 try:
   from meridian import mlflow  # pylint: disable=g-import-not-at-top
 except ImportError:

proto/README.md

@@ -0,0 +1,20 @@
+# About MMM Proto Schema
+
+The MMM Proto Schema is a framework-agnostic data standard that provides a
+consistent and serializable way to represent a trained Marketing Mix Model
+(MMM). Its core purpose is to establish a common language for the outputs of an
+MMM, primarily within its current Python-centric implementation. This allows the
+results from models built using various tools or methodologies to be uniformly
+represented, stored, shared, and compared by Python-based applications and
+workflows. By offering this standardized representation, the schema aims to
+enhance interoperability and facilitate downstream applications, such as scenario
+planning, optimization, and consistent reporting, independent of how the original
+model was constructed.
+
+## Install Meridian with MMM Proto Schema
+Currently, this package can only be installed from source code:
+```sh
+git clone https://github.com/google/meridian.git;
+cd meridian;
+pip install .[schema];
+```

proto/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 2025 The Meridian Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Module for MMM Proto Schema."""
+
+__version__ = "1.0.0"

proto/mmm/v1/common/date_interval.proto

@@ -0,0 +1,33 @@
+// Copyright 2025 The Meridian Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+edition = "2023";
+
+package mmm.v1.common;
+
+import "google/type/date.proto";
+
+option features.field_presence = IMPLICIT;
+option java_multiple_files = true;
+
+message DateInterval {
+  // The start date of the interval. Inclusive. Required.
+  google.type.Date start_date = 1;
+
+  // The end date of the interval. Exclusive. Required.
+  google.type.Date end_date = 2;
+
+  // A tag to identify the date interval. Optional.
+  string tag = 3;
+}

proto/mmm/v1/common/estimate.proto

@@ -0,0 +1,43 @@
+// Copyright 2025 The Meridian Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+edition = "2023";
+
+package mmm.v1.common;
+
+option features.field_presence = IMPLICIT;
+option java_multiple_files = true;
+
+// Contains an estimate value of estimand and associated quantified
+// uncertainties.
+message Estimate {
+  // The estimate value of an estimand. Required.
+  double value = 1;
+
+  // The uncertainty of an estimate quantified by probability interval.
+  message Uncertainty {
+    // The probability that a value is inside an interval bounded by lowerbound
+    // and upperbound. Required.
+    double probability = 1;
+
+    // The lowerbound of the interval. Required.
+    double lowerbound = 2;
+
+    // The upperbound of the interval. Required.
+    double upperbound = 3;
+  }
+
+  // The quantified uncertainties.
+  repeated Uncertainty uncertainties = 2;
+}

proto/mmm/v1/common/kpi_type.proto

@@ -0,0 +1,31 @@
+// Copyright 2025 The Meridian Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+edition = "2023";
+
+package mmm.v1.common;
+
+option java_multiple_files = true;
+
+// Different KPI types used in marketing performance and optimization.
+enum KpiType {
+  KPI_TYPE_UNSPECIFIED = 0;
+
+  // Some generic user-defined KPI unit.
+  NON_REVENUE = 1;
+
+  // KPI defined as revenue specifically, or some KPI unit after conversion
+  // to revenue.
+  REVENUE = 2;
+}

proto/mmm/v1/common/target_metric.proto

@@ -0,0 +1,41 @@
+// Copyright 2025 The Meridian Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+edition = "2023";
+
+package mmm.v1.common;
+
+option java_multiple_files = true;
+
+// 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`.
+enum TargetMetric {
+  TARGET_METRIC_UNSPECIFIED = 0;
+
+  // Any KPI type (revenue if the model data can be converted to revenue, or
+  // some generic KPI otherwise).
+  KPI = 1;
+
+  // ROI = net KPI change / spend.
+  ROI = 2;
+
+  // Marginal ROI is defined at channel level and is applied across all
+  // channels.
+  // mROI = changed in incremental KPI / spend.
+  MARGINAL_ROI = 3;
+
+  // CPIK = total spend / change in incremental KPI.
+  COST_PER_INCREMENTAL_KPI = 4;
+}

proto/mmm/v1/fit/model_fit.proto

@@ -0,0 +1,70 @@
+// Copyright 2025 The Meridian Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+edition = "2023";
+
+package mmm.v1.fit;
+
+import "mmm/v1/common/date_interval.proto";
+import "mmm/v1/common/estimate.proto";
+
+option features.field_presence = IMPLICIT;
+option java_multiple_files = true;
+
+// A prediction contains the predicted KPI and the ground truth at a specific
+// time.
+message Prediction {
+  // The time associated to this prediction point. Required.
+  common.DateInterval date_interval = 1;
+
+  // The predicted outcome. Required.
+  common.Estimate predicted_outcome = 2;
+
+  // The predicted baseline. Optional.
+  common.Estimate predicted_baseline = 3;
+
+  // The actual value observed in the data. Required.
+  double actual_value = 4;
+}
+
+// The model fit performance indicated by different metrics.
+message Performance {
+  double r_squared = 1;
+
+  // Mean absolute percentage error.
+  double mape = 2;
+
+  // Is equal to sum_i(actual_i - pred_i) / sum_i(actual_i)
+  double weighted_mape = 3;
+
+  // Root mean square error.
+  double rmse = 4;
+}
+
+message Result {
+  // The name of the result. Required.
+  string name = 1;
+
+  // The predictions over different times. Required.
+  repeated Prediction predictions = 2;
+
+  // The performance of the model fit. Required.
+  Performance performance = 3;
+}
+
+message ModelFit {
+  // Different results for different purposes. For example, one could divide a
+  // data to training set, testing set, and validation set. Required.
+  repeated Result results = 1;
+}

proto/mmm/v1/marketing/analysis/kpi_outcome.proto

@@ -0,0 +1,77 @@
+// Copyright 2025 The Meridian Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+edition = "2023";
+
+package mmm.v1.marketing.analysis;
+
+import "mmm/v1/common/estimate.proto";
+import "mmm/v1/common/kpi_type.proto";
+
+option features.field_presence = IMPLICIT;
+option java_multiple_files = true;
+
+// A contribution is defined as the value difference caused by adding a new
+// outcome.
+message Contribution {
+  // The contribution value. Required.
+  common.Estimate value = 1;
+
+  // Share of contribution = contribution / total contribution from all
+  // outcomes.
+  common.Estimate share = 2;
+}
+
+// Effectiveness calculates how much incremental KPI is generated per media unit
+// (e.g. impressions or clicks), i.e. contribution / media unit.
+message Effectiveness {
+  // The media unit of the effectiveness. Required.
+  string media_unit = 1;
+
+  // The value of the effectiveness. Required.
+  common.Estimate value = 2;
+}
+
+// An outcome analysis on KPI which can be defined as revenue or other generic
+// non-revenue type.
+message KpiOutcome {
+  // 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.
+  common.KpiType kpi_type = 1;
+
+  // 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.
+  Contribution contribution = 2;
+
+  // The effectiveness of this outcome.
+  Effectiveness effectiveness = 3;
+
+  // ROI = contribution / spend.
+  // See contribution definition above.
+  common.Estimate roi = 4;
+
+  // Marginal ROI shows the additional ROI gained from additional spend.
+  // See ROI definition above.
+  common.Estimate marginal_roi = 5;
+
+  // 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.
+  common.Estimate cost_per_contribution = 6;
+}

proto/mmm/v1/marketing/analysis/marketing_analysis.proto

@@ -0,0 +1,41 @@
+// Copyright 2025 The Meridian Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+edition = "2023";
+
+package mmm.v1.marketing.analysis;
+
+import "mmm/v1/common/date_interval.proto";
+import "mmm/v1/marketing/analysis/media_analysis.proto";
+import "mmm/v1/marketing/analysis/non_media_analysis.proto";
+
+option java_multiple_files = true;
+
+// The marketing analysis.
+message MarketingAnalysis {
+  // The date interval that the analysis covers. Required.
+  common.DateInterval date_interval = 1;
+
+  // Analysis on different media channels. Required.
+  repeated MediaAnalysis media_analyses = 2;
+
+  // Analysis on different non-media factors.
+  repeated NonMediaAnalysis non_media_analyses = 3;
+}
+
+// A list of marketing analyses.
+message MarketingAnalysisList {
+  // The marketing analyses for different time ranges. Required.
+  repeated MarketingAnalysis marketing_analyses = 1;
+}