google-meridian 1.0.7__py3-none-any.whl → 1.0.9__py3-none-any.whl

meridian/constants.py

@@ -51,6 +51,8 @@ GREY_300 = '#DADCE0'
 
 # Example: "2024-01-09"
 DATE_FORMAT = '%Y-%m-%d'
+# Example: "2024 Apr"
+QUARTER_FORMAT = '%Y %b'
 
 # Input data variables.
 KPI = 'kpi'
@@ -95,6 +97,27 @@ POSSIBLE_INPUT_DATA_ARRAY_NAMES = (
     + MEDIA_INPUT_DATA_ARRAY_NAMES
     + RF_INPUT_DATA_ARRAY_NAMES
 )
+PAID_CHANNELS = (MEDIA, REACH, FREQUENCY)
+PAID_DATA = PAID_CHANNELS + (REVENUE_PER_KPI,)
+NON_PAID_DATA = (
+    ORGANIC_MEDIA,
+    ORGANIC_REACH,
+    ORGANIC_FREQUENCY,
+    NON_MEDIA_TREATMENTS,
+)
+SPEND_DATA = (
+    MEDIA_SPEND,
+    RF_SPEND,
+)
+PERFORMANCE_DATA = PAID_DATA + SPEND_DATA
+IMPRESSIONS_DATA = PAID_CHANNELS + NON_PAID_DATA
+RF_DATA = (
+    REACH,
+    FREQUENCY,
+    RF_SPEND,
+    REVENUE_PER_KPI,
+)
+NON_REVENUE_DATA = IMPRESSIONS_DATA + (CONTROLS,)
 
 # Scaled input data variables.
 MEDIA_SCALED = 'media_scaled'
@@ -543,6 +566,7 @@ TARGET_ROI = 'target_roi'
 TARGET_MROI = 'target_mroi'
 SPEND_CONSTRAINT_DEFAULT_FIXED_BUDGET = 0.3
 SPEND_CONSTRAINT_DEFAULT_FLEXIBLE_BUDGET = 1.0
+SPEND_CONSTRAINT_DEFAULT = 1.0
 
 
 # Plot constants.
@@ -591,3 +615,11 @@ CARD_STATS = 'stats'
 
 # VegaLite common params.
 VEGALITE_FACET_DEFAULT_WIDTH = 400
+VEGALITE_FACET_LARGE_WIDTH = 500
+VEGALITE_FACET_EXTRA_LARGE_WIDTH = 900
+
+# Time Granularity Constants
+WEEKLY = 'weekly'
+QUARTERLY = 'quarterly'
+TIME_GRANULARITIES = frozenset({WEEKLY, QUARTERLY})
+QUARTERLY_SUMMARY_THRESHOLD_WEEKS = 52

meridian/data/input_data.py

@@ -401,6 +401,7 @@ class InputData:
         )
 
   def _validate_kpi(self):
+    """Validates the KPI data."""
     if (
         self.kpi_type != constants.REVENUE
         and self.kpi_type != constants.NON_REVENUE
@@ -413,6 +414,14 @@ class InputData:
     if (self.kpi.values < 0).any():
       raise ValueError("KPI values must be non-negative.")
 
+    if (
+        self.revenue_per_kpi is not None
+        and (self.revenue_per_kpi.values <= 0).all()
+    ):
+      raise ValueError(
+          "Revenue per KPI values must not be all zero or negative."
+      )
+
   def _validate_names(self):
     """Verifies that the names of the data arrays are correct."""
     arrays = [
@@ -534,15 +543,50 @@ class InputData:
   def _validate_media_channels(self):
     """Verifies Meridian media channel names invariants.
 
-    In the input data, media channel names across `media_channel` and
-    `rf_channel` must be unique.
+    In the input data, channel names across `media_channel`,
+    `rf_channel`, `organic_media_channel`, `organic_rf_channel`,
+    `non_media_channel` must be unique.
     """
     all_channels = self.get_all_channels()
     if len(np.unique(all_channels)) != all_channels.size:
-      raise ValueError(
-          "Media channel names across `media_channel` and `rf_channel` must be"
-          " unique."
+      error_msg = (
+          "Channel names across `media_channel`, `rf_channel`,"
+          " `organic_media_channel`, `organic_rf_channel`, and"
+          " `non_media_channel` must be unique."
       )
+      # For each channel, store all occurrences of the channel in particular
+      # channel type.
+      from_channel_to_type = {}
+      for channel in all_channels:
+        if channel not in from_channel_to_type:
+          from_channel_to_type[channel] = []
+
+      # pytype: disable=attribute-error
+      if self.media_channel is not None:
+        for channel in self.media_channel.values:
+          from_channel_to_type[channel].append(constants.MEDIA_CHANNEL)
+      if self.rf_channel is not None:
+        for channel in self.rf_channel.values:
+          from_channel_to_type[channel].append(constants.RF_CHANNEL)
+      if self.organic_media_channel is not None:
+        for channel in self.organic_media_channel.values:
+          from_channel_to_type[channel].append(constants.ORGANIC_MEDIA_CHANNEL)
+      if self.organic_rf_channel is not None:
+        for channel in self.organic_rf_channel.values:
+          from_channel_to_type[channel].append(constants.ORGANIC_RF_CHANNEL)
+      if self.non_media_channel is not None:
+        for channel in self.non_media_channel.values:
+          from_channel_to_type[channel].append(constants.NON_MEDIA_CHANNEL)
+      # pytype: enable=attribute-error
+
+      for channel, types in from_channel_to_type.items():
+        if len(types) > 1:
+          error_msg += (
+              f" Channel `{channel}` is present in multiple channel types:"
+              f" {types}."
+          )
+
+      raise ValueError(error_msg)
 
   def _validate_times(self):
     """Validates time coordinate values."""

meridian/model/model.py

@@ -149,6 +149,7 @@ class Meridian:
     self._validate_paid_media_prior_type()
     self._validate_geo_invariants()
     self._validate_time_invariants()
+    self._validate_kpi_transformer()
 
   @property
   def input_data(self) -> data.InputData:
@@ -410,6 +411,7 @@ class Meridian:
         set_total_media_contribution_prior=set_total_media_contribution_prior,
         kpi=np.sum(self.input_data.kpi.values),
         total_spend=agg_total_spend,
+        media_effects_dist=self.media_effects_dist,
     )
 
   @functools.cached_property
@@ -825,6 +827,19 @@ class Meridian:
           " the listed variables that do not vary across time."
       )
 
+  def _validate_kpi_transformer(self):
+    """Validates the KPI transformer."""
+    if (
+        self.kpi_transformer.population_scaled_stdev == 0
+        and self.model_spec.paid_media_prior_type
+        in constants.PAID_MEDIA_ROI_PRIOR_TYPES
+    ):
+      kpi = "kpi" if self.is_national else "population_scaled_kpi"
+      raise ValueError(
+          f"`{kpi}` cannot be constant with"
+          f" {self.model_spec.paid_media_prior_type} prior type."
+      )
+
   def adstock_hill_media(
       self,
       media: tf.Tensor,  # pylint: disable=redefined-outer-name
@@ -1030,7 +1045,7 @@ class Meridian:
       max_energy_diff: float = 500.0,
       unrolled_leapfrog_steps: int = 1,
       parallel_iterations: int = 10,
-      seed: Sequence[int] | None = None,
+      seed: Sequence[int] | int | None = None,
       **pins,
   ):
     """Runs Markov Chain Monte Carlo (MCMC) sampling of posterior distributions.
@@ -1080,9 +1095,10 @@ class Meridian:
         trajectory length implied by `max_tree_depth`. Defaults is `1`.
       parallel_iterations: Number of iterations allowed to run in parallel. Must
         be a positive integer. For more information, see `tf.while_loop`.
-      seed: Used to set the seed for reproducible results. For more information,
-        see [PRNGS and seeds]
-        (https://github.com/tensorflow/probability/blob/main/PRNGS.md).
+      seed: An `int32[2]` Tensor or a Python list or tuple of 2 `int`s, which
+        will be treated as stateless seeds; or a Python `int` or `None`, which
+        will be treated as stateful seeds. See [tfp.random.sanitize_seed]
+        (https://www.tensorflow.org/probability/api_docs/python/tfp/random/sanitize_seed).
       **pins: These are used to condition the provided joint distribution, and
         are passed directly to `joint_dist.experimental_pin(**pins)`.
 

meridian/model/posterior_sampler.py

@@ -393,7 +393,7 @@ class PosteriorMCMCSampler:
       max_energy_diff: float = 500.0,
       unrolled_leapfrog_steps: int = 1,
       parallel_iterations: int = 10,
-      seed: Sequence[int] | None = None,
+      seed: Sequence[int] | int | None = None,
       **pins,
   ) -> az.InferenceData:
     """Runs Markov Chain Monte Carlo (MCMC) sampling of posterior distributions.
@@ -441,9 +441,10 @@ class PosteriorMCMCSampler:
         trajectory length implied by `max_tree_depth`. Defaults is `1`.
       parallel_iterations: Number of iterations allowed to run in parallel. Must
         be a positive integer. For more information, see `tf.while_loop`.
-      seed: Used to set the seed for reproducible results. For more information,
-        see [PRNGS and seeds]
-        (https://github.com/tensorflow/probability/blob/main/PRNGS.md).
+      seed: An `int32[2]` Tensor or a Python list or tuple of 2 `int`s, which
+        will be treated as stateless seeds; or a Python `int` or `None`, which
+        will be treated as stateful seeds. See [tfp.random.sanitize_seed]
+        (https://www.tensorflow.org/probability/api_docs/python/tfp/random/sanitize_seed).
       **pins: These are used to condition the provided joint distribution, and
         are passed directly to `joint_dist.experimental_pin(**pins)`.
 
@@ -457,7 +458,14 @@ class PosteriorMCMCSampler:
         [ResourceExhaustedError when running Meridian.sample_posterior]
         (https://developers.google.com/meridian/docs/advanced-modeling/model-debugging#gpu-oom-error).
     """
-    seed = tfp.random.sanitize_seed(seed) if seed else None
+    if seed is not None and isinstance(seed, Sequence) and len(seed) != 2:
+      raise ValueError(
+          "Invalid seed: Must be either a single integer (stateful seed) or a"
+          " pair of two integers (stateless seed). See"
+          " [tfp.random.sanitize_seed](https://www.tensorflow.org/probability/api_docs/python/tfp/random/sanitize_seed)"
+          " for details."
+      )
+    seed = tfp.random.sanitize_seed(seed) if seed is not None else None
     n_chains_list = [n_chains] if isinstance(n_chains, int) else n_chains
     total_chains = np.sum(n_chains_list)
 
@@ -486,6 +494,8 @@ class PosteriorMCMCSampler:
             " integers as `n_chains` to sample chains serially (see"
             " https://developers.google.com/meridian/docs/advanced-modeling/model-debugging#gpu-oom-error)"
         ) from error
+      if seed is not None:
+        seed += 1
       states.append(mcmc.all_states._asdict())
       traces.append(mcmc.trace)
 

meridian/model/prior_distribution.py

@@ -455,6 +455,7 @@ class PriorDistribution:
       set_total_media_contribution_prior: bool,
       kpi: float,
       total_spend: np.ndarray,
+      media_effects_dist: str,
   ) -> PriorDistribution:
     """Returns a new `PriorDistribution` with broadcast distribution attributes.
 
@@ -480,6 +481,8 @@ class PriorDistribution:
         `set_total_media_contribution_prior=True`.
       total_spend: Spend per media channel summed across geos and time. Required
         if `set_total_media_contribution_prior=True`.
+      media_effects_dist: A string to specify the distribution of media random
+        effects across geos.
 
     Returns:
       A new `PriorDistribution` broadcast from this prior distribution,
@@ -757,6 +760,7 @@ class PriorDistribution:
       )
     else:
       roi_m_converted = self.roi_m
+    _check_for_negative_effect(roi_m_converted, media_effects_dist)
     roi_m = tfp.distributions.BatchBroadcast(
         roi_m_converted, n_media_channels, name=constants.ROI_M
     )
@@ -777,13 +781,15 @@ class PriorDistribution:
       )
     else:
       roi_rf_converted = self.roi_rf
+    _check_for_negative_effect(roi_rf_converted, media_effects_dist)
     roi_rf = tfp.distributions.BatchBroadcast(
         roi_rf_converted, n_rf_channels, name=constants.ROI_RF
     )
-
+    _check_for_negative_effect(self.mroi_m, media_effects_dist)
     mroi_m = tfp.distributions.BatchBroadcast(
         self.mroi_m, n_media_channels, name=constants.MROI_M
     )
+    _check_for_negative_effect(self.mroi_rf, media_effects_dist)
     mroi_rf = tfp.distributions.BatchBroadcast(
         self.mroi_rf, n_rf_channels, name=constants.MROI_RF
     )
@@ -885,6 +891,21 @@ def _get_total_media_contribution_prior(
   return tfp.distributions.LogNormal(lognormal_mu, lognormal_sigma, name=name)
 
 
+def _check_for_negative_effect(
+    dist: tfp.distributions.Distribution, media_effects_dist: str
+):
+  """Checks for negative effect in the model."""
+  if (
+      media_effects_dist == constants.MEDIA_EFFECTS_LOG_NORMAL
+      and np.any(dist.cdf(0)) > 0
+  ):
+    raise ValueError(
+        'Media priors must have non-negative support when'
+        f' `media_effects_dist`="{media_effects_dist}". Found negative effect'
+        f' in {dist.name}.'
+    )
+
+
 def distributions_are_equal(
     a: tfp.distributions.Distribution, b: tfp.distributions.Distribution
 ) -> bool: