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

meridian/templates/formatter.py

@@ -18,6 +18,7 @@ from collections.abc import Sequence
 import dataclasses
 import math
 import os
+import re
 
 import altair as alt
 import immutabledict
@@ -46,6 +47,9 @@ class ChartSpec:
   id: str
   chart_json: str
   description: str | None = None
+  errors: Sequence[str] | None = None
+  warnings: Sequence[str] | None = None
+  infos: Sequence[str] | None = None
 
 
 @dataclasses.dataclass(frozen=True)
@@ -55,6 +59,9 @@ class TableSpec:
   column_headers: Sequence[str]
   row_values: Sequence[Sequence[str]]
   description: str | None = None
+  errors: Sequence[str] | None = None
+  warnings: Sequence[str] | None = None
+  infos: Sequence[str] | None = None
 
 
 @dataclasses.dataclass(frozen=True)
@@ -198,6 +205,25 @@ def format_monetary_num(num: float, currency: str) -> str:
   return compact_number(num, precision=precision, currency=currency)
 
 
+def format_col_names(headers: Sequence[str]) -> Sequence[str]:
+  """Turns underscores to spaces and capitalizes words.
+
+  Ex. ['col_name', ...] to ['Col Name', ...])
+
+  Args:
+    headers: The list of column names to format.
+
+  Returns:
+    Human readable list of column names.
+  """
+  # \b matches the start of a word
+  # [a-z] matches only if the first letter is lowercase
+  return [
+      re.sub(r'\b[a-z]', lambda m: m.group().upper(), header.replace('_', ' '))
+      for header in headers
+  ]
+
+
 def create_template_env() -> jinja2.Environment:
   """Creates a Jinja2 template environment."""
   return jinja2.Environment(
@@ -220,19 +246,20 @@ def create_summary_html(
 def create_card_html(
     template_env: jinja2.Environment,
     card_spec: CardSpec,
-    insights: str,
+    insights: str | None = None,
     chart_specs: Sequence[ChartSpec | TableSpec] | None = None,
     stats_specs: Sequence[StatsSpec] | None = None,
 ) -> str:
   """Creates a card's HTML snippet that includes given card and chart specs."""
-  insights_html = template_env.get_template('insights.html.jinja').render(
-      text_html=insights
-  )
   card_params = dataclasses.asdict(card_spec)
   card_params[c.CARD_CHARTS] = (
       _create_charts_htmls(template_env, chart_specs) if chart_specs else None
   )
-  card_params[c.CARD_INSIGHTS] = insights_html
+  if insights:
+    insights_html = template_env.get_template('insights.html.jinja').render(
+        text_html=insights
+    )
+    card_params[c.CARD_INSIGHTS] = insights_html
   card_params[c.CARD_STATS] = (
       _create_stats_htmls(template_env, stats_specs) if stats_specs else None
   )
@@ -267,3 +294,12 @@ def _create_charts_htmls(
     else:
       htmls.append(table_template.render(dataclasses.asdict(spec)))
   return htmls
+
+
+def create_finding_html(
+    template_env: jinja2.Environment, text: str, finding_type: str
+) -> str:
+  """Generates an HTML tag for the table finding."""
+  return template_env.get_template('finding.html.jinja').render(
+      finding_class=finding_type, text=text
+  )

meridian/templates/formatter_test.py

@@ -92,6 +92,36 @@ class FormatterTest(parameterized.TestCase):
     formatted_number = formatter.compact_number(num, precision, currency)
     self.assertEqual(formatted_number, expected)
 
+  @parameterized.named_parameters(
+      dict(
+          testcase_name='basic_snake_case',
+          input_headers=['finding_cause'],
+          expected=['Finding Cause'],
+      ),
+      dict(
+          testcase_name='multiple_columns',
+          input_headers=['geo', 'time_index', 'channel_name'],
+          expected=['Geo', 'Time Index', 'Channel Name'],
+      ),
+      dict(
+          testcase_name='preserves_acronyms',
+          input_headers=['VIF_score', 'national_KPI'],
+          expected=['VIF Score', 'National KPI'],
+      ),
+      dict(
+          testcase_name='handles_tuples_input',
+          input_headers=('row_id', 'value'),
+          expected=['Row Id', 'Value'],
+      ),
+      dict(
+          testcase_name='empty_input',
+          input_headers=[],
+          expected=[],
+      ),
+  )
+  def test_format_col_names(self, input_headers, expected):
+    self.assertEqual(formatter.format_col_names(input_headers), expected)
+
   def test_create_summary_html(self):
     template_env = formatter.create_template_env()
     title = 'Integration Test Report'
@@ -211,6 +241,103 @@ class FormatterTest(parameterized.TestCase):
     self.assertEqual(stats_html[0][2].tag, 'delta')
     self.assertContainsSubset('+0.3', stats_html[0][2].text)
 
+  def test_create_card_html_no_insights(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')
+
+    card_html = ET.fromstring(
+        formatter.create_card_html(
+            template_env, card_spec, insights=None, stats_specs=[stats_spec]
+        )
+    )
+
+    self.assertEqual(card_html.tag, 'card')
+    self.assertIsNone(card_html.find('card-insights'))
+    self.assertIsNotNone(card_html.find('stats-section'))
+
+  def test_create_card_html_chart_findings(self):
+    """Tests that errors, warnings, and infos render inside a chart."""
+    template_env = formatter.create_template_env()
+    card_spec = formatter.CardSpec(id='test_id', title='test_title')
+    chart_spec = formatter.ChartSpec(
+        id='id',
+        chart_json='{}',
+        errors=['Chart Error'],
+        warnings=['Chart Warning'],
+        infos=['Chart Info'],
+    )
+    card_html = ET.fromstring(
+        formatter.create_card_html(
+            template_env, card_spec, insights=None, chart_specs=[chart_spec]
+        )
+    )
+
+    charts_elem = card_html.find('charts')
+    self.assertIsNotNone(charts_elem)
+    chart_elem = charts_elem.find('chart')
+    self.assertIsNotNone(chart_elem)
+
+    error_elem = chart_elem.find('errors')
+    self.assertIsNotNone(error_elem)
+    error_p = error_elem.find('p')
+    self.assertIsNotNone(error_p)
+    self.assertIn('Chart Error', error_p.text)
+
+    warning_elem = chart_elem.find('warnings')
+    self.assertIsNotNone(warning_elem)
+    warning_p = warning_elem.find('p')
+    self.assertIsNotNone(warning_p)
+    self.assertIn('Chart Warning', warning_p.text)
+
+    info_elem = chart_elem.find('infos')
+    self.assertIsNotNone(info_elem)
+    info_p = info_elem.find('p')
+    self.assertIsNotNone(info_p)
+    self.assertIn('Chart Info', info_p.text)
+
+  def test_create_card_html_table_findings(self):
+    """Tests that errors, warnings, and infos render inside a table."""
+    template_env = formatter.create_template_env()
+    card_spec = formatter.CardSpec(id='test_id', title='test_title')
+    table_spec = formatter.TableSpec(
+        id='table_id',
+        title='Table Title',
+        column_headers=['Col1'],
+        row_values=[['Val1']],
+        errors=['Table Error'],
+        warnings=['Table Warning'],
+        infos=['Table Info'],
+    )
+    card_html = ET.fromstring(
+        formatter.create_card_html(
+            template_env, card_spec, insights=None, chart_specs=[table_spec]
+        )
+    )
+
+    charts_elem = card_html.find('charts')
+    self.assertIsNotNone(charts_elem)
+    table_elem = charts_elem.find('chart-table')
+    self.assertIsNotNone(table_elem)
+
+    error_elem = table_elem.find('errors')
+    self.assertIsNotNone(error_elem)
+    error_p = error_elem.find('p')
+    self.assertIsNotNone(error_p)
+    self.assertIn('Table Error', error_p.text)
+
+    warning_elem = table_elem.find('warnings')
+    self.assertIsNotNone(warning_elem)
+    warning_p = warning_elem.find('p')
+    self.assertIsNotNone(warning_p)
+    self.assertIn('Table Warning', warning_p.text)
+
+    info_elem = table_elem.find('infos')
+    self.assertIsNotNone(info_elem)
+    info_p = info_elem.find('p')
+    self.assertIsNotNone(info_p)
+    self.assertIn('Table Info', info_p.text)
+
 
 if __name__ == '__main__':
   absltest.main()

meridian/templates/style.css

@@ -86,11 +86,30 @@ card {
     font-weight: 400;
     line-height: 50px; }
   card > card-insights {
+    background: #eee; }
+  card errors,
+  card warnings,
+  card infos {
+    margin-top: -39px;
+    margin-left: -69px;
+    margin-right: -69px; }
+  card errors {
+    background: #f8d7da; }
+  card warnings {
+    background: #fff3cd; }
+  card infos {
+    background: #dae8fc; }
+  card > card-insights,
+  card errors,
+  card warnings,
+  card infos {
     display: flex;
     flex-direction: row;
-    padding: 22px 20px;
-    background: #eee; }
-    card > card-insights p.insights-text {
+    padding: 22px 20px; }
+    card > card-insights p,
+    card errors p,
+    card warnings p,
+    card infos p {
       margin: 0px 25px;
       color: var(--Grey-800, #3c4043);
       font-family: Roboto;
@@ -110,7 +129,10 @@ charts {
   charts chart {
     display: flex;
     flex-flow: column nowrap;
-    gap: 12px; }
+    gap: 12px;
+    flex: 1 1 auto;
+    min-width: 0;
+    max-width: 100%; }
     charts chart > chart-description {
       color: var(--Grey-800, #3c4043);
       font-family: "Google Sans Display", "Google Sans", sans-serif;
@@ -119,10 +141,18 @@ charts {
       font-weight: 400;
       line-height: 16px;
       max-width: 450px; }
+  charts chart-embed {
+    display: block;
+    width: 100%;
+    overflow-x: auto;
+    padding: 10px 5px 20px 2px; }
   charts chart-table {
     display: flex;
     flex-flow: column nowrap;
-    gap: 12px; }
+    gap: 12px;
+    flex: 1 1 auto;
+    min-width: 0;
+    max-width: 100%; }
     charts chart-table .chart-table-title {
       color: var(--Grey-800, #3c4043);
       font-family: "Google Sans Display", "Google Sans", sans-serif;
@@ -138,7 +168,10 @@ charts {
       font-style: normal;
       font-weight: 400;
       line-height: 20px;
-      letter-spacing: 0.2px; }
+      letter-spacing: 0.2px;
+      width: 100%;
+      overflow-x: auto;
+      padding-bottom: 20px; }
       charts chart-table .chart-table-content table {
         border-radius: 4px;
         border: 1px solid var(--Grey-300, #dadce0);
@@ -160,15 +193,39 @@ charts {
       font-weight: 400;
       line-height: 16px;
       max-width: 450px; }
+    charts chart-table finding {
+      display: flex;
+      width: fit-content;
+      align-items: center;
+      justify-content: center;
+      white-space: nowrap;
+      padding: 4px 12px;
+      border-radius: 16px;
+      margin: 2px 4px 2px 0;
+      font-family: "Google Sans Display", "Google Sans", sans-serif;
+      font-weight: 500;
+      font-size: 13px;
+      line-height: 20px; }
+      charts chart-table finding.error {
+        background-color: #f8d7da;
+        color: var(--Red-600, #d93025); }
+      charts chart-table finding.attention {
+        background-color: #fff3cd;
+        color: #664d03; }
+      charts chart-table finding.info {
+        background-color: #dae8fc;
+        color: var(--blue-700, #1967d2); }
 
 stats-section {
   display: flex;
-  flex-direction: row;
-  justify-content: space-around;
+  flex-flow: row wrap;
+  justify-content: flex-start;
+  gap: 40px;
   padding: 32px; }
   stats-section stats {
     display: flex;
-    flex-direction: column; }
+    flex-direction: column;
+    flex: 0 0 auto; }
     stats-section stats > stats-title {
       color: var(--grey-900, #202124);
       font-family: Roboto;

meridian/templates/style.scss

@@ -20,6 +20,10 @@ $insights_bg_grey: #eee;
 $text_grey: var(--Grey-800, #3c4043);
 $text_green: var(--Green-500, #34a853);
 $text_red: var(--Red-600, #d93025);
+$error_red: #f8d7da;
+$text_yellow: #664d03;
+$warning_yellow: #fff3cd;
+$info_blue: #dae8fc;
 
 $google_sans: 'Google Sans Display', 'Google Sans', sans-serif;
 $roboto: Roboto;
@@ -112,12 +116,38 @@ card {
   }
 
   > card-insights {
+    background: $insights_bg_grey;
+  }
+
+  errors,
+  warnings,
+  infos {
+    margin-top: -39px;
+    margin-left: -69px;
+    margin-right: -69px;
+  }
+
+  errors {
+    background: $error_red;
+  }
+
+  warnings {
+    background: $warning_yellow;
+  }
+
+  infos {
+    background: $info_blue;
+  }
+
+  > card-insights,
+  errors,
+  warnings,
+  infos {
     display: flex;
     flex-direction: row;
     padding: 22px 20px;
-    background: $insights_bg_grey;
 
-    p.insights-text {
+    p {
       margin: 0px 25px;
       color: $text_grey;
 
@@ -149,6 +179,9 @@ charts {
 
   chart {
     @include chart-style;
+    flex: 1 1 auto;
+    min-width: 0;
+    max-width: 100%;
 
     > chart-description {
       color: $text_grey;
@@ -162,8 +195,19 @@ charts {
     }
   }
 
+  chart-embed {
+    display: block;
+    width: 100%;
+
+    overflow-x: auto;
+    padding: 10px 5px 20px 2px;
+  }
+
   chart-table {
     @include chart-style;
+    flex: 1 1 auto;
+    min-width: 0;
+    max-width: 100%;
 
     .chart-table-title {
       color: $text_grey;
@@ -185,6 +229,9 @@ charts {
       line-height: 20px;
       letter-spacing: 0.2px;
 
+      width: 100%;
+      overflow-x: auto;
+      padding-bottom: 20px;
       @mixin border-style {
         border-radius: 4px;
         border: 1px solid var(--Grey-300, #dadce0);
@@ -216,18 +263,52 @@ charts {
       line-height: 16px;
       max-width: 450px;
     }
+
+    finding {
+      display: flex;
+      width: fit-content;
+      align-items: center;
+      justify-content: center;
+      white-space: nowrap;
+
+      padding: 4px 12px;
+      border-radius: 16px;
+      margin: 2px 4px 2px 0;
+
+      font-family: $google_sans;
+      font-weight: 500;
+      font-size: 13px;
+      line-height: 20px;
+
+      &.error {
+        background-color: $error_red;
+        color: $text_red;
+      }
+
+      &.attention {
+        background-color: $warning_yellow;
+        color: $text_yellow;
+      }
+
+      &.info {
+        background-color: $info_blue;
+        color: $chip_blue;
+      }
+    }
   }
 }
 
 stats-section {
   display: flex;
-  flex-direction: row;
-  justify-content: space-around;
+  flex-flow: row wrap;
+  justify-content: flex-start;
+  gap: 40px;
   padding: 32px;
 
   stats {
     display: flex;
     flex-direction: column;
+    flex: 0 0 auto;
 
     > stats-title {
       color: $title_dark_grey;

meridian/templates/table.html.jinja

@@ -15,6 +15,7 @@ limitations under the License.
 #}
 
 <chart-table id="{{ id }}">
+  {% include "findings.html.jinja" %}
   <div class="chart-table-title">{{ title }}</div>
   <div class="chart-table-content">
     <table>

meridian/version.py

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

scenarioplanner/__init__.py

@@ -0,0 +1,42 @@
+# 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.
+
+"""Generates Meridian Scenario Planner Dashboards in Looker Studio.
+
+This package provides tools to create and manage Meridian dashboards. It helps
+transform data from the MMM (Marketing Mix Modeling) schema into a custom
+Looker Studio dashboard, which can be shared via a URL.
+
+The typical workflow is:
+
+  1. Analyze MMM data into the appropriate schema.
+  2. Generate UI-specific proto messages from this data using
+     `mmm_ui_proto_generator`.
+  3. Build a Looker Studio URL that embeds this UI proto data using
+     `linkingapi`.
+
+Key functionalities include:
+
+  - `linkingapi`: Builds Looker Studio report URLs with embedded data sources.
+    This allows for the creation of pre-configured reports.
+  - `mmm_ui_proto_generator`: Generates a `Mmm` proto message for the Meridian
+    Scenario Planner UI. It takes structured MMM data and transforms it into the
+    specific proto format that the dashboard frontend expects.
+  - `converters`: Provides utilities to convert and transform analyzed model
+    data into a data format that Looker Studio expects.
+"""
+
+from scenarioplanner import converters
+from scenarioplanner import linkingapi
+from scenarioplanner import mmm_ui_proto_generator

scenarioplanner/converters/__init__.py

@@ -0,0 +1,25 @@
+# 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.
+
+"""Provides tools for converting and wrapping MMM schema data.
+
+This package contains modules to transform Marketing Mix Modeling (MMM) protocol
+buffer data into other formats and provides high-level wrappers for easier data
+manipulation, analysis, and reporting.
+"""
+
+from scenarioplanner.converters import dataframe
+from scenarioplanner.converters import mmm
+from scenarioplanner.converters import mmm_converter
+from scenarioplanner.converters import sheets

scenarioplanner/converters/dataframe/__init__.py

@@ -0,0 +1,28 @@
+# 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.
+
+"""Converters for `Mmm` protos to flat dataframes.
+
+This package provides a set of tools for transforming data from `Mmm`
+protos into flat dataframes. This conversion makes the data easier to analyze,
+visualize, and use in other data processing pipelines.
+"""
+
+from scenarioplanner.converters.dataframe import budget_opt_converters
+from scenarioplanner.converters.dataframe import common
+from scenarioplanner.converters.dataframe import constants
+from scenarioplanner.converters.dataframe import converter
+from scenarioplanner.converters.dataframe import dataframe_model_converter
+from scenarioplanner.converters.dataframe import marketing_analyses_converters
+from scenarioplanner.converters.dataframe import rf_opt_converters