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

meridian/model/spec.py

@@ -15,12 +15,13 @@
 """Defines model specification parameters for Meridian."""
 
 import dataclasses
+from typing import Sequence
+import warnings
 
 from meridian import constants
 from meridian.model import prior_distribution
 import numpy as np
 
-
 __all__ = [
     "ModelSpec",
 ]
@@ -29,12 +30,22 @@ __all__ = [
 def _validate_roi_calibration_period(
     array: np.ndarray | None,
     array_name: str,
-    media_channel_dim_name: str,
+    channel_dim_name: str,
+    prior_type: str,
+    prior_type_name: str,
 ):
-  if array is not None and (len(array.shape) != 2):
+  """Validates the ROI calibration period array."""
+  if array is None:
+    return
+  if prior_type != constants.TREATMENT_PRIOR_TYPE_ROI:
+    raise ValueError(
+        f"The `{array_name}` should be `None` unless `{prior_type_name}` is"
+        f" '{constants.TREATMENT_PRIOR_TYPE_ROI}'."
+    )
+  if len(array.shape) != 2:
     raise ValueError(
         f"The shape of the `{array_name}` array {array.shape} should be"
-        f" 2-dimensional (`n_media_times` x `{media_channel_dim_name}`)."
+        f" 2-dimensional (`n_media_times` x `{channel_dim_name}`)."
     )
 
 
@@ -66,29 +77,85 @@ class ModelSpec:
     unique_sigma_for_each_geo: A boolean indicating whether to use a unique
       residual variance for each geo. If `False`, then a single residual
       variance is used for all geos. Default: `False`.
-    paid_media_prior_type: A string to specify the prior type for the media
-      coefficients. Allowed values: `'roi'`, `'mroi'`, `'coefficient'`. Default:
-      `'roi'`. The `PriorDistribution` contains distributions `roi_m`, `mroi_m`,
-      and`beta_m`, but only one of these is used depending on the
-      `paid_media_prior_type`. Likewise, the `PriorDistribution` contains
-      distributions `roi_rf`, `mroi_rf`, and`beta_rf`, but only one of these is
-      used depending on the `paid_media_prior_type`. When
-      `paid_media_prior_type` is `'roi'`, the `PriorDistribution.roi_m` and
-      `PriorDistribution.roi_rf` parameters are used to specify a prior on the
-      ROI. When `paid_media_prior_type` is `'mroi'`, the
-      `PriorDistribution.mroi_m` and `PriorDistribution.mroi_rf` parameters are
-      used to specify a prior on the mROI. When `paid_media_prior_type` is
-      `'coefficient'`, the `PriorDistribution.beta_m` and
-      `PriorDistribution.beta_rf` parameters are used to specify a prior on the
-      coefficient mean parameters.
+    media_prior_type: A string to specify the prior type for the media
+      coefficients. Allowed values: `'roi'`, `'mroi'`, `'contribution'`,
+      `'coefficient'`. The `PriorDistribution` contains `roi_m`, `mroi_m`,
+      `contribution_m`, and `beta_m`, but only one of these is used depending on
+      the `media_prior_type`. When `media_prior_type` is `'roi'`, the
+      `PriorDistribution.roi_m` parameter is used to specify a prior on the ROI.
+      When `media_prior_type` is `'mroi'`, the `PriorDistribution.mroi_m`
+      parameter is used to specify a prior on the mROI. When `media_prior_type`
+      is `'contribution'`, the `PriorDistribution.contribution_m` parameter is
+      used to specify a prior on the contribution. When `media_prior_type` is
+      `'coefficient'`, the `PriorDistribution.beta_m` parameter is used to
+      specify a prior on the coefficient mean parameters. Default: `'roi'`.
+    rf_prior_type: A string to specify the prior type for the RF coefficients.
+      Allowed values: `'roi'`, `'mroi'`, `'contribution'`, `'coefficient'`. The
+      `PriorDistribution` contains distributions `roi_rf`, `mroi_rf`,
+      `contribution_rf`, and`beta_rf`, but only one of these is used depending
+      on the `rf_prior_type`. When `rf_prior_type` is `'roi'`, the
+      `PriorDistribution.roi_rf` parameter is used to specify a prior on the
+      ROI. When `rf_media_prior_type` is `'mroi'`, the
+      `PriorDistribution.mroi_rf` parameter is used to specify a prior on the
+      mROI. When `rf_prior_type` is `'contribution'`, the
+      `PriorDistribution.contribution_rf` parameter is used to specify a prior
+      on the contribution. When `rf_prior_type` is `'coefficient'`, the
+      `PriorDistribution.beta_rf` parameter is used to specify a prior on the
+      coefficient mean parameters. Default: `'roi'`.
+    paid_media_prior_type: Deprecated. Use `media_prior_type` and
+      `rf_prior_type` instead. A string to specify the prior type for media and
+      RF treatments at the same time. Ignored when `media_prior_type` or
+      `rf_prior_type` are set. Default: `'roi'`.
     roi_calibration_period: An optional boolean array of shape `(n_media_times,
       n_media_channels)` indicating the subset of `time` that the ROI value of
-      the `roi_m` prior (or mROI value of the `mroi_m` prior) applies to. If
-      `None`, all times are used. Default: `None`.
+      the `roi_m` prior applies to. The ROI numerator is the incremental outcome
+      generated during this time period, and the denominator is the spend during
+      this time period. (Spend data by time period is required). If `None`, all
+      times are used. Only used if `media_prior_type` is `'roi'`.
+      Default: `None`.
     rf_roi_calibration_period: An optional boolean array of shape
       `(n_media_times, n_rf_channels)` indicating the subset of `time` that the
-      ROI value of the `roi_rf` prior (or mROI value of the `mroi_rf` prior)
-      applies to. If `None`, all times are used. Default: `None`.
+      ROI value of the `roi_rf` prior applies to. The ROI numerator is the
+      incremental outcome generated during this time period, and the denominator
+      is the spend during this time period. (Spend data by time period is
+      required). If `None`, all times are used. Only used if `rf_prior_type` is
+      `'roi'`. Default: `None`.
+    organic_media_prior_type: A string to specify the prior type for the organic
+      media coefficients. Allowed values: `'contribution'`, `'coefficient'`.
+      `PriorDistribution` contains `contribution_om` and `beta_om`, but only one
+      of these is used depending on the `organic_media_prior_type`. When
+      `organic_media_prior_type` is `'contribution'`, the
+      `PriorDistribution.contribution_om` parameter is used to specify a prior
+      on the contribution. When `organic_media_prior_type` is `'coefficient'`,
+      the `PriorDistribution.beta_om` parameter is used to specify a prior on
+      the coefficient mean parameters. Default: `'contribution'`.
+    organic_rf_prior_type: A string to specify the prior type for the organic
+      reach and frequency coefficients. Allowed values: `'contribution'`,
+      `'coefficient'`. The `PriorDistribution` contains distributions
+      `contribution_orf`, and `beta_orf`, but only one of these is used
+      depending on the `organic_rf_prior_type`. When `organic_rf_prior_type` is
+      `'contribution'`, the `PriorDistribution.contribution_orf` parameter is
+      used to specify a prior on the contribution. When `organic_rf_prior_type`
+      is `'coefficient'`, the `PriorDistribution.beta_orf` parameter is used to
+      specify a prior on the coefficient mean parameters. Default:
+      `'contribution'`.
+    non_media_treatments_prior_type: A string to specify the prior type for the
+      non-media treatment coefficients. Allowed values: `'contribution'`,
+      `'coefficient'`. `PriorDistribution` contains `contribution_n` and
+      `gamma_n`, but only one of these is used depending on the
+      `non_media_prior_type`. When `non_media_prior_type` is `'contribution'`,
+      the `PriorDistribution.contribution_n` parameter is used to specify a
+      prior on the contribution. When `non_media_prior_type` is `'coefficient'`,
+      the `PriorDistribution.gamma_n` parameter is used to specify a prior on
+      the coefficient mean parameters. Default: `'contribution'`.
+    non_media_baseline_values: Optional list with the shape
+      `(n_non_media_channels,)`. Each element is either a float (which means
+      that the fixed value will be used as baseline for the given channel) or
+      one of the strings `"min"` or `"max"` (which mean that the global minimum
+      or maximum value will be used as baseline for the scaled values of the
+      given non_media treatments channel). If `None`, the minimum value is used
+      as baseline for each non-media treatments channel. This attribute is used
+      as the default value for the corresponding argument to `Analyzer` methods.
     knots: An optional integer or list of integers indicating the knots used to
       estimate time effects. When `knots` is a list of integers, the knot
       locations are provided by that list. Zero corresponds to a knot at the
@@ -134,9 +201,17 @@ class ModelSpec:
   hill_before_adstock: bool = False
   max_lag: int | None = 8
   unique_sigma_for_each_geo: bool = False
-  paid_media_prior_type: str = constants.PAID_MEDIA_PRIOR_TYPE_ROI
+  media_prior_type: str | None = None
+  rf_prior_type: str | None = None
+  paid_media_prior_type: str | None = None
   roi_calibration_period: np.ndarray | None = None
   rf_roi_calibration_period: np.ndarray | None = None
+  organic_media_prior_type: str = constants.TREATMENT_PRIOR_TYPE_CONTRIBUTION
+  organic_rf_prior_type: str = constants.TREATMENT_PRIOR_TYPE_CONTRIBUTION
+  non_media_treatments_prior_type: str = (
+      constants.TREATMENT_PRIOR_TYPE_CONTRIBUTION
+  )
+  non_media_baseline_values: Sequence[float | str] | None = None
   knots: int | list[int] | None = None
   baseline_geo: int | str | None = None
   holdout_id: np.ndarray | None = None
@@ -148,24 +223,77 @@ class ModelSpec:
     if self.media_effects_dist not in constants.MEDIA_EFFECTS_DISTRIBUTIONS:
       raise ValueError(
           f"The `media_effects_dist` parameter '{self.media_effects_dist}' must"
-          f" be one of {sorted(list(constants.MEDIA_EFFECTS_DISTRIBUTIONS))}."
+          f" be one of {sorted(constants.MEDIA_EFFECTS_DISTRIBUTIONS)}."
       )
-    # Validate roi_prior_type.
-    if self.paid_media_prior_type not in constants.PAID_MEDIA_PRIOR_TYPES:
+    # Support paid_media_prior_type for backwards compatibility.
+    if self.paid_media_prior_type is not None:
+      if self.media_prior_type is not None or self.rf_prior_type is not None:
+        raise ValueError(
+            "The deprecated `paid_media_prior_type` parameter cannot be used"
+            " with `media_prior_type` or `rf_prior_type`. Use"
+            " `media_prior_type` and `rf_prior_type` instead."
+        )
+      else:
+        warnings.warn(
+            "Using `paid_media_prior_type` parameter will set prior types for"
+            " media and RF at the same time. This is deprecated and will be"
+            " removed in a future version of Meridian. Use `media_prior_type`"
+            " and `rf_prior_type` instead."
+        )
+    # Validate prior_type.
+    if (
+        self.effective_media_prior_type
+        not in constants.PAID_TREATMENT_PRIOR_TYPES
+    ):
       raise ValueError(
-          "The `paid_media_prior_type` parameter"
-          f" '{self.paid_media_prior_type}' must be one of"
-          f" {sorted(list(constants.PAID_MEDIA_PRIOR_TYPES))}."
+          "The `media_prior_type` parameter"
+          f" '{self.effective_media_prior_type}' must be one of"
+          f" {sorted(constants.PAID_TREATMENT_PRIOR_TYPES)}."
       )
+    if self.effective_rf_prior_type not in constants.PAID_TREATMENT_PRIOR_TYPES:
+      raise ValueError(
+          "The `rf_prior_type` parameter"
+          f" '{self.effective_rf_prior_type}' must be one of"
+          f" {sorted(constants.PAID_TREATMENT_PRIOR_TYPES)}."
+      )
+    if self.organic_media_prior_type not in (
+        constants.NON_PAID_TREATMENT_PRIOR_TYPES
+    ):
+      raise ValueError(
+          "The `organic_media_prior_type` parameter"
+          f" '{self.organic_media_prior_type}' must be one of"
+          f" {sorted(constants.NON_PAID_TREATMENT_PRIOR_TYPES)}."
+      )
+    if self.organic_rf_prior_type not in (
+        constants.NON_PAID_TREATMENT_PRIOR_TYPES
+    ):
+      raise ValueError(
+          "The `organic_rf_prior_type` parameter"
+          f" '{self.organic_rf_prior_type}' must be one of"
+          f" {sorted(constants.NON_PAID_TREATMENT_PRIOR_TYPES)}."
+      )
+    if self.non_media_treatments_prior_type not in (
+        constants.NON_PAID_TREATMENT_PRIOR_TYPES
+    ):
+      raise ValueError(
+          "The `non_media_treatments_prior_type` parameter"
+          f" '{self.non_media_treatments_prior_type}' must be one of"
+          f" {sorted(constants.NON_PAID_TREATMENT_PRIOR_TYPES)}."
+      )
+
     _validate_roi_calibration_period(
-        self.roi_calibration_period,
-        "roi_calibration_period",
-        "n_media_channels",
+        array=self.roi_calibration_period,
+        array_name="roi_calibration_period",
+        channel_dim_name="n_media_channels",
+        prior_type=self.effective_media_prior_type,
+        prior_type_name="media_prior_type",
     )
     _validate_roi_calibration_period(
-        self.rf_roi_calibration_period,
-        "rf_roi_calibration_period",
-        "n_rf_channels",
+        array=self.rf_roi_calibration_period,
+        array_name="rf_roi_calibration_period",
+        channel_dim_name="n_rf_channels",
+        prior_type=self.effective_rf_prior_type,
+        prior_type_name="rf_prior_type",
     )
 
     # Validate knots.
@@ -173,3 +301,35 @@ class ModelSpec:
       raise ValueError("The `knots` parameter cannot be an empty list.")
     if isinstance(self.knots, int) and self.knots == 0:
       raise ValueError("The `knots` parameter cannot be zero.")
+
+  @property
+  def effective_media_prior_type(self) -> str:
+    """Returns the effective media prior type.
+
+    The recommended way to set prior types is to use `media_prior_type` and
+    `rf_prior_type` directly. If both `media_prior_type` and `rf_prior_type`
+    are not set, the deprecated `paid_media_prior_type` is used for both media
+    and RF channels. If none of them are set, the default is `roi`.
+    """
+    if self.media_prior_type is not None:
+      return self.media_prior_type
+    elif self.paid_media_prior_type is not None:
+      return self.paid_media_prior_type
+    else:
+      return constants.TREATMENT_PRIOR_TYPE_ROI
+
+  @property
+  def effective_rf_prior_type(self) -> str:
+    """Returns the effective rf prior type.
+
+    The recommended way to set prior types is to use `media_prior_type` and
+    `rf_prior_type` directly. If both `media_prior_type` and `rf_prior_type`
+    are not set, the deprecated `paid_media_prior_type` is used for both media
+    and RF channels. If none of them are set, the default is `roi`.
+    """
+    if self.rf_prior_type is not None:
+      return self.rf_prior_type
+    elif self.paid_media_prior_type is not None:
+      return self.paid_media_prior_type
+    else:
+      return constants.TREATMENT_PRIOR_TYPE_ROI

meridian/model/transformers.py

@@ -140,9 +140,21 @@ class CenteringAndScalingTransformer(TensorTransformer):
       self._stdevs = tf.math.reduce_std(tensor, axis=(0, 1))
 
   @tf.function(jit_compile=True)
-  def forward(self, tensor: tf.Tensor) -> tf.Tensor:
-    """Scales a given tensor using the stored coefficients."""
-    if self._population_scaling_factors is not None:
+  def forward(
+      self, tensor: tf.Tensor, apply_population_scaling: bool = True
+  ) -> tf.Tensor:
+    """Scales a given tensor using the stored coefficients.
+
+    Args:
+      tensor: A tensor of dimension `(n_geos, n_times, n_channels)` to
+        transform.
+      apply_population_scaling: Whether to apply population scaling before the
+        normalization by means and standard deviations.
+    """
+    if (
+        apply_population_scaling
+        and self._population_scaling_factors is not None
+    ):
       tensor /= self._population_scaling_factors[:, None, :]
     return tf.math.divide_no_nan(tensor - self._means, self._stdevs)
 

google_meridian-1.0.8.dist-info/RECORD

@@ -1,41 +0,0 @@
-google_meridian-1.0.8.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
-meridian/__init__.py,sha256=d85YKzKshDwbViGr-BG7DJhNJh8a-dVF87y83gnTv7I,714
-meridian/constants.py,sha256=vhJI7R3kTGIHkLzkyx3i6ZnpcAXdAo4ath1eBS6cQHQ,15197
-meridian/analysis/__init__.py,sha256=-FooDZ5OzePpyTVkvRoWQx_xBaRR_hjVLny9H8-kkyQ,836
-meridian/analysis/analyzer.py,sha256=HyFJlTUYsv03skU4SiPvqjwevq7TXabwtD9VhoGObsw,200181
-meridian/analysis/formatter.py,sha256=F8OYxD2bH13zV10JY63j2ugCOj-DpTXhyJr43n5ukr8,7270
-meridian/analysis/optimizer.py,sha256=NwHb5PBhHye4XtPhh0qv0ZMCq6LwErZXFa86BwmtKLs,90115
-meridian/analysis/summarizer.py,sha256=jkESRdbH1U3ij-aBdV1JFTYNVJdfALmji5G4jmK4oMs,18403
-meridian/analysis/summary_text.py,sha256=n6a-DTZxtS3WvdI_pDEK7lvO3MRUX3h83GzuVnG6sQ4,12438
-meridian/analysis/test_utils.py,sha256=xai8oxXu51PDsiQ-ZYTnN_eSLsGu0BUOS8rDTcc6v-E,77719
-meridian/analysis/visualizer.py,sha256=_40uBa6QMJSjfwsvswcbGRUN3Urr_Vs16XiwpWETAfc,92624
-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=ixOYHDQExjnPTLLnZ758pRQscZP7c8QJqtc8P4hK-mE,774
-meridian/data/arg_builder.py,sha256=f7LEysYmixAagwygZOEiJkRnWggRhTeXj5AXthBpkQ8,3741
-meridian/data/input_data.py,sha256=aSOyhu7AYhqsqW9xRB9oClOXsMTTeKnW9_p_n8WzBl4,35238
-meridian/data/load.py,sha256=MKCnRoR8ZIfhEAcm5ZUQsjfoEzi1c9SDOgf6BR8Akr0,54642
-meridian/data/test_utils.py,sha256=LNtsAalrHuolw7JbdggesJjhc6HXuy_eGPPAf4ix42c,51756
-meridian/data/time_coordinates.py,sha256=U4Qv8kXKUYoSH0A5F3REkoScSvrFDHgf_LaxSybdTgo,9881
-meridian/model/__init__.py,sha256=bvx8vvXolktsCTDKViU9U1v85pgNWF3haDowTKy11d4,982
-meridian/model/adstock_hill.py,sha256=b_YYhqci6ndgi602FFXmx2f12ceC4N0tp338nMMtm54,9283
-meridian/model/knots.py,sha256=r7PPaJM96d5pkoOeV9crIOgkM0-rh24mWMvypMiV4aQ,8054
-meridian/model/media.py,sha256=Gjr4jm0y_6pFy7aa_oKIuuZ8P7F56e3ZB-3o6msApeA,11876
-meridian/model/model.py,sha256=hA6HSaH2cd7Zgm8_JX3Jd79bWQSk8BtdqfEm5C9e3oQ,43323
-meridian/model/model_test_data.py,sha256=dqS_vDQUg811UGmyr8ZgWp8VTIra-krA7A2erQlfPlU,12488
-meridian/model/posterior_sampler.py,sha256=uUNMdxyoK0LT6hNKiAxEEl-1X0SyBMz-o_Sao5q5Ts8,23228
-meridian/model/prior_distribution.py,sha256=6fqx_XIM0DSQICd65XaSRhelsjvZ4ariBfeyOeoKld8,39075
-meridian/model/prior_sampler.py,sha256=zGSAQviFO3s2GcVbfG9EfXxo_SNFBFbTQC3e-QBFzio,23079
-meridian/model/spec.py,sha256=xaHxfCLWLnWMAkMy2ouDoqGBHI_4tzzX8AaJOsKdu7Q,8878
-meridian/model/transformers.py,sha256=te3OJixprWLtv7O00a9GZWE4waTS94NNLVo3tWIl1-k,7420
-google_meridian-1.0.8.dist-info/METADATA,sha256=DaSRL6L3xb0AiZBw22nbxDbFqvm2thApTpiEzffGe-o,22055
-google_meridian-1.0.8.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-google_meridian-1.0.8.dist-info/top_level.txt,sha256=nwaCebZvvU34EopTKZsjK0OMTFjVnkf4FfnBN_TAc0g,9
-google_meridian-1.0.8.dist-info/RECORD,,