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

meridian/model/eda/eda_outcome.py

@@ -29,6 +29,7 @@ __all__ = [
     "StandardDeviationArtifact",
     "VIFArtifact",
     "KpiInvariabilityArtifact",
+    "CostPerMediaUnitArtifact",
     "EDACheckType",
     "ArtifactType",
     "EDAOutcome",
@@ -101,7 +102,8 @@ class PairwiseCorrArtifact(AnalysisArtifact):
   Attributes:
     corr_matrix: Pairwise correlation matrix.
     extreme_corr_var_pairs: DataFrame of variable pairs exceeding the
-      correlation threshold.
+      correlation threshold. Includes 'correlation' and 'abs_correlation'
+      columns, and is sorted by 'abs_correlation' in descending order.
     extreme_corr_threshold: The threshold used to identify extreme correlation
       pairs.
   """
@@ -153,6 +155,23 @@ class KpiInvariabilityArtifact(AnalysisArtifact):
   kpi_stdev: xr.DataArray
 
 
+@dataclasses.dataclass(frozen=True)
+class CostPerMediaUnitArtifact(AnalysisArtifact):
+  """Encapsulates artifacts from a Cost per Media Unit analysis.
+
+  Attributes:
+    cost_per_media_unit_da: DataArray of cost per media unit.
+    cost_media_unit_inconsistency_df: DataFrame of time periods where cost and
+      media units are inconsistent (e.g., zero cost with positive media units,
+      or positive cost with zero media units).
+    outlier_df: DataFrame with outliers of cost per media unit.
+  """
+
+  cost_per_media_unit_da: xr.DataArray
+  cost_media_unit_inconsistency_df: pd.DataFrame
+  outlier_df: pd.DataFrame
+
+
 @enum.unique
 class EDACheckType(enum.Enum):
   """Enumeration for the type of an EDA check."""
@@ -161,6 +180,7 @@ class EDACheckType(enum.Enum):
   STANDARD_DEVIATION = enum.auto()
   MULTICOLLINEARITY = enum.auto()
   KPI_INVARIABILITY = enum.auto()
+  COST_PER_MEDIA_UNIT = enum.auto()
 
 
 ArtifactType = typing.TypeVar("ArtifactType", bound="AnalysisArtifact")

meridian/model/knots.py

@@ -19,6 +19,7 @@ from collections.abc import Collection, Sequence
 import copy
 import dataclasses
 import math
+import pprint
 from typing import Any
 from meridian import constants
 from meridian.data import input_data
@@ -289,6 +290,22 @@ class AKS:
     penalty = geo_scaling_factor * base_penalty
 
     aspline = self.aspline(x=x, y=y, knots=knots, penalty=penalty)
+    # Ensure defined knot range covers at least one of the available knot sets.
+    available_knots_lengths = np.unique(
+        np.fromiter(
+            (len(x) for x in aspline[constants.KNOTS_SELECTED]), dtype=int
+        )
+    ).tolist()
+    if not any(
+        min_internal_knots <= k <= max_internal_knots
+        for k in available_knots_lengths
+    ):
+      raise ValueError(
+          f'The range [{min_internal_knots}, {max_internal_knots}] does not'
+          ' contain any of the available knot lengths:'
+          f' {pprint.pformat(available_knots_lengths)}'
+      )
+
     n_knots = np.array([len(x) for x in aspline[constants.KNOTS_SELECTED]])
     feasible_idx = np.where(
         (n_knots >= min_internal_knots) & (n_knots <= max_internal_knots)

meridian/model/model_test_data.py

@@ -143,6 +143,7 @@ class WithInputDataSamples:
   _short_input_data_with_rf_only: input_data.InputData
   _short_input_data_with_media_and_rf: input_data.InputData
   _national_input_data_media_only: input_data.InputData
+  _national_input_data_rf_only: input_data.InputData
   _national_input_data_media_and_rf: input_data.InputData
   _test_dist_media_and_rf: collections.OrderedDict[str, backend.Tensor]
   _test_dist_media_only: collections.OrderedDict[str, backend.Tensor]
@@ -282,6 +283,16 @@ class WithInputDataSamples:
             seed=0,
         )
     )
+    cls._national_input_data_rf_only = (
+        test_utils.sample_input_data_non_revenue_revenue_per_kpi(
+            n_geos=cls._N_GEOS_NATIONAL,
+            n_times=cls._N_TIMES,
+            n_media_times=cls._N_MEDIA_TIMES,
+            n_controls=cls._N_CONTROLS,
+            n_rf_channels=cls._N_RF_CHANNELS,
+            seed=0,
+        )
+    )
     cls._national_input_data_media_only = (
         test_utils.sample_input_data_non_revenue_revenue_per_kpi(
             n_geos=cls._N_GEOS_NATIONAL,
@@ -581,6 +592,10 @@ class WithInputDataSamples:
   def national_input_data_media_only(self) -> input_data.InputData:
     return self._national_input_data_media_only.copy(deep=True)
 
+  @property
+  def national_input_data_rf_only(self) -> input_data.InputData:
+    return self._national_input_data_rf_only.copy(deep=True)
+
   @property
   def national_input_data_media_and_rf(self) -> input_data.InputData:
     return self._national_input_data_media_and_rf.copy(deep=True)

meridian/{analysis/templates → templates}/card.html.jinja

@@ -1,5 +1,5 @@
 {#
-Copyright 2024 Google LLC
+Copyright 2025 Google LLC
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

meridian/{analysis/templates → templates}/chart.html.jinja

@@ -1,5 +1,5 @@
 {#
-Copyright 2024 Google LLC
+Copyright 2025 Google LLC
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

meridian/{analysis/templates → templates}/chips.html.jinja

@@ -1,5 +1,5 @@
 {#
-Copyright 2024 Google LLC
+Copyright 2025 Google LLC
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

meridian/{analysis → templates}/formatter.py

@@ -88,7 +88,7 @@ AXIS_CONFIG = immutabledict.immutabledict({
 
 
 _template_loader = jinja2.FileSystemLoader(
-    os.path.abspath(os.path.dirname(__file__)) + '/templates'
+    os.path.abspath(os.path.dirname(__file__))
 )
 
 
@@ -206,6 +206,17 @@ def create_template_env() -> jinja2.Environment:
   )
 
 
+def create_summary_html(
+    template_env: jinja2.Environment,
+    title: str,
+    cards: Sequence[str],
+) -> str:
+  """Creates the HTML snippet for the summary page."""
+  return template_env.get_template('summary.html.jinja').render(
+      title=title, cards=cards
+  )
+
+
 def create_card_html(
     template_env: jinja2.Environment,
     card_spec: CardSpec,

meridian/templates/formatter_test.py

@@ -0,0 +1,216 @@
+# 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.
+
+from xml.etree import ElementTree as ET
+
+from absl.testing import absltest
+from absl.testing import parameterized
+from meridian.templates import formatter
+
+
+class FormatterTest(parameterized.TestCase):
+
+  def test_custom_title_params_correct(self):
+    title_params = formatter.custom_title_params('test title')
+    self.assertEqual(
+        title_params.to_dict(),
+        {
+            'anchor': 'start',
+            'color': '#3C4043',
+            'font': 'Google Sans Display',
+            'fontSize': 18,
+            'fontWeight': 'normal',
+            'offset': 10,
+            'text': 'test title',
+        },
+    )
+
+  def test_bar_chart_width(self):
+    num_bars = 3
+    width = formatter.bar_chart_width(num_bars)
+    self.assertEqual(width, 186)
+
+  @parameterized.named_parameters(
+      ('zero_percent', 0.0, '0%'),
+      ('less_than_one_percent', 0.0005, '0.05%'),
+      ('one_percent', 0.01, '1%'),
+      ('greater_than_one_percent', 0.4257, '43%'),
+  )
+  def test_format_percent_correct(self, percent, expected):
+    formatted_percent = formatter.format_percent(percent)
+    self.assertEqual(formatted_percent, expected)
+
+  def test_compact_number_expr_default(self):
+    expr = formatter.compact_number_expr()
+    self.assertEqual(expr, "replace(format(datum.value, '.3~s'), 'G', 'B')")
+
+  def test_compact_number_expr_params(self):
+    expr = formatter.compact_number_expr('other', 2)
+    self.assertEqual(expr, "replace(format(datum.other, '.2~s'), 'G', 'B')")
+
+  @parameterized.named_parameters(
+      ('rounded_up_percent', 0.4257, 15, '42.6% (15)'),
+      ('rounded_down_percent', 0.4251, 15, '42.5% (15)'),
+      ('thousand_value', 0.42, 2e4, '42.0% (20k)'),
+      ('million_value', 0.42, 3e7, '42.0% (30M)'),
+      ('billion_value', 0.42, 4e9, '42.0% (4B)'),
+  )
+  def test_format_number_text_correct(self, percent, value, expected):
+    formatted_text = formatter.format_number_text(percent, value)
+    self.assertEqual(formatted_text, expected)
+
+  @parameterized.named_parameters(
+      ('zero_precision_thousands', 12345, '$', '$12k'),
+      ('round_up_thousands', 14900, '€', '€15k'),
+      ('million_value', 3.21e6, '£', '£3.2M'),
+      ('billion_value_round_up', 4.28e9, '¥', '¥4.3B'),
+      ('negative', -12345, '₮', '-₮12k'),
+  )
+  def test_format_monetary_num_correct(self, num, currency, expected):
+    formatted_number = formatter.format_monetary_num(num, currency)
+    self.assertEqual(formatted_number, expected)
+
+  @parameterized.named_parameters(
+      ('decimals', -0.1234, 2, '$', '-$0.12'),
+      ('zero_precision_thousands', 12345, 0, '', '12k'),
+      ('round_up_thousands', 14900, 0, '$', '$15k'),
+      ('million_value', 3.21e6, 2, '$', '$3.21M'),
+      ('negative', -12345, 0, '$', '-$12k'),
+  )
+  def test_compact_number_correct(self, num, precision, currency, expected):
+    formatted_number = formatter.compact_number(num, precision, currency)
+    self.assertEqual(formatted_number, expected)
+
+  def test_create_summary_html(self):
+    template_env = formatter.create_template_env()
+    title = 'Integration Test Report'
+    cards = ['<card>Card 1</card>', '<card>Card 2</card>']
+
+    html_result = formatter.create_summary_html(template_env, title, cards)
+
+    # Since summary.html contains DOCTYPE (which breaks ElementTree XML parser),
+    # we verify the output using string assertions.
+    self.assertIn('<!DOCTYPE html>', html_result)
+    self.assertIn(title, html_result)
+    self.assertIn('<card>Card 1</card>', html_result)
+    self.assertIn('<card>Card 2</card>', html_result)
+
+  def test_create_card_html_structure(self):
+    template_env = formatter.create_template_env()
+    card_spec = formatter.CardSpec(id='test_id', title='test_title')
+    stats_spec = formatter.StatsSpec(title='stats_title', stat='test_stat')
+    chart_spec = formatter.ChartSpec(
+        'test_chart_id', 'test_chart_json', 'test_chart_description'
+    )
+
+    card_html = ET.fromstring(
+        formatter.create_card_html(
+            template_env, card_spec, 'test_insights', [chart_spec], [stats_spec]
+        )
+    )
+    self.assertEqual(card_html.tag, 'card')
+    self.assertLen(card_html, 4)
+    self.assertEqual(card_html[0].tag, 'card-title')
+    self.assertEqual(card_html[1].tag, 'card-insights')
+    self.assertEqual(card_html[2].tag, 'stats-section')
+    self.assertEqual(card_html[3].tag, 'charts')
+
+  def test_create_card_html_text(self):
+    template_env = formatter.create_template_env()
+    card_spec = formatter.CardSpec(id='test_id', title='test_title')
+    chart_spec = formatter.ChartSpec(
+        'test_chart_id', 'test_chart_json', 'test_chart_description'
+    )
+    card_html = ET.fromstring(
+        formatter.create_card_html(
+            template_env, card_spec, 'test_insights', [chart_spec]
+        )
+    )
+    self.assertContainsSubset('test_title', card_html[0].text)
+    self.assertContainsSubset('test_insights', card_html[1][1].text)
+
+  def test_create_card_html_multiple_charts(self):
+    template_env = formatter.create_template_env()
+    card_spec = formatter.CardSpec(id='test_id', title='test_title')
+    chart_spec1 = formatter.ChartSpec(
+        'test_chart_id1', 'test_chart_json1', 'test_chart_description1'
+    )
+    chart_spec2 = formatter.ChartSpec(
+        'test_chart_id2', 'test_chart_json2', 'test_chart_description2'
+    )
+    card_html = ET.fromstring(
+        formatter.create_card_html(
+            template_env, card_spec, 'test_insights', [chart_spec1, chart_spec2]
+        )
+    )
+    charts = card_html[2]
+    self.assertLen(charts, 4)  # Each chart has 2 items, chart and script.
+
+  def test_create_card_html_chart_structure(self):
+    template_env = formatter.create_template_env()
+    card_spec = formatter.CardSpec(id='test_id', title='test_title')
+    chart_spec = formatter.ChartSpec(
+        'test_chart_id', 'test_chart_json', 'test_chart_description'
+    )
+    card_html = ET.fromstring(
+        formatter.create_card_html(
+            template_env, card_spec, 'test_insights', [chart_spec]
+        )
+    )
+    chart_html = card_html[2]
+    self.assertEqual(chart_html.tag, 'charts')
+    self.assertEqual(chart_html[0].tag, 'chart')
+    self.assertEqual(chart_html[0][0].tag, 'chart-embed')
+    self.assertEqual(chart_html[0][1].tag, 'chart-description')
+    self.assertContainsSubset('test_chart_description', chart_html[0][1].text)
+    self.assertEqual(chart_html[1].tag, 'script')
+    self.assertContainsSubset('test_chart_json', chart_html[1].text)
+
+  def test_create_card_html_mulitple_stats(self):
+    template_env = formatter.create_template_env()
+    card_spec = formatter.CardSpec(id='test_id', title='test_title')
+    stat1 = formatter.StatsSpec(title='stats_title1', stat='test_stat1')
+    stat2 = formatter.StatsSpec(title='stats_title2', stat='test_stat2')
+    card_html = ET.fromstring(
+        formatter.create_card_html(
+            template_env, card_spec, 'test_insights', stats_specs=[stat1, stat2]
+        )
+    )
+    stats = card_html[2]
+    self.assertLen(stats, 2)
+
+  def test_create_card_html_stats_structure(self):
+    template_env = formatter.create_template_env()
+    card_spec = formatter.CardSpec(id='test_id', title='test_title')
+    stats_spec = formatter.StatsSpec(
+        title='stats_title', stat='test_stat', delta='+0.3'
+    )
+    card_html = ET.fromstring(
+        formatter.create_card_html(
+            template_env, card_spec, 'test_insights', stats_specs=[stats_spec]
+        )
+    )
+    stats_html = card_html[2]
+    self.assertEqual(stats_html.tag, 'stats-section')
+    self.assertEqual(stats_html[0].tag, 'stats')
+    self.assertEqual(stats_html[0][0].tag, 'stats-title')
+    self.assertEqual(stats_html[0][0].text, 'stats_title')
+    self.assertEqual(stats_html[0][1].tag, 'stat')
+    self.assertEqual(stats_html[0][1].text, 'test_stat')
+    self.assertEqual(stats_html[0][2].tag, 'delta')
+    self.assertContainsSubset('+0.3', stats_html[0][2].text)
+
+
+if __name__ == '__main__':
+  absltest.main()

meridian/{analysis/templates → templates}/insights.html.jinja

@@ -1,5 +1,5 @@
 {#
-Copyright 2024 Google LLC
+Copyright 2025 Google LLC
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

meridian/{analysis/templates → templates}/stats.html.jinja

@@ -1,5 +1,5 @@
 {#
-Copyright 2024 Google LLC
+Copyright 2025 Google LLC
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

meridian/{analysis/templates → templates}/style.css

@@ -1,5 +1,5 @@
 /**
- * Copyright 2024 Google LLC
+ * Copyright 2025 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

meridian/{analysis/templates → templates}/style.scss

@@ -1,5 +1,5 @@
 /**
- * Copyright 2024 Google LLC
+ * Copyright 2025 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

meridian/{analysis/templates → templates}/summary.html.jinja

@@ -1,5 +1,5 @@
 <!--
-Copyright 2024 Google LLC
+Copyright 2025 Google LLC
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -42,7 +42,9 @@ limitations under the License.
       </div>
     </div>
 
-    {% include "chips.html.jinja" %}
+    {% if start_date is defined and start_date %}
+      {% include "chips.html.jinja" %}
+    {% endif %}
 
     <cards>
       {# Each card is laid out in a grid. See; .card display layout. #}

meridian/{analysis/templates → templates}/table.html.jinja

@@ -1,5 +1,5 @@
 {#
-Copyright 2024 Google LLC
+Copyright 2025 Google LLC
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

meridian/version.py

@@ -14,4 +14,4 @@
 
 """Module for Meridian version."""
 
-__version__ = "1.3.0"
+__version__ = "1.3.2"

schema/__init__.py

@@ -0,0 +1,30 @@
+# 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.
+
+"""Module containing MMM schema library."""
+
+try:  # pylint: disable=g-statement-before-imports
+  # A quick check for schema dependencies.
+  # If this fails, it's likely because meridian was installed without
+  # `pip install google-meridian[schema]`.
+  from mmm.v1.model.meridian import meridian_model_pb2  # pylint: disable=g-import-not-at-top
+except ModuleNotFoundError as exc:
+  raise ImportError(
+      'Schema dependencies not found. Please install meridian with '
+      '`pip install google-meridian[schema]`.'
+  ) from exc
+
+# pylint: disable=g-import-not-at-top
+from schema import serde
+from schema import utils

schema/serde/__init__.py

@@ -0,0 +1,26 @@
+# 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.
+
+"""A serialization and deserialization library for Meridian models.
+
+For entry points API, see `meridian_serde` module docs.
+"""
+
+from schema.serde import constants
+from schema.serde import distribution
+from schema.serde import eda_spec
+from schema.serde import hyperparameters
+from schema.serde import inference_data
+from schema.serde import meridian_serde
+from schema.serde import serde

schema/serde/constants.py

@@ -0,0 +1,48 @@
+# 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 shared across the Meridian serde library."""
+
+# Constants for hyperparameters protobuf structure
+BASELINE_GEO_ONEOF = 'baseline_geo_oneof'
+BASELINE_GEO_INT = 'baseline_geo_int'
+BASELINE_GEO_STRING = 'baseline_geo_string'
+CONTROL_POPULATION_SCALING_ID = 'control_population_scaling_id'
+HOLDOUT_ID = 'holdout_id'
+NON_MEDIA_POPULATION_SCALING_ID = 'non_media_population_scaling_id'
+ADSTOCK_DECAY_SPEC = 'adstock_decay_spec'
+GLOBAL_ADSTOCK_DECAY = 'global_adstock_decay'
+ADSTOCK_DECAY_BY_CHANNEL = 'adstock_decay_by_channel'
+DEFAULT_DECAY = 'geometric'
+
+# Constants for marketing data protobuf structure
+GEO_INFO = 'geo_info'
+METADATA = 'metadata'
+REACH_FREQUENCY = 'reach_frequency'
+
+# Constants for distribution protobuf structure
+DISTRIBUTION_TYPE = 'distribution_type'
+BATCH_BROADCAST_DISTRIBUTION = 'batch_broadcast'
+DETERMINISTIC_DISTRIBUTION = 'deterministic'
+HALF_NORMAL_DISTRIBUTION = 'half_normal'
+LOG_NORMAL_DISTRIBUTION = 'log_normal'
+NORMAL_DISTRIBUTION = 'normal'
+TRANSFORMED_DISTRIBUTION = 'transformed'
+TRUNCATED_NORMAL_DISTRIBUTION = 'truncated_normal'
+UNIFORM_DISTRIBUTION = 'uniform'
+BETA_DISTRIBUTION = 'beta'
+BIJECTOR_TYPE = 'bijector_type'
+SHIFT_BIJECTOR = 'shift'
+SCALE_BIJECTOR = 'scale'
+RECIPROCAL_BIJECTOR = 'reciprocal'