google-meridian 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

meridian/analysis/review/configs.py

@@ -0,0 +1,110 @@
+# 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.
+
+"""Configurations for the Model Quality Checks."""
+
+import dataclasses
+
+
+@dataclasses.dataclass(frozen=True)
+class BaseConfig:
+  """Base class for all check configurations."""
+
+
+@dataclasses.dataclass(frozen=True)
+class ConvergenceConfig(BaseConfig):
+  """Configuration for the Convergence Check.
+
+  Attributes:
+    convergence_threshold: The threshold for the R-hat statistic to determine if
+      the model has converged. R-hat values below this are considered converged.
+    not_fully_convergence_threshold: The threshold for the R-hat statistic to
+      determine if the model is not fully converged but potentially acceptable.
+      R-hat values between `convergence_threshold` and this value are considered
+      not fully converged. R-hat values above this threshold are considered not
+      converged.
+  """
+
+  convergence_threshold: float = 1.2
+  not_fully_convergence_threshold: float = 10.0
+
+
+@dataclasses.dataclass(frozen=True)
+class ROIConsistencyConfig(BaseConfig):
+  """Configuration for the ROI Consistency Check.
+
+  This check verifies if the posterior median of the ROI falls within a
+  reasonable range of the prior distribution.
+
+  Attributes:
+    prior_lower_quantile: The lower quantile of the ROI prior distribution to
+      define the lower bound of the reasonable range.
+    prior_upper_quantile: The upper quantile of the ROI prior distribution to
+      define the upper bound of the reasonable range.
+  """
+
+  prior_lower_quantile: float = 0.01
+  prior_upper_quantile: float = 0.99
+
+
+@dataclasses.dataclass(frozen=True)
+class BaselineConfig(BaseConfig):
+  """Configuration for the Baseline Check.
+
+  This check warns if there is a high probability of a negative baseline.
+
+  Attributes:
+    negative_baseline_prob_review_threshold: Probability threshold for a
+      review. If the probability of a negative baseline is above this value, a
+      review is issued.
+    negative_baseline_prob_fail_threshold: Probability threshold for a failure.
+      If the probability of a negative baseline is above this value, the check
+      fails.
+  """
+
+  negative_baseline_prob_review_threshold: float = 0.2
+  negative_baseline_prob_fail_threshold: float = 0.8
+
+
+@dataclasses.dataclass(frozen=True)
+class BayesianPPPConfig(BaseConfig):
+  """Configuration for the Bayesian Posterior Predictive P-value Check.
+
+  Attributes:
+    ppp_threshold: P-value threshold for posterior predictive check.
+  """
+
+  ppp_threshold: float = 0.05
+
+
+@dataclasses.dataclass(frozen=True)
+class GoodnessOfFitConfig(BaseConfig):
+  """An empty config for the Goodness of Fit Check."""
+
+
+@dataclasses.dataclass(frozen=True)
+class PriorPosteriorShiftConfig(BaseConfig):
+  """Configuration for the Prior-Posterior Shift Check.
+
+  Attributes:
+    n_bootstraps: Number of bootstrap samples to use for calculating posterior
+      statistics.
+    alpha: Significance level for detecting a shift between prior and posterior
+      distributions.
+    seed: Random seed for reproducibility of bootstrap sampling.
+  """
+
+  n_bootstraps: int = 1000
+  alpha: float = 0.05
+  seed: int = 42

meridian/analysis/review/constants.py

@@ -0,0 +1,40 @@
+# 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.
+
+"""Constants for model review."""
+
+RHAT = "rhat"
+PARAMETER = "parameter"
+CONVERGENCE_THRESHOLD = "convergence_threshold"
+CHANNELS_LOW_HIGH = "channels_low_high"
+PRIOR_ROI_LO = "prior_roi_lo"
+PRIOR_ROI_HI = "prior_roi_hi"
+POSTERIOR_ROI_MEAN = "posterior_roi_mean"
+QUANTILE_NOT_DEFINED_MSG = "quantile_not_defined_msg"
+INF_CHANNELS_MSG = "inf_channels_msg"
+LOW_HIGH_CHANNELS_MSG = "low_high_channels_msg"
+NEGATIVE_BASELINE_PROB = "negative_baseline_prob"
+NEGATIVE_BASELINE_PROB_FAIL_THRESHOLD = "negative_baseline_prob_fail_threshold"
+NEGATIVE_BASELINE_PROB_REVIEW_THRESHOLD = (
+    "negative_baseline_prob_review_threshold"
+)
+R_SQUARED = "r_squared"
+MAPE = "mape"
+WMAPE = "wmape"
+MEAN = "mean"
+VARIANCE = "variance"
+MEDIAN = "median"
+Q1 = "q1"
+Q3 = "q3"
+BAYESIAN_PPP = "bayesian_ppp"

meridian/analysis/review/results.py

@@ -0,0 +1,544 @@
+# 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.
+
+"""Data structures for the Model Quality Checks results."""
+
+import dataclasses
+import enum
+from typing import Any
+from meridian.analysis.review import constants
+
+
+# ==============================================================================
+# Base classes
+# ==============================================================================
+@enum.unique
+class Status(enum.Enum):
+  PASS = enum.auto()
+  REVIEW = enum.auto()
+  FAIL = enum.auto()
+
+
+class BaseCase:
+  """Base class for all check cases."""
+
+  status: Status
+
+  def __init__(self, status: Status):
+    """Initializes the base case with a status."""
+    self.status = status
+
+
+class ModelCheckCase(BaseCase):
+  """Base class for all model-level check cases."""
+
+  message_template: str
+  recommendation: str | None = None
+
+  def __init__(
+      self,
+      status: Status,
+      message_template: str,
+      recommendation: str | None = None,
+  ):
+    super().__init__(status)
+    self.message_template = message_template
+    self.recommendation = recommendation
+
+
+@dataclasses.dataclass(frozen=True)
+class BaseResultData:
+  """Base class for check result data."""
+
+  case: BaseCase
+  details: dict[str, Any]
+
+
+@dataclasses.dataclass(frozen=True)
+class ChannelResult(BaseResultData):
+  """Base class for channel-level check results."""
+
+  channel_name: str
+
+
+@dataclasses.dataclass(frozen=True)
+class CheckResult(BaseResultData):
+  """Base class for model-level check results."""
+
+  case: ModelCheckCase
+
+  @property
+  def recommendation(self) -> str:
+    """Returns the check result message."""
+    report_str = self.case.message_template.format(**self.details)
+    if self.case.recommendation:
+      return f"{report_str} {self.case.recommendation}"
+    return report_str
+
+
+# ==============================================================================
+# Check: Convergence
+# ==============================================================================
+NOT_FULLY_CONVERGED_RECOMMENDATION = (
+    "Manually inspect the parameters with high R-hat values to determine if the"
+    " results are acceptable for your use case, and consider increasing MCMC"
+    " iterations or investigating model misspecification."
+)
+
+NOT_CONVERGED_RECOMMENDATION = (
+    "We recommend increasing MCMC iterations or investigating model"
+    " misspecification (e.g., priors, multicollinearity) before proceeding."
+)
+
+
+@enum.unique
+class ConvergenceCases(ModelCheckCase, enum.Enum):
+  """Cases for the Convergence Check."""
+
+  CONVERGED = (
+      Status.PASS,
+      (
+          "The model has likely converged, as all parameters have R-hat values"
+          " < {convergence_threshold}."
+      ),
+      None,
+  )
+  NOT_FULLY_CONVERGED = (
+      Status.FAIL,
+      (
+          "The model hasn't fully converged, and the `max_r_hat` for parameter"
+          " `{parameter}` is {rhat:.2f}."
+      ),
+      NOT_FULLY_CONVERGED_RECOMMENDATION,
+  )
+  NOT_CONVERGED = (
+      Status.FAIL,
+      (
+          "The model hasn't converged, and the `max_r_hat` for parameter"
+          " `{parameter}` is {rhat:.2f}."
+      ),
+      NOT_CONVERGED_RECOMMENDATION,
+  )
+
+  def __init__(
+      self,
+      status: Status,
+      message_template: str,
+      recommendation: str | None,
+  ):
+    super().__init__(status, message_template, recommendation)
+
+
+@dataclasses.dataclass(frozen=True)
+class ConvergenceCheckResult(CheckResult):
+  """The immutable result of the Convergence Check."""
+
+  case: ConvergenceCases
+
+  def __post_init__(self):
+    if self.case == ConvergenceCases.CONVERGED and (
+        constants.CONVERGENCE_THRESHOLD not in self.details
+    ):
+      raise ValueError(
+          "The message template 'The model has likely converged, as all"
+          " parameters have R-hat values < {convergence_threshold}'. is"
+          " missing required formatting arguments: convergence_threshold."
+          f" Details: {self.details}."
+      )
+
+
+# ==============================================================================
+# Check: Baseline
+# ==============================================================================
+_BASELINE_FAIL_RECOMMENDATION = (
+    "This high probability points to a statistical error and is a clear signal"
+    " that the model requires adjustment. The model is likely over-crediting"
+    " your treatments. Consider adjusting the model's settings, data, or priors"
+    " to correct this issue."
+)
+_BASELINE_REVIEW_RECOMMENDATION = (
+    "This indicates that the baseline time series occasionally dips into"
+    " negative values. We recommend visually inspecting the baseline time"
+    " series in the Model Fit charts, but don't be overly concerned. An"
+    " occasional, small dip may indicate minor statistical error, which is"
+    " inherent in any model."
+)
+_BASELINE_PASS_RECOMMENDATION = (
+    "We recommend visually inspecting the baseline time series in the Model "
+    "Fit charts to confirm this."
+)
+
+
+@enum.unique
+class BaselineCases(ModelCheckCase, enum.Enum):
+  """Cases for the Baseline Check."""
+
+  PASS = (
+      Status.PASS,
+      (
+          "The posterior probability that the baseline is negative is"
+          " {negative_baseline_prob:.2f}."
+      ),
+      _BASELINE_PASS_RECOMMENDATION,
+  )
+  REVIEW = (
+      Status.REVIEW,
+      (
+          "The posterior probability that the baseline is negative is"
+          " {negative_baseline_prob:.2f}."
+      ),
+      _BASELINE_REVIEW_RECOMMENDATION,
+  )
+  FAIL = (
+      Status.FAIL,
+      (
+          "The posterior probability that the baseline is negative is"
+          " {negative_baseline_prob:.2f}."
+      ),
+      _BASELINE_FAIL_RECOMMENDATION,
+  )
+
+  def __init__(
+      self,
+      status: Status,
+      message_template: str,
+      recommendation: str | None,
+  ):
+    super().__init__(status, message_template, recommendation)
+
+
+@dataclasses.dataclass(frozen=True)
+class BaselineCheckResult(CheckResult):
+  """The immutable result of the Baseline Check."""
+
+  case: BaselineCases
+
+  def __post_init__(self):
+    if self.case is BaselineCases.PASS:
+      return
+    if any(
+        key not in self.details
+        for key in (
+            constants.NEGATIVE_BASELINE_PROB,
+            constants.NEGATIVE_BASELINE_PROB_FAIL_THRESHOLD,
+            constants.NEGATIVE_BASELINE_PROB_REVIEW_THRESHOLD,
+        )
+    ):
+      raise ValueError(
+          "The message template is missing required formatting arguments:"
+          " negative_baseline_prob, negative_baseline_prob_fail_threshold,"
+          " negative_baseline_prob_review_threshold. Details:"
+          f" {self.details}."
+      )
+
+
+# ==============================================================================
+# Check: Bayesian Posterior Predictive P-value
+# ==============================================================================
+_BAYESIAN_PPP_FAIL_RECOMMENDATION = (
+    "The observed total outcome is an extreme outlier compared to the model's"
+    " expected total outcomes, which suggests a systematic lack of fit. We"
+    " recommend reviewing input data quality and re-examining the model"
+    " specification (e.g., priors, transformations) to resolve this issue."
+)
+_BAYESIAN_PPP_PASS_RECOMMENDATION = (
+    "The observed total outcome is consistent with the model's posterior"
+    " predictive distribution."
+)
+
+
+@enum.unique
+class BayesianPPPCases(ModelCheckCase, enum.Enum):
+  """Cases for the Bayesian Posterior Predictive P-value Check."""
+
+  PASS = (
+      Status.PASS,
+      "The Bayesian posterior predictive p-value is {bayesian_ppp:.2f}.",
+      _BAYESIAN_PPP_PASS_RECOMMENDATION,
+  )
+  FAIL = (
+      Status.FAIL,
+      "The Bayesian posterior predictive p-value is {bayesian_ppp:.2f}.",
+      _BAYESIAN_PPP_FAIL_RECOMMENDATION,
+  )
+
+  def __init__(
+      self,
+      status: Status,
+      message_template: str,
+      recommendation: str | None,
+  ):
+    super().__init__(status, message_template, recommendation)
+
+
+@dataclasses.dataclass(frozen=True)
+class BayesianPPPCheckResult(CheckResult):
+  """The immutable result of the Bayesian Posterior Predictive P-value Check."""
+
+  case: BayesianPPPCases
+
+  def __post_init__(self):
+    if constants.BAYESIAN_PPP not in self.details:
+      raise ValueError(
+          "The message template is missing required formatting arguments:"
+          " bayesian_ppp. Details:"
+          f" {self.details}."
+      )
+
+
+# ==============================================================================
+# Check: Goodness of Fit
+# ==============================================================================
+_GOODNESS_OF_FIT_REVIEW_RECOMMENDATION = (
+    "A negative R-squared signals a potential conflict between your priors and"
+    " the data, and it warrants investigation. If this conflict is intentional"
+    " (due to an informative prior), no further action is needed. If it's"
+    " unintentional, we recommend relaxing your priors to be less restrictive."
+)
+
+_GOODNESS_OF_FIT_PASS_RECOMMENDATION = (
+    "These goodness-of-fit metrics are intended for guidance and relative"
+    " comparison."
+)
+
+
+@enum.unique
+class GoodnessOfFitCases(ModelCheckCase, enum.Enum):
+  """Cases for the Goodness of Fit Check."""
+
+  PASS = (
+      Status.PASS,
+      (
+          "R-squared = {r_squared:.4f}, MAPE = {mape:.4f}, and wMAPE ="
+          " {wmape:.4f}."
+      ),
+      _GOODNESS_OF_FIT_PASS_RECOMMENDATION,
+  )
+  REVIEW = (
+      Status.REVIEW,
+      (
+          "R-squared = {r_squared:.4f}, MAPE = {mape:.4f}, and wMAPE ="
+          " {wmape:.4f}."
+      ),
+      _GOODNESS_OF_FIT_REVIEW_RECOMMENDATION,
+  )
+
+  def __init__(
+      self,
+      status: Status,
+      message_template: str,
+      recommendation: str | None,
+  ):
+    super().__init__(status, message_template, recommendation)
+
+
+@dataclasses.dataclass(frozen=True)
+class GoodnessOfFitCheckResult(CheckResult):
+  """The immutable result of the Goodness of Fit Check."""
+
+  case: GoodnessOfFitCases
+
+  def __post_init__(self):
+    if any(
+        key not in self.details
+        for key in (
+            constants.R_SQUARED,
+            constants.MAPE,
+            constants.WMAPE,
+        )
+    ):
+      raise ValueError(
+          "The message template is missing required formatting arguments:"
+          " r_squared, mape, wmape. Details:"
+          f" {self.details}."
+      )
+
+
+# ==============================================================================
+# Check: ROI Consistency
+# ==============================================================================
+_ROI_CONSISTENCY_RECOMMENDATION = (
+    "Please review this result to determine if it is reasonable within your"
+    " business context."
+)
+
+
+@enum.unique
+class ROIConsistencyChannelCases(BaseCase, enum.Enum):
+  """Cases for ROI Consistency Check per channel."""
+
+  ROI_PASS = (Status.PASS, enum.auto())
+  ROI_LOW = (Status.REVIEW, enum.auto())
+  ROI_HIGH = (Status.REVIEW, enum.auto())
+  PRIOR_ROI_QUANTILE_INF = (Status.REVIEW, enum.auto())
+  QUANTILE_NOT_DEFINED = (Status.REVIEW, enum.auto())
+
+  def __init__(self, status: Status, unique_id: Any):
+    super().__init__(status)
+
+
+class ROIConsistencyAggregateCases(ModelCheckCase, enum.Enum):
+  """Cases for ROI Consistency Check aggregate result."""
+
+  PASS = (
+      Status.PASS,
+      (
+          "The posterior distribution of the ROI is within a reasonable range,"
+          " aligning with the custom priors you provided."
+      ),
+      None,
+  )
+  REVIEW = (
+      Status.REVIEW,
+      "{quantile_not_defined_msg}{inf_channels_msg}{low_high_channels_msg}",
+      _ROI_CONSISTENCY_RECOMMENDATION,
+  )
+
+  def __init__(
+      self,
+      status: Status,
+      message_template: str,
+      recommendation: str | None,
+  ):
+    super().__init__(status, message_template, recommendation)
+
+
+@dataclasses.dataclass(frozen=True)
+class ROIConsistencyChannelResult(ChannelResult):
+  """The immutable result of ROI Consistency Check for a single channel."""
+
+  case: ROIConsistencyChannelCases
+
+
+@dataclasses.dataclass(frozen=True)
+class ROIConsistencyCheckResult(CheckResult):
+  """The immutable result of model-level ROI Consistency Check."""
+
+  case: ROIConsistencyAggregateCases
+  channel_results: list[ROIConsistencyChannelResult]
+
+
+# ==============================================================================
+# Check: Prior-Posterior Shift
+# ==============================================================================
+_PPS_REVIEW_RECOMMENDATION = (
+    "Please review these channels to see if this is expected (due to a strong"
+    " priors) or problematic (due to a weak signal)."
+)
+
+
+@enum.unique
+class PriorPosteriorShiftChannelCases(BaseCase, enum.Enum):
+  """Cases for Prior-Posterior Shift Check per channel."""
+
+  SHIFT = (Status.PASS, enum.auto())
+  NO_SHIFT = (Status.REVIEW, enum.auto())
+
+  def __init__(self, status: Status, unique_id: Any):
+    super().__init__(status)
+
+
+class PriorPosteriorShiftAggregateCases(ModelCheckCase, enum.Enum):
+  """Cases for Prior-Posterior Shift Check aggregate result."""
+
+  PASS = (
+      Status.PASS,
+      (
+          "The model has successfully learned from the data. This is a positive"
+          " sign that your data was informative."
+      ),
+      None,
+  )
+  REVIEW = (
+      Status.REVIEW,
+      (
+          "We've detected channel(s) {channels_str} where the posterior"
+          " distribution did not significantly shift from the prior. This"
+          " suggests the data signal for these channels was not strong enough"
+          " to update the model's beliefs."
+      ),
+      _PPS_REVIEW_RECOMMENDATION,
+  )
+
+  def __init__(
+      self,
+      status: Status,
+      message_template: str,
+      recommendation: str | None,
+  ):
+    super().__init__(status, message_template, recommendation)
+
+
+@dataclasses.dataclass(frozen=True)
+class PriorPosteriorShiftChannelResult(ChannelResult):
+  """The result of Prior-Posterior Shift Check for a single channel."""
+
+  case: PriorPosteriorShiftChannelCases
+
+
+@dataclasses.dataclass(frozen=True)
+class PriorPosteriorShiftCheckResult(CheckResult):
+  """The immutable result of model-level Prior-Posterior Shift Check."""
+
+  case: PriorPosteriorShiftAggregateCases
+  channel_results: list[PriorPosteriorShiftChannelResult]
+
+
+# ==============================================================================
+# Review Summary
+# ==============================================================================
+@dataclasses.dataclass(frozen=True)
+class ReviewSummary:
+  """The final summary of all model quality checks.
+
+  Attributes:
+    overall_status: The overall status of all checks.
+    summary_message: A summary message of all checks.
+    results: A list of all check results.
+  """
+
+  overall_status: Status
+  summary_message: str
+  results: list[CheckResult]
+
+  def __repr__(self) -> str:
+    report = []
+    report.append("=" * 40)
+    report.append("Model Quality Checks")
+    report.append("=" * 40)
+    report.append(f"Overall Status: {self.overall_status.name}")
+    report.append(f"Summary: {self.summary_message}")
+    report.append("\nCheck Results:")
+
+    for result in self.results:
+      name = result.__class__.__name__
+      if name.endswith("CheckResult"):
+        title = name[: -len("CheckResult")]
+      else:
+        title = name
+
+      report.append("-" * 40)
+      report.append(f"{title} Check:")
+      report.append(f"  Status: {result.case.status.name}")
+      report.append(f"  Recommendation: {result.recommendation}")
+
+    return "\n".join(report)
+
+  @property
+  def checks_status(self) -> dict[str, str]:
+    """Returns a dictionary of check names and statuses."""
+    return {
+        result.__class__.__name__: result.case.status.name
+        for result in self.results
+    }