google-meridian 1.3.2__py3-none-any.whl → 1.4.0__py3-none-any.whl

meridian/analysis/visualizer.py

@@ -243,6 +243,12 @@ class ModelDiagnostics:
 
     groupby = posterior_df.columns.tolist()
     groupby.remove(parameter)
+
+    parameter_99_max = prior_posterior_df[parameter].quantile(0.99)
+    # Remove outliers that make the chart hard to read.
+    prior_posterior_df[parameter] = prior_posterior_df[parameter].clip(
+        upper=parameter_99_max * c.OUTLIER_CLIP_FACTOR
+    )
     plot = (
         alt.Chart(prior_posterior_df, width=c.VEGALITE_FACET_DEFAULT_WIDTH)
         .transform_density(
@@ -269,7 +275,7 @@ class ModelDiagnostics:
         title=formatter.custom_title_params(
             summary_text.PRIOR_POSTERIOR_DIST_CHART_TITLE
         )
-    ).configure_axis(**formatter.TEXT_CONFIG)
+    ).configure_axis(**formatter.TEXT_CONFIG).interactive()
 
   def plot_rhat_boxplot(self) -> alt.Chart:
     """Plots the R-hat box plot.
@@ -1450,17 +1456,15 @@ class MediaSummary:
 
     Args:
       aggregate_times: If `True`, aggregates the metrics across all time
-        periods.  If `False`, returns time-varying metrics.
+        periods. If `False`, returns time-varying metrics.
 
     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:** `impressions`, `pct_of_impressions`, `spend`,
           `pct_of_spend`, `CPM`, `incremental_outcome`, `pct_of_contribution`,
-          `roi`,
-          `effectiveness`, `mroi`.
+          `roi`, `effectiveness`, `mroi`.
     """
     return self._analyzer.summary_metrics(
         selected_times=self._selected_times,

meridian/constants.py

@@ -755,6 +755,7 @@ STROKE_DASH = (4, 2)
 POINT_SIZE = 80
 INDEPENDENT = 'independent'
 RESPONSE_CURVE_STEP_SIZE = 0.01
+OUTLIER_CLIP_FACTOR = 1.2
 
 
 # Font names.

meridian/data/test_utils.py

@@ -642,6 +642,7 @@ def random_media_da(
     channel_variable_name: str = 'media_channel',
     channel_prefix: str = 'ch_',
     integer_geos: bool = False,
+    nonzero_shift: float = 0.0,
 ) -> xr.DataArray:
   """Generates a sample `media` DataArray.
 
@@ -662,6 +663,7 @@ def random_media_da(
     channel_variable_name: The name of the channel variable
     channel_prefix: The prefix of the channel names
     integer_geos: If True, the geos will be integers.
+    nonzero_shift: A scalar value to add to the generated data.
 
   Returns:
     A DataArray containing random data.
@@ -695,6 +697,8 @@ def random_media_da(
         )
     )
 
+  media = media + nonzero_shift
+
   if explicit_geo_names is None:
     geos = sample_geos(n_geos, integer_geos)
   else:
@@ -736,6 +740,7 @@ def random_organic_media_da(
     explicit_time_index: Sequence[str] | None = None,
     explicit_media_channel_names: Sequence[str] | None = None,
     integer_geos: bool = False,
+    nonzero_shift: float = 0.0,
 ) -> xr.DataArray:
   """Generates a sample `organic_media` DataArray."""
   return random_media_da(
@@ -751,6 +756,7 @@ def random_organic_media_da(
       channel_variable_name='organic_media_channel',
       channel_prefix='organic_media_',
       integer_geos=integer_geos,
+      nonzero_shift=nonzero_shift,
   )
 
 
@@ -761,6 +767,7 @@ def random_media_spend_nd_da(
     seed=0,
     integer_geos: bool = False,
     explicit_media_channel_names: Sequence[str] | None = None,
+    nonzero_shift: float = 0.0,
 ) -> xr.DataArray:
   """Generates a sample N-dimensional `media_spend` DataArray.
 
@@ -781,6 +788,7 @@ def random_media_spend_nd_da(
     integer_geos: If True, the geos will be integers.
     explicit_media_channel_names: If given, ignore `n_media_channels` and use
       this as is.
+    nonzero_shift: A scalar value to add to the generated data.
 
   Returns:
     A DataArray containing the generated `media_spend` data with the given
@@ -818,7 +826,7 @@ def random_media_spend_nd_da(
         f'Shape {dims} not supported by the random_media_spend_nd_da function.'
     )
 
-  media_spend = abs(np.random.normal(1, 1, size=shape))
+  media_spend = abs(np.random.normal(1, 1, size=shape)) + nonzero_shift
 
   return xr.DataArray(
       media_spend,
@@ -1007,8 +1015,27 @@ def random_reach_da(
     channel_variable_name: str = 'rf_channel',
     channel_prefix: str = 'rf_ch_',
     integer_geos: bool = False,
+    nonzero_shift: float = 0.0,
 ) -> xr.DataArray:
-  """Generates a sample `reach` DataArray."""
+  """Generates a sample `reach` DataArray.
+
+  Args:
+    n_geos: Number of geos
+    n_times: Number of time periods
+    n_media_times: Number of media time periods
+    n_rf_channels: Number of reach and frequency channels
+    seed: Random seed used by `np.random.seed()`
+    explicit_rf_channel_names: If given, ignore `n_rf_channels` and use this as
+      is
+    array_name: The name of the array to be created
+    channel_variable_name: The name of the channel variable
+    channel_prefix: The prefix of the channel names
+    integer_geos: If True, the geos will be integers.
+    nonzero_shift: A scalar value to add to the generated data.
+
+  Returns:
+    A DataArray containing random data.
+  """
 
   np.random.seed(seed)
 
@@ -1016,12 +1043,15 @@ def random_reach_da(
   if n_times < n_media_times:
     start_date -= datetime.timedelta(weeks=(n_media_times - n_times))
 
-  reach = np.round(
-      abs(
-          np.random.normal(
-              3000, 100, size=(n_geos, n_media_times, n_rf_channels)
+  reach = (
+      np.round(
+          abs(
+              np.random.normal(
+                  3000, 100, size=(n_geos, n_media_times, n_rf_channels)
+              )
           )
       )
+      + nonzero_shift
   )
 
   channels = (
@@ -1051,6 +1081,7 @@ def random_organic_reach_da(
     seed: int = 0,
     explicit_organic_rf_channel_names: Sequence[str] | None = None,
     integer_geos: bool = False,
+    nonzero_shift: float = 0.0,
 ) -> xr.DataArray:
   """Generates a sample `organic_reach` DataArray."""
   return random_reach_da(
@@ -1064,6 +1095,7 @@ def random_organic_reach_da(
       channel_variable_name='organic_rf_channel',
       channel_prefix='organic_rf_ch_',
       integer_geos=integer_geos,
+      nonzero_shift=nonzero_shift,
   )
 
 
@@ -1078,8 +1110,27 @@ def random_frequency_da(
     channel_variable_name: str = 'rf_channel',
     channel_prefix: str = 'rf_ch_',
     integer_geos: bool = False,
+    nonzero_shift: float = 0.0,
 ) -> xr.DataArray:
-  """Generates a sample `frequency` DataArray."""
+  """Generates a sample `frequency` DataArray.
+
+  Args:
+    n_geos: Number of geos
+    n_times: Number of time periods
+    n_media_times: Number of media time periods
+    n_rf_channels: Number of reach and frequency channels
+    seed: Random seed used by `np.random.seed()`
+    explicit_rf_channel_names: If given, ignore `n_rf_channels` and use this as
+      is
+    array_name: The name of the array to be created
+    channel_variable_name: The name of the channel variable
+    channel_prefix: The prefix of the channel names
+    integer_geos: If True, the geos will be integers.
+    nonzero_shift: A scalar value to add to the generated data.
+
+  Returns:
+    A DataArray containing random data.
+  """
 
   np.random.seed(seed)
 
@@ -1087,8 +1138,9 @@ def random_frequency_da(
   if n_times < n_media_times:
     start_date -= datetime.timedelta(weeks=(n_media_times - n_times))
 
-  frequency = abs(
-      np.random.normal(3, 5, size=(n_geos, n_media_times, n_rf_channels))
+  frequency = (
+      abs(np.random.normal(3, 5, size=(n_geos, n_media_times, n_rf_channels)))
+      + nonzero_shift
   )
 
   channels = (
@@ -1119,6 +1171,7 @@ def random_organic_frequency_da(
     seed: int = 0,
     explicit_organic_rf_channel_names: Sequence[str] | None = None,
     integer_geos: bool = False,
+    nonzero_shift: float = 0.0,
 ) -> xr.DataArray:
   """Generates a sample `organic_frequency` DataArray."""
   return random_frequency_da(
@@ -1132,6 +1185,7 @@ def random_organic_frequency_da(
       channel_variable_name='organic_rf_channel',
       channel_prefix='organic_rf_ch_',
       integer_geos=integer_geos,
+      nonzero_shift=nonzero_shift,
   )
 
 
@@ -1141,6 +1195,7 @@ def random_rf_spend_nd_da(
     n_rf_channels: int | None = None,
     seed=0,
     integer_geos: bool = False,
+    nonzero_shift: float = 0.0,
 ) -> xr.DataArray:
   """Generates a sample N-dimensional `rf_spend` DataArray.
 
@@ -1157,6 +1212,7 @@ def random_rf_spend_nd_da(
     n_rf_channels: Number of channels in the created `rf_spend` array.
     seed: Random seed used by `np.random.seed()`.
     integer_geos: If True, the geos will be integers.
+    nonzero_shift: A scalar value to add to the generated data.
 
   Returns:
     A DataArray containing the generated `rf_spend` data with the given
@@ -1187,7 +1243,7 @@ def random_rf_spend_nd_da(
         f'Shape {dims} not supported by the random_rf_spend_nd_da function.'
     )
 
-  rf_spend = abs(np.random.normal(1, 1, size=shape))
+  rf_spend = abs(np.random.normal(1, 1, size=shape)) + nonzero_shift
 
   return xr.DataArray(
       rf_spend,
@@ -1206,6 +1262,7 @@ def random_non_media_treatments_da(
     date_format: str = c.DATE_FORMAT,
     explicit_time_index: Sequence[str] | None = None,
     integer_geos: bool = False,
+    nonzero_shift: float = 0.0,
 ) -> xr.DataArray:
   """Generates a sample `non_media_treatments` DataArray.
 
@@ -1218,6 +1275,7 @@ def random_non_media_treatments_da(
     date_format: The date format to use for time coordinate labels
     explicit_time_index: If given, ignore `date_format` and use this as is
     integer_geos: If True, the geos will be integers.
+    nonzero_shift: A scalar value to add to the generated data.
 
   Returns:
     A DataArray containing random non-media variable.
@@ -1232,6 +1290,8 @@ def random_non_media_treatments_da(
       non_media_channel,
       size=(n_geos, n_times, n_non_media_channels),
   )
+  non_media_treatments = non_media_treatments + nonzero_shift
+
   return xr.DataArray(
       non_media_treatments,
       dims=['geo', 'time', 'non_media_channel'],
@@ -1268,6 +1328,7 @@ def random_dataset(
     remove_media_time: bool = False,
     integer_geos: bool = False,
     kpi_data_pattern: str = '',
+    nonzero_shift: float = 0.0,
 ) -> xr.Dataset:
   """Generates a random dataset."""
   if n_media_channels:
@@ -1280,6 +1341,7 @@ def random_dataset(
         integer_geos=integer_geos,
         explicit_media_channel_names=explicit_media_channel_names,
         media_value_scales=media_value_scales,
+        nonzero_shift=nonzero_shift,
     )
     media_spend = random_media_spend_nd_da(
         n_geos=n_geos,
@@ -1288,6 +1350,7 @@ def random_dataset(
         explicit_media_channel_names=explicit_media_channel_names,
         seed=seed,
         integer_geos=integer_geos,
+        nonzero_shift=nonzero_shift,
     )
   else:
     media = None
@@ -1301,6 +1364,7 @@ def random_dataset(
         n_rf_channels=n_rf_channels,
         seed=seed,
         integer_geos=integer_geos,
+        nonzero_shift=nonzero_shift,
     )
     frequency = random_frequency_da(
         n_geos=n_geos,
@@ -1309,6 +1373,7 @@ def random_dataset(
         n_rf_channels=n_rf_channels,
         seed=seed,
         integer_geos=integer_geos,
+        nonzero_shift=nonzero_shift,
     )
     rf_spend = random_rf_spend_nd_da(
         n_geos=n_geos,
@@ -1316,6 +1381,7 @@ def random_dataset(
         n_rf_channels=n_rf_channels,
         seed=seed,
         integer_geos=integer_geos,
+        nonzero_shift=nonzero_shift,
     )
   else:
     reach = None
@@ -1352,6 +1418,7 @@ def random_dataset(
         n_non_media_channels=n_non_media_channels,
         seed=seed,
         integer_geos=integer_geos,
+        nonzero_shift=nonzero_shift,
     )
   else:
     non_media_treatments = None
@@ -1364,6 +1431,7 @@ def random_dataset(
         n_organic_media_channels=n_organic_media_channels,
         seed=seed,
         integer_geos=integer_geos,
+        nonzero_shift=nonzero_shift,
     )
   else:
     organic_media = None
@@ -1376,6 +1444,7 @@ def random_dataset(
         n_organic_rf_channels=n_organic_rf_channels,
         seed=seed,
         integer_geos=integer_geos,
+        nonzero_shift=nonzero_shift,
     )
     organic_frequency = random_organic_frequency_da(
         n_geos=n_geos,
@@ -1384,6 +1453,7 @@ def random_dataset(
         n_organic_rf_channels=n_organic_rf_channels,
         seed=seed,
         integer_geos=integer_geos,
+        nonzero_shift=nonzero_shift,
     )
   else:
     organic_reach = None
@@ -1794,6 +1864,7 @@ def sample_input_data_non_revenue_revenue_per_kpi(
     n_organic_media_channels: int | None = None,
     n_organic_rf_channels: int | None = None,
     seed: int = 0,
+    nonzero_shift: float = 0.0,
 ) -> input_data.InputData:
   """Generates sample InputData for `non_revenue` KPI w/ revenue_per_kpi."""
   dataset = random_dataset(
@@ -1807,6 +1878,7 @@ def sample_input_data_non_revenue_revenue_per_kpi(
       n_organic_media_channels=n_organic_media_channels,
       n_organic_rf_channels=n_organic_rf_channels,
       seed=seed,
+      nonzero_shift=nonzero_shift,
   )
   return input_data.InputData(
       kpi=dataset.kpi,

meridian/model/__init__.py

@@ -15,7 +15,9 @@
 """The Meridian API module that models the data."""
 
 from meridian.model import adstock_hill
+from meridian.model import context
 from meridian.model import eda
+from meridian.model import equations
 from meridian.model import knots
 from meridian.model import media
 from meridian.model import model