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

meridian/constants.py

@@ -95,6 +95,35 @@ POSSIBLE_INPUT_DATA_ARRAY_NAMES = (
     + MEDIA_INPUT_DATA_ARRAY_NAMES
     + RF_INPUT_DATA_ARRAY_NAMES
 )
+PAID_DATA = (
+    MEDIA,
+    REACH,
+    FREQUENCY,
+    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 = (
+    MEDIA,
+    REACH,
+    FREQUENCY,
+) + 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 +572,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 +621,4 @@ CARD_STATS = 'stats'
 
 # VegaLite common params.
 VEGALITE_FACET_DEFAULT_WIDTH = 400
+VEGALITE_FACET_LARGE_WIDTH = 500

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/data/load.py

@@ -950,7 +950,7 @@ class DataFrameDataLoader(InputDataLoader):
         raise ValueError('NA values found in the organic_frequency columns.')
 
     # Determine columns in which NAs are expected in the lagged-media period.
-    na_columns = []
+    not_lagged_columns = []
     coords = [
         constants.KPI,
         constants.CONTROLS,
@@ -967,12 +967,12 @@ class DataFrameDataLoader(InputDataLoader):
     for coord in coords:
       columns = getattr(self.coord_to_columns, coord)
       columns = [columns] if isinstance(columns, str) else columns
-      na_columns.extend(columns)
+      not_lagged_columns.extend(columns)
 
     # Dates with at least one non-NA value in columns different from media,
     # reach, frequency, organic_media, organic_reach, and organic_frequency.
     time_column_name = self.coord_to_columns.time
-    no_na_period = self.df[(~self.df[na_columns].isna()).any(axis=1)][
+    no_na_period = self.df[(~self.df[not_lagged_columns].isna()).any(axis=1)][
         time_column_name
     ].unique()
 
@@ -999,13 +999,16 @@ class DataFrameDataLoader(InputDataLoader):
     # organic_frequency.
     not_lagged_data = self.df.loc[
         self.df[time_column_name].isin(no_na_period),
-        na_columns,
+        not_lagged_columns,
     ]
     if not_lagged_data.isna().any(axis=None):
+      incorrect_columns = []
+      for column in not_lagged_columns:
+        if not_lagged_data[column].isna().any(axis=None):
+          incorrect_columns.append(column)
       raise ValueError(
-          'NA values found in non-media columns outside the lagged-media'
-          f' period {na_period} (continuous window of 100% NA values in all'
-          ' non-media columns).'
+          f'NA values found in columns {incorrect_columns} within the modeling'
+          ' time window (time periods where the KPI is modeled).'
       )
 
   def load(self) -> input_data.InputData:

meridian/model/model.py

@@ -1030,7 +1030,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 +1080,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)