google-meridian 1.2.1__py3-none-any.whl → 1.3.1__py3-none-any.whl

meridian/analysis/review/reviewer.py

@@ -0,0 +1,186 @@
+# 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.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Implementation of the runner of the Model Quality Checks."""
+
+import typing
+
+import immutabledict
+from meridian import constants
+from meridian.analysis import analyzer as analyzer_module
+from meridian.analysis.review import checks
+from meridian.analysis.review import configs
+from meridian.analysis.review import results
+from meridian.model import prior_distribution
+
+
+CheckType = typing.Type[checks.BaseCheck]
+ConfigInstance = configs.BaseConfig
+ChecksBattery = immutabledict.immutabledict[CheckType, ConfigInstance]
+
+_DEFAULT_POST_CONVERGENCE_CHECKS: ChecksBattery = immutabledict.immutabledict({
+    checks.BaselineCheck: configs.BaselineConfig(),
+    checks.BayesianPPPCheck: configs.BayesianPPPConfig(),
+    checks.GoodnessOfFitCheck: configs.GoodnessOfFitConfig(),
+    checks.PriorPosteriorShiftCheck: configs.PriorPosteriorShiftConfig(),
+    checks.ROIConsistencyCheck: configs.ROIConsistencyConfig(),
+})
+
+
+class ModelReviewer:
+  """Executes a series of quality checks on a Meridian model.
+
+  The reviewer first runs a convergence check. If the model has converged, it
+  proceeds to run a battery of post-convergence checks.
+
+  The default battery of post-convergence checks includes:
+    - BaselineCheck
+    - BayesianPPPCheck
+    - GoodnessOfFitCheck
+    - PriorPosteriorShiftCheck
+    - ROIConsistencyCheck
+  Each with its default configuration.
+
+  This battery of checks can be customized by passing a dictionary to the
+  `post_convergence_checks` argument of the constructor, mapping check
+  classes to their configuration instances. For example, to run only the
+  BaselineCheck with a non-default configuration:
+
+  ```python
+    my_checks = {
+        checks.BaselineCheck: configs.BaselineConfig(
+            negative_baseline_prob_review_threshold=0.1,
+            negative_baseline_prob_fail_threshold=0.5,
+        )
+    }
+    reviewer = ModelReviewer(meridian_model, post_convergence_checks=my_checks)
+  ```
+  """
+
+  def __init__(
+      self,
+      meridian,
+      post_convergence_checks: ChecksBattery = _DEFAULT_POST_CONVERGENCE_CHECKS,
+  ):
+    self._meridian = meridian
+    self._results: list[results.CheckResult] = []
+    self._analyzer = analyzer_module.Analyzer(meridian)
+    self._post_convergence_checks = post_convergence_checks
+
+  def _run_and_handle(self, check_class, config):
+    instance = check_class(self._meridian, self._analyzer, config)  # pytype: disable=not-instantiable
+    self._results.append(instance.run())
+
+  def _uses_roi_priors(self):
+    """Checks if the model uses ROI priors."""
+    return (
+        self._meridian.n_media_channels > 0
+        and self._meridian.model_spec.effective_media_prior_type
+        == constants.TREATMENT_PRIOR_TYPE_ROI
+    ) or (
+        self._meridian.n_rf_channels > 0
+        and self._meridian.model_spec.effective_rf_prior_type
+        == constants.TREATMENT_PRIOR_TYPE_ROI
+    )
+
+  def _has_custom_roi_priors(self):
+    """Checks if the model uses custom ROI priors."""
+    default_distribution = prior_distribution.PriorDistribution()
+    if (
+        self._meridian.n_media_channels > 0
+        and self._meridian.model_spec.effective_media_prior_type
+        == constants.TREATMENT_PRIOR_TYPE_ROI
+    ):
+      if not prior_distribution.distributions_are_equal(
+          self._meridian.model_spec.prior.roi_m, default_distribution.roi_m
+      ):
+        return True
+    if (
+        self._meridian.n_rf_channels > 0
+        and self._meridian.model_spec.effective_rf_prior_type
+        == constants.TREATMENT_PRIOR_TYPE_ROI
+    ):
+      if not prior_distribution.distributions_are_equal(
+          self._meridian.model_spec.prior.roi_rf, default_distribution.roi_rf
+      ):
+        return True
+    return False
+
+  def run(self) -> results.ReviewSummary:
+    """Executes all checks and generates the final summary."""
+    self._results.clear()
+    self._run_and_handle(checks.ConvergenceCheck, configs.ConvergenceConfig())
+
+    # Stop if the model did not converge.
+    if (
+        self._results
+        and self._results[0].case is results.ConvergenceCases.NOT_CONVERGED
+    ):
+      return results.ReviewSummary(
+          overall_status=results.Status.FAIL,
+          summary_message=(
+              "Failed: Model did not converge. Other checks were skipped."
+          ),
+          results=self._results,
+      )
+
+    # Run all other checks in sequence.
+    for check_class, config in self._post_convergence_checks.items():
+      if (
+          check_class == checks.PriorPosteriorShiftCheck
+          and not self._uses_roi_priors()
+      ):
+        # Skip the Prior-Posterior Shift check if no ROI priors are used.
+        continue
+      if (
+          check_class == checks.ROIConsistencyCheck
+          and not self._has_custom_roi_priors()
+      ):
+        # Skip the ROI Consistency check if no custom ROI priors are provided.
+        continue
+      self._run_and_handle(check_class, config)
+
+    # Determine the final overall status.
+    has_failures = any(
+        res.case.status is results.Status.FAIL for res in self._results
+    )
+    has_reviews = any(
+        res.case.status is results.Status.REVIEW for res in self._results
+    )
+
+    if has_failures and has_reviews:
+      overall_status = results.Status.FAIL
+      summary_message = (
+          "Failed: Quality issues were detected in your model. Follow"
+          " recommendations to address any failed checks and review"
+          " results to determine if further action is needed."
+      )
+    elif has_failures:
+      overall_status = results.Status.FAIL
+      summary_message = (
+          "Failed: Quality issues were detected in your model. Address failed"
+          " checks before proceeding."
+      )
+    elif has_reviews:
+      overall_status = results.Status.PASS
+      summary_message = "Passed with reviews: Review is needed."
+    else:
+      overall_status = results.Status.PASS
+      summary_message = "Passed: No major quality issues were identified."
+
+    return results.ReviewSummary(
+        overall_status=overall_status,
+        summary_message=summary_message,
+        results=self._results,
+    )

meridian/analysis/summarizer.py

@@ -20,6 +20,7 @@ import os
 
 import jinja2
 from meridian import constants as c
+from meridian.analysis import analyzer
 from meridian.analysis import formatter
 from meridian.analysis import summary_text
 from meridian.analysis import visualizer
@@ -59,17 +60,18 @@ RESPONSE_CURVES_CARD_SPEC = formatter.CardSpec(
 class Summarizer:
   """Generates HTML summary visualizations from the model fitting."""
 
-  def __init__(self, meridian: model.Meridian):
+  def __init__(self, meridian: model.Meridian, use_kpi: bool = False):
     """Initialize the visualizer classes that are not time-dependent."""
     self._meridian = meridian
+    self._use_kpi = analyzer.Analyzer(meridian)._use_kpi(use_kpi)
 
   @functools.cached_property
   def _model_fit(self):
-    return visualizer.ModelFit(self._meridian)
+    return visualizer.ModelFit(self._meridian, use_kpi=self._use_kpi)
 
   @functools.cached_property
   def _model_diagnostics(self):
-    return visualizer.ModelDiagnostics(self._meridian)
+    return visualizer.ModelDiagnostics(self._meridian, use_kpi=self._use_kpi)
 
   def output_model_results_summary(
       self,
@@ -77,7 +79,6 @@ class Summarizer:
       filepath: str,
       start_date: tc.Date = None,
       end_date: tc.Date = None,
-      use_kpi: bool = False,
   ):
     """Generates and saves the HTML results summary output.
 
@@ -87,18 +88,15 @@ class Summarizer:
       start_date: Optional start date selector, *inclusive*, in _yyyy-mm-dd_
         format.
       end_date: Optional end date selector, *inclusive* in _yyyy-mm-dd_ format.
-      use_kpi: If `True`, calculate the incremental KPI. Otherwise, calculate
-        the incremental revenue using the revenue per KPI (if available).
     """
     os.makedirs(filepath, exist_ok=True)
     with open(os.path.join(filepath, filename), 'w') as f:
-      f.write(self._gen_model_results_summary(start_date, end_date, use_kpi))
+      f.write(self._gen_model_results_summary(start_date, end_date))
 
   def _gen_model_results_summary(
       self,
       start_date: tc.Date = None,
       end_date: tc.Date = None,
-      use_kpi: bool = False,
   ) -> str:
     """Generate HTML results summary output (as sanitized content str)."""
     all_dates = self._meridian.input_data.time_coordinates.all_dates
@@ -144,7 +142,6 @@ class Summarizer:
     cards_htmls = self._create_cards_htmls(
         template_env,
         selected_times=selected_times,
-        use_kpi=use_kpi,
     )
 
     return html_template.render(
@@ -155,29 +152,29 @@ class Summarizer:
       self,
       template_env: jinja2.Environment,
       selected_times: Sequence[str] | None,
-      use_kpi: bool,
   ) -> Sequence[str]:
     """Creates the HTML snippets for cards in the summary page."""
     media_summary = visualizer.MediaSummary(
-        self._meridian, selected_times=selected_times
+        self._meridian, selected_times=selected_times, use_kpi=self._use_kpi
+    )
+    media_effects = visualizer.MediaEffects(
+        self._meridian, use_kpi=self._use_kpi
     )
-    media_effects = visualizer.MediaEffects(self._meridian)
     reach_frequency = (
         visualizer.ReachAndFrequency(
-            self._meridian, selected_times=selected_times
+            self._meridian, selected_times=selected_times, use_kpi=self._use_kpi
         )
         if self._meridian.n_rf_channels > 0
         else None
     )
     cards = [
         self._create_model_fit_card_html(
-            template_env, selected_times=selected_times, use_kpi=use_kpi
+            template_env, selected_times=selected_times
         ),
         self._create_outcome_contrib_card_html(
             template_env,
             media_summary,
             selected_times=selected_times,
-            use_kpi=use_kpi,
         ),
         self._create_performance_breakdown_card_html(
             template_env, media_summary
@@ -188,17 +185,16 @@ class Summarizer:
             media_summary=media_summary,
             media_effects=media_effects,
             reach_frequency=reach_frequency,
-            use_kpi=use_kpi,
         ),
     ]
     return cards
 
   def _create_model_fit_card_html(
-      self, template_env: jinja2.Environment, use_kpi: bool, **kwargs
+      self, template_env: jinja2.Environment, **kwargs
   ) -> str:
     """Creates the HTML snippet for the Model Fit card."""
     model_fit = self._model_fit
-    outcome = self._kpi_or_revenue(use_kpi)
+    outcome = self._kpi_or_revenue()
     expected_actual_outcome_chart = formatter.ChartSpec(
         id=summary_text.EXPECTED_ACTUAL_OUTCOME_CHART_ID,
         description=summary_text.EXPECTED_ACTUAL_OUTCOME_CHART_DESCRIPTION_FORMAT.format(
@@ -207,9 +203,7 @@ class Summarizer:
         chart_json=model_fit.plot_model_fit(**kwargs).to_json(),
     )
 
-    predictive_accuracy_table = self._predictive_accuracy_table_spec(
-        use_kpi=use_kpi, **kwargs
-    )
+    predictive_accuracy_table = self._predictive_accuracy_table_spec(**kwargs)
     insights = summary_text.MODEL_FIT_INSIGHTS_FORMAT
 
     return formatter.create_card_html(
@@ -219,11 +213,9 @@ class Summarizer:
         [expected_actual_outcome_chart, predictive_accuracy_table],
     )
 
-  def _predictive_accuracy_table_spec(
-      self, use_kpi: bool, **kwargs
-  ) -> formatter.TableSpec:
+  def _predictive_accuracy_table_spec(self, **kwargs) -> formatter.TableSpec:
     """Creates the HTML snippet for the predictive accuracy table."""
-    outcome = self._kpi_or_revenue(use_kpi)
+    outcome = self._kpi_or_revenue()
     model_diag = self._model_diagnostics
     table = model_diag.predictive_accuracy_table(column_var=c.METRIC, **kwargs)
 
@@ -284,10 +276,9 @@ class Summarizer:
       template_env: jinja2.Environment,
       media_summary: visualizer.MediaSummary,
       selected_times: Sequence[str] | None,
-      use_kpi: bool,
   ) -> str:
     """Creates the HTML snippet for the Outcome Contrib card."""
-    outcome = self._kpi_or_revenue(use_kpi)
+    outcome = self._kpi_or_revenue()
 
     num_selected_times = (
         self._meridian.n_times
@@ -457,10 +448,9 @@ class Summarizer:
       media_summary: visualizer.MediaSummary,
       media_effects: visualizer.MediaEffects,
       reach_frequency: visualizer.ReachAndFrequency | None,
-      use_kpi: bool,
   ) -> str:
     """Creates the HTML snippet for the Optimal Analyst card."""
-    outcome = self._kpi_or_revenue(use_kpi)
+    outcome = self._kpi_or_revenue()
     charts = []
     charts.append(
         formatter.ChartSpec(
@@ -473,7 +463,6 @@ class Summarizer:
                 selected_times=(
                     frozenset(selected_times) if selected_times else None
                 ),
-                use_kpi=use_kpi,
                 plot_separately=False,
                 include_ci=False,
                 num_channels_displayed=7,
@@ -541,7 +530,5 @@ class Summarizer:
         rf_channel=most_spend_rf_channel
     ).optimal_frequency
 
-  def _kpi_or_revenue(self, use_kpi: bool) -> str:
-    if use_kpi or self._meridian.input_data.revenue_per_kpi is None:
-      return c.KPI.upper()
-    return c.REVENUE
+  def _kpi_or_revenue(self) -> str:
+    return c.KPI.upper() if self._use_kpi else c.REVENUE

meridian/analysis/templates/chips.html.jinja

@@ -18,4 +18,16 @@ limitations under the License.
   <chip>
     Time period: {{ start_date }} - {{ end_date }}
   </chip>
+  {% if selected_geos %}
+    {%- set geo_count = selected_geos | length %}
+    {%- set full_list = selected_geos | join(', ') %}
+    <chip title="Selected: {{ full_list }}">
+      Selected geos:
+      {%- if geo_count > 5 %}
+        {{ selected_geos[:5] | join(', ') }}, + {{ geo_count - 5 }} more
+      {%- else %}
+        {{ full_list }}
+      {%- endif %}
+    </chip>
+  {% endif %}
 </chips>

meridian/analysis/test_utils.py

@@ -726,8 +726,6 @@ INC_OUTCOME_NON_PAID_USE_PRIOR = np.array([[
         2.224e05,
     ],
 ]])
-
-
 INC_OUTCOME_NON_PAID_USE_POSTERIOR = np.array([
     [
         [
@@ -1055,7 +1053,6 @@ INC_OUTCOME_NON_PAID_USE_POSTERIOR = np.array([
     ],
 ])
 
-
 INC_OUTCOME_NON_MEDIA_MAX = np.array([
     [
         [
@@ -1282,7 +1279,6 @@ INC_OUTCOME_NON_MEDIA_MAX = np.array([
         ],
     ],
 ])
-
 INC_OUTCOME_NON_MEDIA_MIX = np.array([
     [
         [
@@ -1509,7 +1505,6 @@ INC_OUTCOME_NON_MEDIA_MIX = np.array([
         ],
     ],
 ])
-
 INC_OUTCOME_NON_MEDIA_FIXED = np.array([
     [
         [
@@ -1737,6 +1732,33 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
     ],
 ])
 
+EXP_OUTCOME_MEDIA_AND_RF = np.array([
+    [
+        32254.154,
+        32296.66,
+        32331.918,
+        32391.336,
+        32797.367,
+        33077.375,
+        33469.82,
+        33316.707,
+        33251.33,
+        33261.21,
+    ],
+    [
+        53146.668,
+        53151.16,
+        53404.375,
+        53814.035,
+        54136.48,
+        54141.82,
+        54581.93,
+        54777.164,
+        54912.758,
+        54915.656,
+    ],
+])
+
 MROI_MEDIA_AND_RF_USE_PRIOR = np.array([[
     [0.3399, 1.7045, 3.1300, 2.7845, 0.3523],
     [0.4540, 1.3445, 0.9966, 0.2985, 0.4917],