google-meridian 1.1.0__py3-none-any.whl → 1.1.2__py3-none-any.whl

{google_meridian-1.1.0.dist-info → google_meridian-1.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-meridian
-Version: 1.1.0
+Version: 1.1.2
 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.0},
+  version = {1.1.2},
   year = {2025},
 }
 ```

google_meridian-1.1.2.dist-info/RECORD

@@ -0,0 +1,46 @@
+google_meridian-1.1.2.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+meridian/__init__.py,sha256=rWkSMlr2TiRmH7Xf9z1Bj3grQiSbmrxl3dtGB9YGn9o,714
+meridian/constants.py,sha256=AWhDEP9VcyQtPCbZhM6cPXHeWuz19wjaqB5lGz6qBsw,17161
+meridian/analysis/__init__.py,sha256=nGBYz7k9FVdadO_WVGMKJcfq7Yy_TuuP8zgee4i9pSA,836
+meridian/analysis/analyzer.py,sha256=AP2YJpM2R2qMJ-rwtMmgu-cM-xJLJCFodSaP9K8f0Do,204458
+meridian/analysis/formatter.py,sha256=ENIdR1CRiaVqIGEXx1HcnsA4ewgDD_nhsYCweJAThaw,7270
+meridian/analysis/optimizer.py,sha256=Se6_sg0O3A4p80vdVnRtDeyNaE5s-ywxKoU0CODQsWM,107608
+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=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
+meridian/analysis/templates/insights.html.jinja,sha256=6hEWipbOMiMzs9QGZ6dcB_73tNkj0ZtNiC8E89a98zg,606
+meridian/analysis/templates/stats.html.jinja,sha256=9hQOG02FX1IHVIvdWS_-LI2bbSaqdyHEtCZkiArwAg0,772
+meridian/analysis/templates/style.css,sha256=RODTWc2pXcG9zW3q9SEJpVXgeD-WwQgzLpmFcbXPhLg,5492
+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=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/input_data_builder.py,sha256=fFJTmUuIdTnTnZPtZNTiEf4_fsqR_haY7O9ZOFj47bE,25409
+meridian/data/load.py,sha256=cvvesjL6Dc7pYu2nOl558gUOZVAW_B69GirzHocyY3Q,42855
+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=Duubd_Z2Exlk_MJqGTfMIfFjaDUqG_YnsRGjzY4Hn84,1696
+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=KM2EU7eAK5UHDAn1jbUEI_SBrDkz-Bc93R8qRBEiic8,61500
+meridian/model/model_test_data.py,sha256=hDDTEzm72LknW9c5E_dNsy4Mm4Tfs6AirhGf_QxykFs,15552
+meridian/model/posterior_sampler.py,sha256=jjLqcYEAorVJ_2nmhpkVUjCGAyNUZYPTEXVTDHufbqA,27727
+meridian/model/prior_distribution.py,sha256=IEDU1rabcmKNY8lxwbbO4OUAlMHPIMa7flM_zsu3DLM,42417
+meridian/model/prior_sampler.py,sha256=jSaxFmJzyN2OKqKyU059Ar4Yr565w4zlInPl4zxjGZk,23212
+meridian/model/spec.py,sha256=0HNiMQUWQpYvWYOZr1_fj2ah8tH-bEyfEjoqgBZ9Lc0,18049
+meridian/model/transformers.py,sha256=nRjzq1fQG0ypldxboM7Gqok6WSAXAS1witRXoAzeH9Q,7763
+google_meridian-1.1.2.dist-info/METADATA,sha256=qoLl6RDBz8LxrnJ3c4-hDiIMcL5OC8G8X61rotn6PGs,22201
+google_meridian-1.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+google_meridian-1.1.2.dist-info/top_level.txt,sha256=nwaCebZvvU34EopTKZsjK0OMTFjVnkf4FfnBN_TAc0g,9
+google_meridian-1.1.2.dist-info/RECORD,,

{google_meridian-1.1.0.dist-info → google_meridian-1.1.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.8.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

meridian/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The Meridian Authors.
+# 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.
@@ -14,7 +14,7 @@
 
 """Meridian API."""
 
-__version__ = "1.1.0"
+__version__ = "1.1.2"
 
 
 from meridian import analysis

meridian/analysis/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The Meridian Authors.
+# 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.

meridian/analysis/analyzer.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The Meridian Authors.
+# 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.
@@ -788,7 +788,7 @@ class Analyzer:
         tensors are expected to be scaled by their corresponding transformers.
       dist_tensors: A `DistributionTensors` container with the distribution
         tensors for media, RF, organic media, organic RF, non-media treatments,
-        and controls.
+        and controls (if available).
 
     Returns:
       Tensor representing computed kpi means.
@@ -803,17 +803,15 @@ class Analyzer:
         )
     )
 
-    result = (
-        tau_gt
-        + tf.einsum(
-            "...gtm,...gm->...gt", combined_media_transformed, combined_beta
-        )
-        + tf.einsum(
-            "...gtc,...gc->...gt",
-            data_tensors.controls,
-            dist_tensors.gamma_gc,
-        )
+    result = tau_gt + tf.einsum(
+        "...gtm,...gm->...gt", combined_media_transformed, combined_beta
     )
+    if self._meridian.controls is not None:
+      result += tf.einsum(
+          "...gtc,...gc->...gt",
+          data_tensors.controls,
+          dist_tensors.gamma_gc,
+      )
     if data_tensors.non_media_treatments is not None:
       result += tf.einsum(
           "...gtm,...gm->...gt",
@@ -1464,11 +1462,14 @@ class Analyzer:
         (n_chains, 0, self._meridian.n_geos, self._meridian.n_times)
     )
     batch_starting_indices = np.arange(n_draws, step=batch_size)
-    param_list = [
-        constants.MU_T,
-        constants.TAU_G,
-        constants.GAMMA_GC,
-    ] + self._get_causal_param_names(include_non_paid_channels=True)
+    param_list = (
+        [
+            constants.MU_T,
+            constants.TAU_G,
+        ]
+        + ([constants.GAMMA_GC] if self._meridian.n_controls else [])
+        + self._get_causal_param_names(include_non_paid_channels=True)
+    )
     outcome_means_temps = []
     for start_index in batch_starting_indices:
       stop_index = np.min([n_draws, start_index + batch_size])
@@ -3960,11 +3961,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/formatter.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The Meridian Authors.
+# 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.

meridian/analysis/optimizer.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The Meridian Authors.
+# 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.
@@ -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,
@@ -2059,17 +2084,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 +2148,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 +2173,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 +2184,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 +2536,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/summarizer.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The Meridian Authors.
+# 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.

meridian/analysis/summary_text.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The Meridian Authors.
+# 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.

meridian/analysis/test_utils.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The Meridian Authors.
+# 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.

meridian/analysis/visualizer.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The Meridian Authors.
+# 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.
@@ -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.
@@ -1493,8 +1503,7 @@ class MediaSummary:
     Returns:
       An `xarray.Dataset` containing the following:
         - **Coordinates:** `channel`, `metric` (`mean`, `median`, `ci_lo`,
-        `ci_hi`),
-          `distribution` (`prior`, `posterior`)
+          `ci_hi`), `distribution` (`prior`, `posterior`)
         - **Data variables:** `incremental_outcome`, `pct_of_contribution`,
           `effectiveness`.
     """

meridian/constants.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The Meridian Authors.
+# 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.
@@ -72,10 +72,10 @@ REVENUE = 'revenue'
 NON_REVENUE = 'non_revenue'
 REQUIRED_INPUT_DATA_ARRAY_NAMES = (
     KPI,
-    CONTROLS,
     POPULATION,
 )
 OPTIONAL_INPUT_DATA_ARRAY_NAMES = (
+    CONTROLS,
     REVENUE_PER_KPI,
     ORGANIC_MEDIA,
     ORGANIC_REACH,
@@ -148,7 +148,6 @@ REQUIRED_INPUT_DATA_COORD_NAMES = (
     GEO,
     TIME,
     MEDIA_TIME,
-    CONTROL_VARIABLE,
 )
 NON_PAID_MEDIA_INPUT_DATA_COORD_NAMES = (
     ORGANIC_MEDIA_CHANNEL,
@@ -159,6 +158,7 @@ MEDIA_INPUT_DATA_COORD_NAMES = (MEDIA_CHANNEL,)
 RF_INPUT_DATA_COORD_NAMES = (RF_CHANNEL,)
 POSSIBLE_INPUT_DATA_COORD_NAMES = (
     REQUIRED_INPUT_DATA_COORD_NAMES
+    + (CONTROL_VARIABLE,)
     + NON_PAID_MEDIA_INPUT_DATA_COORD_NAMES
     + MEDIA_INPUT_DATA_COORD_NAMES
     + RF_INPUT_DATA_COORD_NAMES

meridian/data/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The Meridian Authors.
+# 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.
@@ -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

meridian/data/arg_builder.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The Meridian Authors.
+# 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.