google-meridian 1.1.1__py3-none-any.whl → 1.1.3__py3-none-any.whl

{google_meridian-1.1.1.dist-info → google_meridian-1.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-meridian
-Version: 1.1.1
+Version: 1.1.3
 Summary: Google's open source mixed marketing model library, helps you understand your return on investment and direct your ad spend with confidence. 
 Author-email: The Meridian Authors <no-reply@google.com>
 License: 
@@ -222,6 +222,7 @@ Requires-Dist: arviz
 Requires-Dist: altair>=5
 Requires-Dist: immutabledict
 Requires-Dist: joblib
+Requires-Dist: natsort<8,>=7.1.1
 Requires-Dist: numpy<3,>=2.0.2
 Requires-Dist: pandas<3,>=2.2.2
 Requires-Dist: scipy<2,>=1.13.1
@@ -236,8 +237,11 @@ Requires-Dist: pylint>=2.6.0; extra == "dev"
 Requires-Dist: pyink; extra == "dev"
 Provides-Extra: colab
 Requires-Dist: psutil; extra == "colab"
+Requires-Dist: python-calamine; extra == "colab"
 Provides-Extra: and-cuda
 Requires-Dist: tensorflow[and-cuda]<2.19,>=2.18; extra == "and-cuda"
+Provides-Extra: mlflow
+Requires-Dist: mlflow; extra == "mlflow"
 Dynamic: license-file
 
 # About Meridian
@@ -393,7 +397,7 @@ To cite this repository:
   author = {Google Meridian Marketing Mix Modeling Team},
   title = {Meridian: Marketing Mix Modeling},
   url = {https://github.com/google/meridian},
-  version = {1.1.1},
+  version = {1.1.3},
   year = {2025},
 }
 ```

{google_meridian-1.1.1.dist-info → google_meridian-1.1.3.dist-info}/RECORD

@@ -1,14 +1,15 @@
-google_meridian-1.1.1.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
-meridian/__init__.py,sha256=v7cNJABthU3UGBjqzcBs5J7MInPPxRkCUZChVo2pw3M,714
-meridian/constants.py,sha256=AWhDEP9VcyQtPCbZhM6cPXHeWuz19wjaqB5lGz6qBsw,17161
+google_meridian-1.1.3.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+meridian/__init__.py,sha256=XROKwHNVQvEa371QCXAHik5wN_YKObOdJQX9bJ2c4M4,832
+meridian/constants.py,sha256=VAVHyGfm9FyDd0dWomfqK5XYDUt9qJx7SAM4rzDh3RQ,17195
+meridian/version.py,sha256=CUTXDDaOfXFTukX_ywPK6Q3PiK9hMyJbmJRBeb5ez7c,644
 meridian/analysis/__init__.py,sha256=nGBYz7k9FVdadO_WVGMKJcfq7Yy_TuuP8zgee4i9pSA,836
-meridian/analysis/analyzer.py,sha256=VBEQYP28G23F2EXoEOqGrWJRmCr_ez-qWD3brQlqZI4,204098
+meridian/analysis/analyzer.py,sha256=FY_SvnkmEqqCIS37UXB3bvaQi-U3BwLcSWhH1puTzdQ,206003
 meridian/analysis/formatter.py,sha256=ENIdR1CRiaVqIGEXx1HcnsA4ewgDD_nhsYCweJAThaw,7270
-meridian/analysis/optimizer.py,sha256=ZmO05reNjlFOy8i3E8M9dDMYCIzNnQjLdH99zSorkqw,106122
+meridian/analysis/optimizer.py,sha256=P4uMcV9ByqMapqa1TEqcnu-3NyTH9fR8QLszdKxRAFc,107801
 meridian/analysis/summarizer.py,sha256=IthOUTMufGvAvbxiDhaKwe7uYCyiTyiQ8vgdmUtdevs,18855
 meridian/analysis/summary_text.py,sha256=I_smDkZJYp2j77ea-9AIbgeraDa7-qUYyb-IthP2qO4,12438
 meridian/analysis/test_utils.py,sha256=ES1r1akhRjD4pf2oTaGqzDfGNu9weAcLv6UZRuIkfEc,77699
-meridian/analysis/visualizer.py,sha256=VHgbvGnRmloawilU_I7FPsqZcAYpZq5ODl3cHy2eiDo,93728
+meridian/analysis/visualizer.py,sha256=hVY0JxDZSgK7ekav3jTYBfxXXn-J0g7uQWMtEj3obx4,94512
 meridian/analysis/templates/card.html.jinja,sha256=pv4MVbQ25CcvtZY-LH7bFW0OSeHobkeEkAleB1sfQ14,1284
 meridian/analysis/templates/chart.html.jinja,sha256=87i0xnXHRBoLLxBpKv2i960TLToWq4r1aVQZqaXIeMQ,1086
 meridian/analysis/templates/chips.html.jinja,sha256=Az0tQwF_-b03JDLyOzpeH-8fb-6jgJgbNfnUUSm-q6E,645
@@ -18,24 +19,29 @@ meridian/analysis/templates/style.css,sha256=RODTWc2pXcG9zW3q9SEJpVXgeD-WwQgzLpm
 meridian/analysis/templates/style.scss,sha256=nSrZOpcIrVyiL4eC9jLUlxIZtAKZ0Rt8pwfk4H1nMrs,5076
 meridian/analysis/templates/summary.html.jinja,sha256=LuENVDHYIpNo4pzloYaCR2K9XN1Ow6_9oQOcOwD9nGg,1707
 meridian/analysis/templates/table.html.jinja,sha256=mvLMZx92RcD2JAS2w2eZtfYG-6WdfwYVo7pM8TbHp4g,1176
-meridian/data/__init__.py,sha256=4F6_dCnDOic08yMw6_nIDR03B9cF_4STDFb430XvZR4,774
+meridian/data/__init__.py,sha256=StIe-wfYnnbfUbKtZHwnAQcRQUS8XCZk_PCaEzw90Ww,929
 meridian/data/arg_builder.py,sha256=Kqlt88bOqFj6D3xNwvWo4MBwNwcDFHzd-wMfEOmLoPU,3741
+meridian/data/data_frame_input_data_builder.py,sha256=3m6wrcC0psmD2ijsXk3R4uByA0Tu2gJxZBGaTS6Z7Io,22040
 meridian/data/input_data.py,sha256=teJPKTBfW-AzBWgf_fEO_S_Z1J_veqQkCvctINaid6I,39749
-meridian/data/load.py,sha256=iFdNq9J89qlmOIrvMER1ci8LzZD87gHl6NTW49h7ZFE,55260
+meridian/data/input_data_builder.py,sha256=08E_MZLrCzwfjvjPWFVs7o_094vVJ5o6VmbTfrg4NUM,25602
+meridian/data/load.py,sha256=B-12fBhsghN7wj0A9IWyT7BVogIXjuUDDvR34JJFwPM,45157
+meridian/data/nd_array_input_data_builder.py,sha256=lfpmnENGuSGKyUd7bDGAwoLqHqteOKmHdKl0VI2wCQA,16341
 meridian/data/test_utils.py,sha256=6GJrPmeaF4uzMxxRgzERGv4g1XMUHwI0s7qDVMZUjuI,55565
 meridian/data/time_coordinates.py,sha256=C5A5fscSLjPH6G9YT8OspgIlCrkMY7y8dMFEt3tNSnE,9874
+meridian/mlflow/__init__.py,sha256=elwXUqPQYi7VF9PYjelU1tydfcUrmtuoq6eJCOnV9bk,693
+meridian/mlflow/autolog.py,sha256=s240eLGAurzaNsulwRlyM1ZdBLvUzyr2eOMYgOyWAzk,6393
 meridian/model/__init__.py,sha256=9NFfqUE5WgFc-9lQMkbfkwwV-bQIz0tsQ_3Jyq0A4SU,982
 meridian/model/adstock_hill.py,sha256=20A_6rbDUAADEkkHspB7JpCm5tYfYS1FQ6hJMLu21Pk,9283
 meridian/model/knots.py,sha256=KPEgnb-UdQQ4QBugOYEke-zBgEghgTmeCMoeiJ30meY,8054
-meridian/model/media.py,sha256=R0LnMUNTuGzXD2lzNRRORA4-p21xpdhkVVsvFaWtEK0,13819
-meridian/model/model.py,sha256=JXHCcxpUDXqJQ9hI0YkY5PfGbpt8d3jAKR1TbCP08PI,61110
+meridian/model/media.py,sha256=3BaPX8xYAFMEvf0mz3mBSCIDWViIs7M218nrCklc6Fk,14099
+meridian/model/model.py,sha256=BlLPyskHrEx5D71mUZFbNxS2VjkQgaiaE6hLKvQ5D3A,61489
 meridian/model/model_test_data.py,sha256=hDDTEzm72LknW9c5E_dNsy4Mm4Tfs6AirhGf_QxykFs,15552
-meridian/model/posterior_sampler.py,sha256=jjLqcYEAorVJ_2nmhpkVUjCGAyNUZYPTEXVTDHufbqA,27727
+meridian/model/posterior_sampler.py,sha256=K49zWTTelME2rL1JLeFAdMPzL0OwrBvyAXA3oR-kgSI,27801
 meridian/model/prior_distribution.py,sha256=IEDU1rabcmKNY8lxwbbO4OUAlMHPIMa7flM_zsu3DLM,42417
-meridian/model/prior_sampler.py,sha256=jSaxFmJzyN2OKqKyU059Ar4Yr565w4zlInPl4zxjGZk,23212
-meridian/model/spec.py,sha256=b6nYj39L-Yy5j2i2IHdZHY2trRvjEA-9i_c3b__63A8,17239
+meridian/model/prior_sampler.py,sha256=cmu6jG-bSEkYDkjVUxl3iSxrL7r-LN7a77cb2Vc0LoA,23218
+meridian/model/spec.py,sha256=0HNiMQUWQpYvWYOZr1_fj2ah8tH-bEyfEjoqgBZ9Lc0,18049
 meridian/model/transformers.py,sha256=nRjzq1fQG0ypldxboM7Gqok6WSAXAS1witRXoAzeH9Q,7763
-google_meridian-1.1.1.dist-info/METADATA,sha256=5yywzNt-Pe3h9GLYo-0MfmOku5tHg2J5XrcJtUTp3Gk,22055
-google_meridian-1.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-google_meridian-1.1.1.dist-info/top_level.txt,sha256=nwaCebZvvU34EopTKZsjK0OMTFjVnkf4FfnBN_TAc0g,9
-google_meridian-1.1.1.dist-info/RECORD,,
+google_meridian-1.1.3.dist-info/METADATA,sha256=5W_XWui7q5gH68OC3Z-PXbDOeBftDbWuhqznNv7fOAk,22201
+google_meridian-1.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+google_meridian-1.1.3.dist-info/top_level.txt,sha256=nwaCebZvvU34EopTKZsjK0OMTFjVnkf4FfnBN_TAc0g,9
+google_meridian-1.1.3.dist-info/RECORD,,

meridian/__init__.py

@@ -13,10 +13,12 @@
 # limitations under the License.
 
 """Meridian API."""
-
-__version__ = "1.1.1"
-
-
 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:
+  pass

meridian/analysis/analyzer.py

@@ -65,6 +65,8 @@ class DataTensors(tf.experimental.ExtensionType):
       time dimension `T`.
     frequency: Optional tensor with dimensions `(n_geos, T, n_rf_channels)` for
       any time dimension `T`.
+    rf_impressions: Optional tensor with dimensions `(n_geos, T, n_rf_channels)`
+      for any time dimension `T`.
     rf_spend: Optional tensor with dimensions `(n_geos, T, n_rf_channels)` for
       any time dimension `T`.
     organic_media: Optional tensor with dimensions `(n_geos, T,
@@ -86,6 +88,7 @@ class DataTensors(tf.experimental.ExtensionType):
   media_spend: Optional[tf.Tensor]
   reach: Optional[tf.Tensor]
   frequency: Optional[tf.Tensor]
+  rf_impressions: Optional[tf.Tensor]
   rf_spend: Optional[tf.Tensor]
   organic_media: Optional[tf.Tensor]
   organic_reach: Optional[tf.Tensor]
@@ -101,6 +104,7 @@ class DataTensors(tf.experimental.ExtensionType):
       media_spend: Optional[tf.Tensor] = None,
       reach: Optional[tf.Tensor] = None,
       frequency: Optional[tf.Tensor] = None,
+      rf_impressions: Optional[tf.Tensor] = None,
       rf_spend: Optional[tf.Tensor] = None,
       organic_media: Optional[tf.Tensor] = None,
       organic_reach: Optional[tf.Tensor] = None,
@@ -118,6 +122,11 @@ class DataTensors(tf.experimental.ExtensionType):
     self.frequency = (
         tf.cast(frequency, tf.float32) if frequency is not None else None
     )
+    self.rf_impressions = (
+        tf.cast(rf_impressions, tf.float32)
+        if rf_impressions is not None
+        else None
+    )
     self.rf_spend = (
         tf.cast(rf_spend, tf.float32) if rf_spend is not None else None
     )
@@ -189,7 +198,10 @@ class DataTensors(tf.experimental.ExtensionType):
     """
     for field in self._tf_extension_type_fields():
       new_tensor = getattr(self, field.name)
-      old_tensor = getattr(meridian.input_data, field.name)
+      if field.name == constants.RF_IMPRESSIONS:
+        old_tensor = getattr(meridian.rf_tensors, field.name)
+      else:
+        old_tensor = getattr(meridian.input_data, field.name)
       # The time dimension is always the second dimension, except for when spend
       # data is provided with only one dimension of (n_channels).
       if (
@@ -293,7 +305,13 @@ class DataTensors(tf.experimental.ExtensionType):
             "This is not supported and will be ignored."
         )
       if field.name in required_variables:
-        if getattr(meridian.input_data, field.name) is None:
+        if field.name == constants.RF_IMPRESSIONS:
+          if meridian.n_rf_channels == 0:
+            raise ValueError(
+                "New `rf_impressions` is not allowed because there are no R&F"
+                " channels in the Meridian model."
+            )
+        elif getattr(meridian.input_data, field.name) is None:
           raise ValueError(
               f"New `{field.name}` is not allowed because the input data to the"
               f" Meridian model does not contain `{field.name}`."
@@ -322,7 +340,10 @@ class DataTensors(tf.experimental.ExtensionType):
       if var_name in [constants.REVENUE_PER_KPI, constants.TIME]:
         continue
       new_tensor = getattr(self, var_name)
-      old_tensor = getattr(meridian.input_data, var_name)
+      if var_name == constants.RF_IMPRESSIONS:
+        old_tensor = getattr(meridian.rf_tensors, var_name)
+      else:
+        old_tensor = getattr(meridian.input_data, var_name)
       if new_tensor is not None:
         assert old_tensor is not None
         if new_tensor.shape[-1] != old_tensor.shape[-1]:
@@ -337,7 +358,10 @@ class DataTensors(tf.experimental.ExtensionType):
     """Validates the time dimension of the specified data variables."""
     for var_name in required_fields:
       new_tensor = getattr(self, var_name)
-      old_tensor = getattr(meridian.input_data, var_name)
+      if var_name == constants.RF_IMPRESSIONS:
+        old_tensor = getattr(meridian.rf_tensors, var_name)
+      else:
+        old_tensor = getattr(meridian.input_data, var_name)
 
       # Skip spend data with only 1 dimension of (n_channels).
       if (
@@ -375,7 +399,10 @@ class DataTensors(tf.experimental.ExtensionType):
     missing_params = []
     for var_name in required_fields:
       new_tensor = getattr(self, var_name)
-      old_tensor = getattr(meridian.input_data, var_name)
+      if var_name == constants.RF_IMPRESSIONS:
+        old_tensor = getattr(meridian.rf_tensors, var_name)
+      else:
+        old_tensor = getattr(meridian.input_data, var_name)
 
       if old_tensor is None:
         continue
@@ -3415,6 +3442,7 @@ class Analyzer:
   def optimal_freq(
       self,
       new_data: DataTensors | None = None,
+      max_frequency: float | None = None,
       freq_grid: Sequence[float] | None = None,
       use_posterior: bool = True,
       use_kpi: bool = False,
@@ -3443,7 +3471,7 @@ class Analyzer:
     ROI numerator is KPI units.
 
     Args:
-      new_data: Optional `DataTensors` object containing `reach`, `frequency`,
+      new_data: Optional `DataTensors` object containing `rf_impressions`,
         `rf_spend`, and `revenue_per_kpi`. If provided, the optimal frequency is
         calculated using the values of the tensors passed in `new_data` and the
         original values of all the remaining tensors. If `None`, the historical
@@ -3451,6 +3479,10 @@ class Analyzer:
         tensors in `new_data` is provided with a different number of time
         periods than in `InputData`, then all tensors must be provided with the
         same number of time periods.
+      max_frequency: Maximum frequency value used to calculate the frequency
+        grid. If `None`, the maximum frequency value is calculated from the
+        historic frequency (maximum value of Meridian.input_data, not
+        `new_data`). If `freq_grid` is provided, this argument has no effect.
       freq_grid: List of frequency values. The ROI of each channel is calculated
         for each frequency value in the list. By default, the list includes
         numbers from `1.0` to the maximum frequency in increments of `0.1`.
@@ -3506,7 +3538,11 @@ class Analyzer:
       )
 
     filled_data = new_data.validate_and_fill_missing_data(
-        constants.RF_DATA,
+        [
+            constants.RF_IMPRESSIONS,
+            constants.RF_SPEND,
+            constants.REVENUE_PER_KPI,
+        ],
         self._meridian,
     )
     # TODO: Once treatment type filtering is added, remove adding
@@ -3527,7 +3563,9 @@ class Analyzer:
         (self._meridian.n_geos, n_times, self._meridian.n_media_channels)
     )
 
-    max_freq = np.max(np.array(filled_data.frequency))
+    max_freq = max_frequency or np.max(
+        np.array(self._meridian.rf_tensors.frequency)
+    )
     if freq_grid is None:
       freq_grid = np.arange(1, max_freq, 0.1)
 
@@ -3537,8 +3575,8 @@ class Analyzer:
     metric_grid = np.zeros((len(freq_grid), self._meridian.n_rf_channels, 4))
 
     for i, freq in enumerate(freq_grid):
-      new_frequency = tf.ones_like(filled_data.frequency) * freq
-      new_reach = filled_data.frequency * filled_data.reach / new_frequency
+      new_frequency = tf.ones_like(filled_data.rf_impressions) * freq
+      new_reach = filled_data.rf_impressions / new_frequency
       new_roi_data = DataTensors(
           reach=new_reach,
           frequency=new_frequency,
@@ -3568,12 +3606,10 @@ class Analyzer:
 
     optimal_frequency = [freq_grid[i] for i in optimal_freq_idx]
     optimal_frequency_tensor = tf.convert_to_tensor(
-        tf.ones_like(filled_data.frequency) * optimal_frequency,
+        tf.ones_like(filled_data.rf_impressions) * optimal_frequency,
         tf.float32,
     )
-    optimal_reach = (
-        filled_data.frequency * filled_data.reach / optimal_frequency_tensor
-    )
+    optimal_reach = filled_data.rf_impressions / optimal_frequency_tensor
 
     new_summary_metrics_data = DataTensors(
         reach=optimal_reach,
@@ -3961,11 +3997,17 @@ class Analyzer:
   ) -> xr.Dataset:
     """Method to generate a response curves xarray.Dataset.
 
-    Response curves are calculated at the national-level, assuming the
-    historical flighting pattern across geos and time periods for each media
-    channel. A list of multipliers is applied to each media channel's total
-    historical spend to obtain the `x-values` at which the channel's response
-    curve is calculated.
+    Response curves are calculated in aggregate across geos and time periods,
+    assuming the historical flighting pattern across geos and time periods for
+    each media channel.
+
+    A list of multipliers is applied to each media channel's total historical
+    spend within `selected_geos` and `selected_times` to obtain the x-axis
+    values. The y-axis values are the incremental ouctcome generated by each
+    channel within `selected_geos` and `selected_times` under the counterfactual
+    where media units in each geo and time period are scaled by the
+    corresponding multiplier. (Media units for time periods prior to
+    `selected_times` are also scaled by the multiplier.)
 
     Args:
       spend_multipliers: List of multipliers. Each channel's total spend is

meridian/analysis/optimizer.py

@@ -223,7 +223,7 @@ class OptimizationGrid:
     if spend_constraint_upper is None:
       spend_constraint_upper = spend_constraint_default
     (optimization_lower_bound, optimization_upper_bound) = (
-        _get_optimization_bounds(
+        get_optimization_bounds(
             n_channels=len(self.channels),
             spend=spend,
             round_factor=self.round_factor,
@@ -1307,36 +1307,57 @@ class BudgetOptimizer:
   ) -> OptimizationResults:
     """Finds the optimal budget allocation that maximizes outcome.
 
-    Optimization depends on the following:
-    1. Flighting pattern (the relative allocation of a channels' media units
-       across geos and time periods, which is held fixed for each channel)
-    2. Cost per media unit (This is assumed to be constant for each channel, and
-       can optionally vary by geo and/or time period)
-    3. `pct_of_spend` (center of the spend box constraint for each channel)
-    4. `budget` (total budget used for fixed budget scenarios)
-
-    By default, these values are assigned based on the historical data. The
-    `pct_of_spend` and `budget` are optimization arguments that can be
-    overridden directly. Passing `new_data.media` (or `new_data.reach` or
-    `new_data.frequency`) will override both the flighting pattern and cost per
-    media unit. Passing `new_data.spend` (or `new_data.rf_spend) will only
-    override the cost per media unit.
-
-    If `new_data` is passed with a different number of time periods than the
-    historical data, then all of the optimization parameters will be inferred
-    from it. Default values for `pct_of_spend` and `budget` (if
-    `fixed_budget=True`) will be inferred from the `new_data`, but can be
-    overridden using the `pct_of_spend` and `budget` arguments.
-
-    If `start_date` or `end_date` is specified, then the default values are
-    inferred based on the subset of time periods specified. Both start and end
-    time selectors should align with the Meridian time dimension coordinates in
-    the underlying model if optimizing the original data. If `new_data` is
-    provided with a different number of time periods than in `InputData`, then
-    the start and end time coordinates must match the time dimensions in
-    `new_data.time`. By default, all times periods are used. Either start or
-    end time component can be `None` to represent the first or the last time
-    coordinate, respectively.
+    Define B to be the historical spend of a channel within `selected_geos` and
+    between `start_date` and `end_date`. When the optimization assigns a new
+    budget N to this channel, the historical media units for each geo and time
+    period are assumed to scale by the ratio N / B. Media units prior to
+    `selected_times` are also scaled by N / B. The incremental outcome of each
+    channel is aggregated over `selected_geos` and between `start_date` and
+    `end_date`.
+
+    The incremental outcome includes the (lagged) amount generated between
+    `start_date` and `end_date` by media executed prior to `start_date`, but it
+    excludes the (lagged) amount generated after `end_date` by media executed
+    between `start_date` and `end_date`. This definition does not require any
+    assumptions about media execution levels, media costs, or revenue per kpi
+    for time periods after `end_date`.
+
+    These assumptions are equivalent to assuming that for each channel, neither
+    the flighting pattern nor the cost per media unit depend on the overall
+    budget assigned to that channel.
+
+    The following optimization parameters are assigned default values based on
+    the model input data:
+    1. Flighting pattern. This is the relative allocation of a channel's media
+       units across geos and time periods. By default, the historical flighting
+       pattern is used. The default can be overridden by passing
+       `new_data.media`. The flighting pattern is held constant during
+       optimization and does not depend on the overall budget assigned to the
+       channel.
+    2. Cost per media unit. By default, the historical spend divided by
+       historical media units is used. This can optionally vary by geo or time
+       period or both depending on whether the spend data has geo and time
+       dimensions. The default can be overridden by passing `new_data.spend`.
+       The cost per media unit is held constant during optimization and does not
+       depend on the overall budget assigned to the channel.
+    3. Center of the spend box constraint for each channel. By default, the
+       historical percentage of spend within `selected_geos` and between
+       `start_date` and `end_date` is used. This can be overridden by passing
+       `pct_of_spend`.
+    4. Total budget to be allocated (for fixed budget scenarios only). By
+       default, the historical spend within `selected_geos` and between
+       `start_date` and `end_date` is used. This can be overridden by passing
+       `budget`.
+
+    Passing `new_data.media` (or `new_data.reach` or `new_data.frequency`) will
+    override both the flighting pattern and cost per media unit. Passing
+    `new_data.spend` (or `new_data.rf_spend) will only override the cost per
+    media unit.
+
+    If `start_date` or `end_date` is specified, these values must be selected
+    from `new_data.time` (if provided) or from `Meridian.n_times` (if
+    `new_data.time` is not provided). The `start_date` and `end_date` default to
+    the first and last time periods, respectively.
 
     Args:
       new_data: An optional `DataTensors` container with optional tensors:
@@ -1355,9 +1376,13 @@ class BudgetOptimizer:
         dimension coordinates for the duration to run the optimization on.
         Please Use `start_date` and `end_date` instead.
       start_date: Optional start date selector, *inclusive*, in _yyyy-mm-dd_
-        format. Default is `None`, i.e. the first time period.
+        format. Default is the first time period of `Meridian.InputData.time` if
+        `new_data` is not provided; otherwise it is the first time period of
+        `new_data.time`.
       end_date: Optional end date selector, *inclusive* in _yyyy-mm-dd_ format.
-        Default is `None`, i.e. the last time period.
+        Default is the last time period of `Meridian.InputData.time` if
+        `new_data` is not provided; otherwise it is the last time period of
+        `new_data.time`.
       fixed_budget: Boolean indicating whether it's a fixed budget optimization
         or flexible budget optimization. Defaults to `True`. If `False`, must
         specify either `target_roi` or `target_mroi`.
@@ -1664,7 +1689,7 @@ class BudgetOptimizer:
     )
     spend = budget * valid_pct_of_spend
     (optimization_lower_bound, optimization_upper_bound) = (
-        _get_optimization_bounds(
+        get_optimization_bounds(
             n_channels=n_channels,
             spend=spend,
             round_factor=optimization_grid.round_factor,
@@ -1829,7 +1854,7 @@ class BudgetOptimizer:
     spend = budget * valid_pct_of_spend
     round_factor = _get_round_factor(budget, gtol)
     (optimization_lower_bound, optimization_upper_bound) = (
-        _get_optimization_bounds(
+        get_optimization_bounds(
             n_channels=n_paid_channels,
             spend=spend,
             round_factor=round_factor,
@@ -1838,9 +1863,14 @@ class BudgetOptimizer:
         )
     )
     if self._meridian.n_rf_channels > 0 and use_optimal_frequency:
+      opt_freq_data = analyzer.DataTensors(
+          rf_impressions=filled_data.reach * filled_data.frequency,
+          rf_spend=filled_data.rf_spend,
+          revenue_per_kpi=filled_data.revenue_per_kpi,
+      )
       optimal_frequency = tf.convert_to_tensor(
           self._analyzer.optimal_freq(
-              new_data=filled_data.filter_fields(c.RF_DATA),
+              new_data=opt_freq_data,
               use_posterior=use_posterior,
               selected_times=selected_times,
               use_kpi=use_kpi,
@@ -2059,17 +2089,17 @@ class BudgetOptimizer:
         c.PAID_DATA + (c.TIME,),
         self._meridian,
     )
-    spend = tf.convert_to_tensor(spend, dtype=tf.float32)
+    spend_tensor = tf.convert_to_tensor(spend, dtype=tf.float32)
     hist_spend = tf.convert_to_tensor(hist_spend, dtype=tf.float32)
     (new_media, new_media_spend, new_reach, new_frequency, new_rf_spend) = (
         self._get_incremental_outcome_tensors(
             hist_spend,
-            spend,
+            spend_tensor,
             new_data=filled_data.filter_fields(c.PAID_CHANNELS),
             optimal_frequency=optimal_frequency,
         )
     )
-    budget = np.sum(spend)
+    budget = np.sum(spend_tensor)
 
     # incremental_outcome here is a tensor with the shape
     # (n_chains, n_draws, n_channels)
@@ -2123,7 +2153,7 @@ class BudgetOptimizer:
     )
 
     roi = analyzer.get_central_tendency_and_ci(
-        data=tf.math.divide_no_nan(incremental_outcome, spend),
+        data=tf.math.divide_no_nan(incremental_outcome, spend_tensor),
         confidence_level=confidence_level,
         include_median=True,
     )
@@ -2148,7 +2178,7 @@ class BudgetOptimizer:
     )
 
     cpik = analyzer.get_central_tendency_and_ci(
-        data=tf.math.divide_no_nan(spend, incremental_outcome),
+        data=tf.math.divide_no_nan(spend_tensor, incremental_outcome),
         confidence_level=confidence_level,
         include_median=True,
     )
@@ -2159,9 +2189,10 @@ class BudgetOptimizer:
     )
 
     total_spend = np.sum(spend) if np.sum(spend) > 0 else 1
+    pct_of_spend = spend / total_spend
     data_vars = {
-        c.SPEND: ([c.CHANNEL], spend),
-        c.PCT_OF_SPEND: ([c.CHANNEL], spend / total_spend),
+        c.SPEND: ([c.CHANNEL], spend.data),
+        c.PCT_OF_SPEND: ([c.CHANNEL], pct_of_spend.data),
         c.INCREMENTAL_OUTCOME: (
             [c.CHANNEL, c.METRIC],
             incremental_outcome_with_mean_median_and_ci,
@@ -2510,7 +2541,7 @@ def _get_spend_bounds(
   return spend_bounds
 
 
-def _get_optimization_bounds(
+def get_optimization_bounds(
     n_channels: int,
     spend: np.ndarray,
     round_factor: int,

meridian/analysis/visualizer.py

@@ -876,9 +876,14 @@ class MediaEffects:
     Args:
       confidence_level: Confidence level for modeled response credible
         intervals, represented as a value between zero and one. Default is 0.9.
-      selected_times: Optional list of a subset of time dimensions to include.
-        By default, all times are included. Times should match the time
-        dimensions from `meridian.InputData`.
+      selected_times: Optional list containing a subset of time dimensions to
+        include. The x-axis corresponds to spend within these time periods. The
+        y-axis corresponds to the incremental outcome generated within these
+        time periods under the counterfactual where media units in each geo and
+        time period are scaled by the ratio of x-axis spend to historical spend.
+        (Media units for time periods prior to to `selected_times` are also
+        scaled by this ratio). By default, all times are included. Times should
+        match the time dimensions from `meridian.InputData`.
       by_reach: For the channel w/ reach and frequency, return the response
         curves by reach given fixed frequency if true; return the response
         curves by frequency given fixed reach if false.
@@ -972,8 +977,13 @@ class MediaEffects:
     Args:
       confidence_level: Confidence level to update to for the response curve
         credible intervals, represented as a value between zero and one.
-      selected_times: Optional list containing a subset of times to include. By
-        default, all time periods are included.
+      selected_times: Optional list containing a subset of time dimensions to
+        include. The x-axis corresponds to spend within these time periods. The
+        y-axis corresponds to the incremental outcome generated within these
+        time periods under the counterfactual where media units in each geo and
+        time period are multiplied by the corresponding multiplier (including
+        time periods prior to to `selected_times`). By default, all time periods
+        are included.
       by_reach: For the channel w/ reach and frequency, return the response
         curves by reach given fixed frequency if true; return the response
         curves by frequency given fixed reach if false.

meridian/constants.py

@@ -63,6 +63,7 @@ CONTROLS = 'controls'
 POPULATION = 'population'
 REACH = 'reach'
 FREQUENCY = 'frequency'
+RF_IMPRESSIONS = 'rf_impressions'
 RF_SPEND = 'rf_spend'
 ORGANIC_MEDIA = 'organic_media'
 ORGANIC_REACH = 'organic_reach'

meridian/data/__init__.py

@@ -15,6 +15,9 @@
 """Data handling API for Meridian."""
 
 from meridian.data import arg_builder
+from meridian.data import data_frame_input_data_builder
 from meridian.data import input_data
+from meridian.data import input_data_builder
 from meridian.data import load
+from meridian.data import nd_array_input_data_builder
 from meridian.data import time_coordinates