google-meridian 1.3.1__py3-none-any.whl → 1.4.0__py3-none-any.whl

scenarioplanner/converters/dataframe/budget_opt_converters.py

@@ -0,0 +1,383 @@
+# 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.
+
+"""Budget optimization converters.
+
+This module defines various classes that convert `BudgetOptimizationResult`s
+into flat dataframes.
+"""
+
+import abc
+from collections.abc import Iterator, Sequence
+
+from meridian import constants as c
+from mmm.v1.marketing.optimization import budget_optimization_pb2 as budget_pb
+from mmm.v1.marketing.optimization import constraints_pb2 as constraints_pb
+from scenarioplanner.converters import mmm
+from scenarioplanner.converters.dataframe import common
+from scenarioplanner.converters.dataframe import constants as dc
+from scenarioplanner.converters.dataframe import converter
+import pandas as pd
+
+
+__all__ = [
+    "NamedOptimizationGridConverter",
+    "BudgetOptimizationSpecsConverter",
+    "BudgetOptimizationResultsConverter",
+    "BudgetOptimizationResponseCurvesConverter",
+]
+
+
+class _BudgetOptimizationConverter(converter.Converter, abc.ABC):
+  """An abstract class for dealing with `BudgetOptimizationResult`s."""
+
+  def __call__(self) -> Iterator[tuple[str, pd.DataFrame]]:
+    results = self._mmm.budget_optimization_results
+    if not results:
+      return
+
+    # Validate group IDs.
+    group_ids = [result.group_id for result in results if result.group_id]
+    if len(set(group_ids)) != len(group_ids):
+      raise ValueError(
+          "Specified group_id must be unique or unset among the given group of"
+          " results."
+      )
+
+    yield from self._handle_budget_optimization_results(
+        self._mmm.budget_optimization_results
+    )
+
+  def _handle_budget_optimization_results(
+      self, results: Sequence[mmm.BudgetOptimizationResult]
+  ) -> Iterator[tuple[str, pd.DataFrame]]:
+    raise NotImplementedError()
+
+
+class NamedOptimizationGridConverter(_BudgetOptimizationConverter):
+  """Outputs named tables for budget optimization grids.
+
+  When called, this converter returns a data frame with the columns:
+
+  *   "Group ID"
+      A UUID generated for each named incremental outcome grid.
+  *   "Channel"
+  *   "Spend"
+  *   "Incremental Outcome"
+  For each named budget optimization result in the MMM output proto.
+  """
+
+  def _handle_budget_optimization_results(
+      self, results: Sequence[mmm.BudgetOptimizationResult]
+  ) -> Iterator[tuple[str, pd.DataFrame]]:
+    for budget_opt_result in results:
+      # There should be one unique ID for each result.
+      group_id = (
+          str(budget_opt_result.group_id) if budget_opt_result.group_id else ""
+      )
+      grid = budget_opt_result.incremental_outcome_grid
+
+      # Each grid yields its own data frame table.
+      optimization_grid_data = []
+      for channel, cells in grid.channel_spend_grids.items():
+        for spend, incremental_outcome in cells:
+          optimization_grid_data.append([
+              group_id,
+              channel,
+              spend,
+              incremental_outcome,
+          ])
+
+      yield (
+          common.create_grid_sheet_name(
+              dc.OPTIMIZATION_GRID_NAME_PREFIX, grid.name
+          ),
+          pd.DataFrame(
+              optimization_grid_data,
+              columns=[
+                  dc.OPTIMIZATION_GROUP_ID_COLUMN,
+                  dc.OPTIMIZATION_CHANNEL_COLUMN,
+                  dc.OPTIMIZATION_GRID_SPEND_COLUMN,
+                  dc.OPTIMIZATION_GRID_INCREMENTAL_OUTCOME_COLUMN,
+              ],
+          ),
+      )
+
+
+class BudgetOptimizationSpecsConverter(_BudgetOptimizationConverter):
+  """Outputs a table of budget optimization specs.
+
+  When called, this converter returns a data frame with the columns:
+
+  *   "Group ID"
+      A UUID generated for an incremental outcome grid present in the output.
+  *   "Date Interval Start"
+  *   "Date Interval End"
+  *   "Analysis Period"
+  *   "Objective"
+  *   "Scenario Type"
+  *   "Initial Channel Spend"
+  *   "Target Metric Constraint"
+      None if scenario type is "Fixed"
+  *   "Target Metric Value"
+      None if scenario type is "Fixed"
+  *   "Channel"
+  *   "Channel Spend Min"
+  *   "Channel Spend Max"
+  """
+
+  def _handle_budget_optimization_results(
+      self, results: Sequence[mmm.BudgetOptimizationResult]
+  ) -> Iterator[tuple[str, pd.DataFrame]]:
+    spec_data = []
+    for budget_opt_result in results:
+      # There should be one unique ID for each result.
+      group_id = (
+          str(budget_opt_result.group_id) if budget_opt_result.group_id else ""
+      )
+      spec = budget_opt_result.spec
+
+      objective = common.map_target_metric_str(spec.objective)
+      # These are the start and end dates for the requested budget optimization
+      # in this spec.
+      date_interval_start, date_interval_end = (
+          d.strftime(c.DATE_FORMAT) for d in spec.date_interval.date_interval
+      )
+      budget_date_interval = (date_interval_start, date_interval_end)
+
+      # aka historical spend from marketing data in the model kernel
+      initial_channel_spends = self._mmm.marketing_data.all_channel_spends(
+          budget_date_interval
+      )
+
+      scenario = (
+          dc.OPTIMIZATION_SPEC_SCENARIO_FIXED
+          if spec.is_fixed_scenario
+          else dc.OPTIMIZATION_SPEC_SCENARIO_FLEXIBLE
+      )
+
+      if spec.is_fixed_scenario:
+        target_metric_constraint = None
+        target_metric_value = None
+      else:
+        flexible_scenario = (
+            spec.budget_optimization_spec_proto.flexible_budget_scenario
+        )
+        # Meridian flexible budget spec only has one target metric constraint.
+        target_metric_constraint_pb = (
+            flexible_scenario.target_metric_constraints[0]
+        )
+        target_metric_constraint = common.map_target_metric_str(
+            target_metric_constraint_pb.target_metric
+        )
+        target_metric_value = target_metric_constraint_pb.target_value
+
+      # When the constraint of a channel is not specified, that channel will
+      # have a constraint of `[0, max_budget]` which is equivalent to no
+      # constraint.
+      #
+      # Here, `max_budget` is the total budget for a fixed scenario spec, or the
+      # max budget upper bound for a flexible scenario spec.
+      #
+      # NOTE: This assumption must be in line with what the budget optimization
+      # processor does with an empty channel constraints list.
+      channel_constraints = spec.channel_constraints
+      if not channel_constraints:
+        # Implicit channel constraints; synthesize them first before proceeding.
+        channel_constraints = [
+            budget_pb.ChannelConstraint(
+                channel_name=channel_name,
+                budget_constraint=constraints_pb.BudgetConstraint(
+                    min_budget=0.0,
+                    max_budget=spec.max_budget,
+                ),
+            )
+            for channel_name in self._mmm.marketing_data.media_channels
+        ]
+
+      for channel_constraint in channel_constraints:
+        spec_data.append([
+            group_id,
+            date_interval_start,
+            date_interval_end,
+            spec.date_interval_tag,
+            objective,
+            scenario,
+            initial_channel_spends.get(channel_constraint.channel_name, 0.0),
+            target_metric_constraint,
+            target_metric_value,
+            channel_constraint.channel_name,
+            channel_constraint.budget_constraint.min_budget,
+            channel_constraint.budget_constraint.max_budget,
+        ])
+
+    yield (
+        dc.OPTIMIZATION_SPECS,
+        pd.DataFrame(
+            spec_data,
+            columns=[
+                dc.OPTIMIZATION_GROUP_ID_COLUMN,
+                dc.OPTIMIZATION_SPEC_DATE_INTERVAL_START_COLUMN,
+                dc.OPTIMIZATION_SPEC_DATE_INTERVAL_END_COLUMN,
+                dc.ANALYSIS_PERIOD_COLUMN,
+                dc.OPTIMIZATION_SPEC_OBJECTIVE_COLUMN,
+                dc.OPTIMIZATION_SPEC_SCENARIO_TYPE_COLUMN,
+                dc.OPTIMIZATION_SPEC_INITIAL_CHANNEL_SPEND_COLUMN,
+                dc.OPTIMIZATION_SPEC_TARGET_METRIC_CONSTRAINT_COLUMN,
+                dc.OPTIMIZATION_SPEC_TARGET_METRIC_VALUE_COLUMN,
+                dc.OPTIMIZATION_CHANNEL_COLUMN,
+                dc.OPTIMIZATION_SPEC_CHANNEL_SPEND_MIN_COLUMN,
+                dc.OPTIMIZATION_SPEC_CHANNEL_SPEND_MAX_COLUMN,
+            ],
+        ),
+    )
+
+
+class BudgetOptimizationResultsConverter(_BudgetOptimizationConverter):
+  """Outputs a table of budget optimization results objectives.
+
+  When called, this converter returns a data frame with the columns:
+
+  *   "Group ID"
+      A UUID generated for a budget optimization result present in the output.
+  *   "Channel"
+  *   "Is Revenue KPI"
+      Whether the KPI is revenue or not.
+  *   "Optimal Spend"
+  *   "Optimal Spend Share"
+  *   "Optimal Impression Effectiveness"
+  *   "Optimal ROI"
+  *   "Optimal mROI"
+  *   "Optimal CPC"
+  """
+
+  def _handle_budget_optimization_results(
+      self, results: Sequence[mmm.BudgetOptimizationResult]
+  ) -> Iterator[tuple[str, pd.DataFrame]]:
+    data = []
+
+    for budget_opt_result in results:
+      group_id = (
+          str(budget_opt_result.group_id) if budget_opt_result.group_id else ""
+      )
+      marketing_analysis = budget_opt_result.optimized_marketing_analysis
+
+      media_channel_analyses = marketing_analysis.channel_mapped_media_analyses
+      for channel, media_analysis in media_channel_analyses.items():
+        # Skip "All Channels" pseudo-channel.
+        if channel == c.ALL_CHANNELS:
+          continue
+
+        spend = media_analysis.spend_info_pb.spend
+        spend_share = media_analysis.spend_info_pb.spend_share
+
+        revenue_outcome = media_analysis.maybe_revenue_outcome
+        nonrevenue_outcome = media_analysis.maybe_non_revenue_outcome
+
+        # pylint: disable=cell-var-from-loop
+        def _append_outcome_data(
+            outcome: mmm.Outcome | None,
+            is_revenue_kpi: bool,
+        ) -> None:
+          if outcome is None:
+            return
+          effectiveness = outcome.effectiveness_pb.value.value
+          roi = outcome.roi_pb.value
+          mroi = outcome.marginal_roi_pb.value
+          cpc = outcome.cost_per_contribution_pb.value
+          data.append([
+              group_id,
+              channel,
+              is_revenue_kpi,
+              spend,
+              spend_share,
+              effectiveness,
+              roi,
+              mroi,
+              cpc,
+          ])
+
+        _append_outcome_data(revenue_outcome, True)
+        _append_outcome_data(nonrevenue_outcome, False)
+        # pylint: enable=cell-var-from-loop
+
+    yield (
+        dc.OPTIMIZATION_RESULTS,
+        pd.DataFrame(
+            data,
+            columns=[
+                dc.OPTIMIZATION_GROUP_ID_COLUMN,
+                dc.OPTIMIZATION_CHANNEL_COLUMN,
+                dc.OPTIMIZATION_RESULT_IS_REVENUE_KPI_COLUMN,
+                dc.OPTIMIZATION_RESULT_SPEND_COLUMN,
+                dc.OPTIMIZATION_RESULT_SPEND_SHARE_COLUMN,
+                dc.OPTIMIZATION_RESULT_EFFECTIVENESS_COLUMN,
+                dc.OPTIMIZATION_RESULT_ROI_COLUMN,
+                dc.OPTIMIZATION_RESULT_MROI_COLUMN,
+                dc.OPTIMIZATION_RESULT_CPC_COLUMN,
+            ],
+        ),
+    )
+
+
+class BudgetOptimizationResponseCurvesConverter(_BudgetOptimizationConverter):
+  """Outputs a table of budget optimization response curves.
+
+  When called, this converter returns a data frame with the columns:
+
+  *   "Group ID"
+      A UUID generated for a budget optimization result present in the output.
+  *   "Channel"
+  *   "Spend"
+  *   "Incremental Outcome"
+  """
+
+  def _handle_budget_optimization_results(
+      self, results: Sequence[mmm.BudgetOptimizationResult]
+  ) -> Iterator[tuple[str, pd.DataFrame]]:
+    response_curve_data = []
+    for budget_opt_result in results:
+      group_id = (
+          str(budget_opt_result.group_id) if budget_opt_result.group_id else ""
+      )
+      curves = budget_opt_result.response_curves
+      for curve in curves:
+        for spend, incremental_outcome in curve.response_points:
+          response_curve_data.append([
+              group_id,
+              curve.channel_name,
+              spend,
+              incremental_outcome,
+          ])
+
+    yield (
+        dc.OPTIMIZATION_RESPONSE_CURVES,
+        pd.DataFrame(
+            response_curve_data,
+            columns=[
+                dc.OPTIMIZATION_GROUP_ID_COLUMN,
+                dc.OPTIMIZATION_CHANNEL_COLUMN,
+                dc.OPTIMIZATION_GRID_SPEND_COLUMN,
+                dc.OPTIMIZATION_GRID_INCREMENTAL_OUTCOME_COLUMN,
+            ],
+        ),
+    )
+
+
+CONVERTERS = [
+    NamedOptimizationGridConverter,
+    BudgetOptimizationSpecsConverter,
+    BudgetOptimizationResultsConverter,
+    BudgetOptimizationResponseCurvesConverter,
+]

scenarioplanner/converters/dataframe/common.py

@@ -0,0 +1,71 @@
+# 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.
+
+"""Common utility functions in this package."""
+
+import re
+
+from mmm.v1.common import target_metric_pb2 as target_metric_pb
+from scenarioplanner.converters.dataframe import constants as dc
+
+
+def map_target_metric_str(metric: target_metric_pb.TargetMetric) -> str:
+  """Maps a TargetMetric enum to a string.
+
+  Args:
+    metric: The TargetMetric enum to map.
+
+  Returns:
+    The string representation of the TargetMetric enum.
+  """
+  match metric:
+    case target_metric_pb.TargetMetric.KPI:
+      return dc.OPTIMIZATION_SPEC_TARGET_METRIC_KPI
+    case target_metric_pb.TargetMetric.ROI:
+      return dc.OPTIMIZATION_SPEC_TARGET_METRIC_ROI
+    case target_metric_pb.TargetMetric.MARGINAL_ROI:
+      return dc.OPTIMIZATION_SPEC_TARGET_METRIC_MARGINAL_ROI
+    case target_metric_pb.TargetMetric.COST_PER_INCREMENTAL_KPI:
+      return dc.OPTIMIZATION_SPEC_TARGET_METRIC_CPIK
+    case _:
+      raise ValueError(f"Unsupported target metric: {metric}")
+
+
+def _to_sheet_name_format(s: str) -> str:
+  """Converts a string to a sheet name format.
+
+  Replace consecutive spaces with a single underscore using regex.
+
+  Args:
+    s: The string to convert.
+
+  Returns:
+    The converted sheet name.
+  """
+  return re.sub(r"\s+", dc.SHEET_NAME_DELIMITER, s)
+
+
+def create_grid_sheet_name(prefix: str, grid_name: str) -> str:
+  """Creates a grid sheet name with the given prefix and grid name.
+
+  Args:
+    prefix: The prefix of the sheet name.
+    grid_name: The name of the grid.
+
+  Returns:
+    The grid sheet name.
+  """
+  grid_sheet_name = _to_sheet_name_format(grid_name)
+  sheet_prefix = _to_sheet_name_format(prefix)
+  return f"{sheet_prefix}_{grid_sheet_name}"

scenarioplanner/converters/dataframe/constants.py

@@ -0,0 +1,137 @@
+# 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.
+
+"""Dataframe converter constants."""
+
+SHEET_NAME_DELIMITER = "_"
+
+# Special analysis aggregation tags.
+ANALYSIS_TAG_ALL = "ALL"
+
+# ModelFit table column names
+MODEL_FIT = "ModelFit"
+MODEL_FIT_TIME_COLUMN = "Time"
+MODEL_FIT_EXPECTED_CI_LOW_COLUMN = "Expected CI Low"
+MODEL_FIT_EXPECTED_CI_HIGH_COLUMN = "Expected CI High"
+MODEL_FIT_EXPECTED_COLUMN = "Expected"
+MODEL_FIT_BASELINE_COLUMN = "Baseline"
+MODEL_FIT_ACTUAL_COLUMN = "Actual"
+
+# ModelDiagnostics table column names
+MODEL_DIAGNOSTICS = "ModelDiagnostics"
+MODEL_DIAGNOSTICS_DATASET_COLUMN = "Dataset"
+MODEL_DIAGNOSTICS_R_SQUARED_COLUMN = "R Squared"
+MODEL_DIAGNOSTICS_MAPE_COLUMN = "MAPE"
+MODEL_DIAGNOSTICS_WMAPE_COLUMN = "wMAPE"
+
+# Common column names
+ANALYSIS_PERIOD_COLUMN = "Analysis Period"
+ANALYSIS_DATE_START_COLUMN = "Analysis Date Start"
+ANALYSIS_DATE_END_COLUMN = "Analysis Date End"
+
+# MediaOutcome table column names
+MEDIA_OUTCOME = "MediaOutcome"
+MEDIA_OUTCOME_CHANNEL_INDEX_COLUMN = "Channel Index"
+MEDIA_OUTCOME_CHANNEL_COLUMN = "Channel"
+MEDIA_OUTCOME_INCREMENTAL_OUTCOME_COLUMN = "Incremental Outcome"
+MEDIA_OUTCOME_CONTRIBUTION_SHARE_COLUMN = "Contribution Share"
+MEDIA_OUTCOME_BASELINE_PSEUDO_CHANNEL_INDEX = 0
+MEDIA_OUTCOME_ALL_CHANNELS_PSEUDO_CHANNEL_INDEX = 1
+MEDIA_OUTCOME_CHANNEL_INDEX = 2
+
+# MediaSpend table column names
+MEDIA_SPEND = "MediaSpend"
+MEDIA_SPEND_CHANNEL_COLUMN = "Channel"
+MEDIA_SPEND_SHARE_VALUE_COLUMN = "Share Value"
+MEDIA_SPEND_LABEL_COLUMN = "Label"
+# The "Label" column enums
+MEDIA_SPEND_LABEL_SPEND_SHARE = "Spend Share"
+MEDIA_SPEND_LABEL_REVENUE_SHARE = "Revenue Share"
+MEDIA_SPEND_LABEL_KPI_SHARE = "KPI Share"
+
+# MediaROI table column names
+MEDIA_ROI = "MediaROI"
+MEDIA_ROI_CHANNEL_COLUMN = "Channel"
+MEDIA_ROI_SPEND_COLUMN = "Spend"
+MEDIA_ROI_EFFECTIVENESS_COLUMN = "Effectiveness"
+MEDIA_ROI_ROI_COLUMN = "ROI"
+MEDIA_ROI_ROI_CI_LOW_COLUMN = "ROI CI Low"
+MEDIA_ROI_ROI_CI_HIGH_COLUMN = "ROI CI High"
+MEDIA_ROI_MARGINAL_ROI_COLUMN = "Marginal ROI"
+MEDIA_ROI_IS_REVENUE_KPI_COLUMN = "Is Revenue KPI"
+
+
+# Shared column names among Optimization tables
+OPTIMIZATION_GROUP_ID_COLUMN = "Group ID"
+OPTIMIZATION_CHANNEL_COLUMN = "Channel"
+
+# Optimization grid table column names
+# (Table name is user-generated from the spec)
+OPTIMIZATION_GRID_SPEND_COLUMN = "Spend"
+OPTIMIZATION_GRID_INCREMENTAL_OUTCOME_COLUMN = "Incremental Outcome"
+
+# R&F Optimization grid table column names
+# (Table name is user-generated from the spec)
+RF_OPTIMIZATION_GRID_FREQ_COLUMN = "Frequency"
+RF_OPTIMIZATION_GRID_ROI_OUTCOME_COLUMN = "ROI"
+
+# Budget optimization grid table name
+OPTIMIZATION_GRID_NAME_PREFIX = "budget_opt_grid"
+
+# R&F optimization grid table name
+RF_OPTIMIZATION_GRID_NAME_PREFIX = "rf_opt_grid"
+
+# Optimization spec table column names and enum values
+OPTIMIZATION_SPECS = "budget_opt_specs"
+OPTIMIZATION_SPEC_DATE_INTERVAL_START_COLUMN = "Date Interval Start"
+OPTIMIZATION_SPEC_DATE_INTERVAL_END_COLUMN = "Date Interval End"
+OPTIMIZATION_SPEC_OBJECTIVE_COLUMN = "Objective"
+OPTIMIZATION_SPEC_SCENARIO_TYPE_COLUMN = "Scenario Type"
+OPTIMIZATION_SPEC_SCENARIO_FIXED = "Fixed"
+OPTIMIZATION_SPEC_SCENARIO_FLEXIBLE = "Flexible"
+OPTIMIZATION_SPEC_INITIAL_CHANNEL_SPEND_COLUMN = "Initial Channel Spend"
+OPTIMIZATION_SPEC_TARGET_METRIC_CONSTRAINT_COLUMN = "Target Metric Constraint"
+OPTIMIZATION_SPEC_TARGET_METRIC_KPI = "KPI"
+OPTIMIZATION_SPEC_TARGET_METRIC_ROI = "ROI"
+OPTIMIZATION_SPEC_TARGET_METRIC_MARGINAL_ROI = "Marginal ROI"
+OPTIMIZATION_SPEC_TARGET_METRIC_CPIK = "Cost per Incremental KPI"
+OPTIMIZATION_SPEC_TARGET_METRIC_VALUE_COLUMN = "Target Metric Value"
+OPTIMIZATION_SPEC_CHANNEL_COLUMN = "Channel"
+OPTIMIZATION_SPEC_CHANNEL_SPEND_MIN_COLUMN = "Channel Spend Min"
+OPTIMIZATION_SPEC_CHANNEL_SPEND_MAX_COLUMN = "Channel Spend Max"
+
+# R&F Optimization spec table column names and enum values
+RF_OPTIMIZATION_SPECS = "rf_opt_specs"
+RF_OPTIMIZATION_SPEC_CHANNEL_FREQUENCY_MIN_COLUMN = "Channel Frequency Min"
+RF_OPTIMIZATION_SPEC_CHANNEL_FREQUENCY_MAX_COLUMN = "Channel Frequency Max"
+
+# Optimization results table column names
+OPTIMIZATION_RESULTS = "budget_opt_results"
+OPTIMIZATION_RESULT_SPEND_COLUMN = "Optimal Spend"
+OPTIMIZATION_RESULT_SPEND_SHARE_COLUMN = "Optimal Spend Share"
+OPTIMIZATION_RESULT_EFFECTIVENESS_COLUMN = "Optimal Impression Effectiveness"
+OPTIMIZATION_RESULT_ROI_COLUMN = "Optimal ROI"
+OPTIMIZATION_RESULT_MROI_COLUMN = "Optimal mROI"
+OPTIMIZATION_RESULT_CPC_COLUMN = "Optimal CPC"
+OPTIMIZATION_RESULT_IS_REVENUE_KPI_COLUMN = "Is Revenue KPI"
+
+# R&F Optimization results table column names
+RF_OPTIMIZATION_RESULTS = "rf_opt_results"
+RF_OPTIMIZATION_RESULT_INITIAL_SPEND_COLUMN = "Initial Spend"
+RF_OPTIMIZATION_RESULT_AVG_FREQ_COLUMN = "Optimal Avg Frequency"
+
+# Optimization results' response curves table column names
+OPTIMIZATION_RESPONSE_CURVES = "response_curves"
+OPTIMIZATION_RESPONSE_CURVE_SPEND_COLUMN = "Spend"
+OPTIMIZATION_RESPONSE_CURVE_INCREMENTAL_OUTCOME_COLUMN = "Incremental Outcome"

scenarioplanner/converters/dataframe/converter.py

@@ -0,0 +1,42 @@
+# 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.
+
+"""`Converter` class for all dataframe converters."""
+
+import abc
+from collections.abc import Iterator
+
+from scenarioplanner.converters import mmm
+import pandas as pd
+
+
+__all__ = ["Converter"]
+
+
+class Converter(abc.ABC):
+  """Converts a trained model and analyses to one or more data frame tables.
+
+  Attributes:
+    mmm: An `Mmm` proto wrapper.
+  """
+
+  def __init__(
+      self,
+      mmm_wrapper: mmm.Mmm,
+  ):
+    self._mmm = mmm_wrapper
+
+  @abc.abstractmethod
+  def __call__(self) -> Iterator[tuple[str, pd.DataFrame]]:
+    raise NotImplementedError()