Using Scenario Planner with new_data for future budget optimization

[pln6]

Hi everyone,
I’m currently working with the Meridian Scenario Planner and exploring whether it can be used for future budget scenario planning by providing new_data.
My goal is to simulate and optimize future budget allocations beyond the original training period.

However, when I define a BudgetOptimizationSpec and run:

mmm_proto = mmm_ui_gen.create_mmm_ui_data_proto(...)

I encounter the following error:

ValueError: start_date (2023-01-02) must be in the time coordinates!

From the traceback, the issue seems to occur when expanding selected time dimensions:

time_coordinates.expand_selected_time_dims(...)

Questions
1. Is it currently supported to use Scenario Planner with new_data for future periods outside the original model time coordinates?

2. If forward-looking scenario planning is supported:

• what is the correct way to align start_date / end_date with new_data.time?
• are there any specific requirements for how new_data.time should be structured?

Any clarification or guidance would be greatly appreciated!

Thanks in advance 🙌

[cpulavarthi]

Hello @pln6,

Thank you for contacting us and for your patience while we investigated your concerns!

I would like to inform you that the new_data argument in the Scenario Planner doesn't currently support out-of-sample forward forecasts. A new guardrail has been added to MMMUiProtoGenerator which acts as a validation check and will raise a ValueError whenever date ranges beyond historical data are used so that this limitation is clearly communicated and avoids future confusion.

ValueError: Scenario Planner UI proto generation does not support out-of-sample dates (start_date 2023-01-02 is outside training history [..., ...]). To perform forward-looking budget optimization with `new_data`, please use `Meridian.budget_optimizer.optimize()` directly.

As for the functionality for new-data-with-future-dates in the Meridian Scenario Planner (dashboard), we are taking this as a feature request and the exact implementation timeline for this feature cannot be provided at the moment. You can track the previous changes to Meridian and unreleased feature updates in our Change Log which will be updated accordingly.

We do have a couple of programmatic alternatives for "forward-looking optimization":

• Option A: Core Optimizer API (Recommended for standard workflows): You can directly invoke optimize() on the model's budget optimizer in Python, passing their counterfactual new_data container:

  from meridian.analysis import optimizer
  from meridian.analysis import tensors
  
  # 1. Define future counterfactual data tensors (must include new_data.time)
  future_data = tensors.DataTensors(
      time=["2023-01-02", "2023-01-09", ...],
      media=...,
      # include other required tensors as needed
  )
  
  # 2. Run budget optimization conditional on the future data
  opt_results = mmm.budget_optimizer.optimize(
      start_date="2023-01-02",
      end_date="2023-03-27",
      fixed_budget=True,
      new_data=future_data,
      confidence_level=0.9,
  )

• Option B: Direct Processor Invocation (Advanced / Custom BI Pipelines): If you specifically requires the structured protobuf outputs or precomputed IncrementalOutcomeGrid that Scenario Planner generates behind the scenes, you can bypass the UI proto generator (create_mmm_ui_data_proto) and invoke BudgetOptimizationProcessor directly in Python (see meridian.schema.processors.budget_optimization_processor for reference):

  from meridian.schema.processors import budget_optimization_processor
  from meridian.analysis import optimizer
  from meridian.schema.processors import common
  
  spec = budget_optimization_processor.BudgetOptimizationSpec(
      optimization_name="future_budget_scenario",
      start_date=datetime.date(2023, 1, 2),
      end_date=datetime.date(2023, 3, 27),
      scenario=optimizer.FixedBudgetScenario(total_budget=1000000),
      kpi_type=common.KpiType.REVENUE,
      new_data=future_data,
  )
  
  processor = budget_optimization_processor.BudgetOptimizationProcessor(mmm)
  budget_opt_proto = processor.execute([spec])

Hope this answers your questions. Feel free to reach out if you face any issues while implementing the workaround or if you have any other questions or suggestions for us.

Google Meridian Support Team