google-meridian 1.0.8__py3-none-any.whl → 1.1.0__py3-none-any.whl

meridian/analysis/summarizer.py

@@ -75,8 +75,8 @@ class Summarizer:
       self,
       filename: str,
       filepath: str,
-      start_date: tc.Date | None = None,
-      end_date: tc.Date | None = None,
+      start_date: tc.Date = None,
+      end_date: tc.Date = None,
   ):
     """Generates and saves the HTML results summary output.
 
@@ -93,8 +93,8 @@ class Summarizer:
 
   def _gen_model_results_summary(
       self,
-      start_date: tc.Date | None = None,
-      end_date: tc.Date | None = None,
+      start_date: tc.Date = None,
+      end_date: tc.Date = None,
   ) -> str:
     """Generate HTML results summary output (as sanitized content str)."""
     all_dates = self._meridian.input_data.time_coordinates.all_dates
@@ -167,7 +167,9 @@ class Summarizer:
         self._create_model_fit_card_html(
             template_env, selected_times=selected_times
         ),
-        self._create_outcome_contrib_card_html(template_env, media_summary),
+        self._create_outcome_contrib_card_html(
+            template_env, media_summary, selected_times=selected_times
+        ),
         self._create_performance_breakdown_card_html(
             template_env, media_summary
         ),
@@ -267,16 +269,30 @@ class Summarizer:
       self,
       template_env: jinja2.Environment,
       media_summary: visualizer.MediaSummary,
+      selected_times: Sequence[str] | None,
   ) -> str:
     """Creates the HTML snippet for the Outcome Contrib card."""
     outcome = self._kpi_or_revenue()
 
+    num_selected_times = (
+        self._meridian.n_times
+        if selected_times is None
+        else len(selected_times)
+    )
+    time_granularity = (
+        c.WEEKLY
+        if num_selected_times < c.QUARTERLY_SUMMARY_THRESHOLD_WEEKS
+        else c.QUARTERLY
+    )
+
     channel_contrib_area_chart = formatter.ChartSpec(
         id=summary_text.CHANNEL_CONTRIB_BY_TIME_CHART_ID,
         description=summary_text.CHANNEL_CONTRIB_BY_TIME_CHART_DESCRIPTION.format(
             outcome=outcome
         ),
-        chart_json=media_summary.plot_channel_contribution_area_chart().to_json(),
+        chart_json=media_summary.plot_channel_contribution_area_chart(
+            time_granularity=time_granularity
+        ).to_json(),
     )
 
     channel_contrib_bump_chart = formatter.ChartSpec(
@@ -284,7 +300,9 @@ class Summarizer:
         description=summary_text.CHANNEL_CONTRIB_RANK_CHART_DESCRIPTION.format(
             outcome=outcome
         ),
-        chart_json=media_summary.plot_channel_contribution_bump_chart().to_json(),
+        chart_json=media_summary.plot_channel_contribution_bump_chart(
+            time_granularity=time_granularity
+        ).to_json(),
     )
     channel_drivers_chart = formatter.ChartSpec(
         id=summary_text.CHANNEL_DRIVERS_CHART_ID,

meridian/analysis/test_utils.py

@@ -1515,13 +1515,13 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
         [
             1.991e02,
             5.116e02,
-            5.190e01,
+            5.191e01,
             6.623e02,
             1.969e02,
-            -7.194e05,
-            -1.927e04,
-            -1.809e03,
-            -3.006e04,
+            -2.250e05,
+            1.676e04,
+            1.058e04,
+            -4.475e03,
         ],
         [
             1.980e02,
@@ -1529,10 +1529,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             5.190e01,
             6.690e02,
             1.947e02,
-            -7.001e05,
-            -1.915e04,
-            -1.729e03,
-            -2.933e04,
+            -2.190e05,
+            1.669e04,
+            1.005e04,
+            -4.375e03,
         ],
         [
             1.984e02,
@@ -1540,10 +1540,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             5.186e01,
             6.678e02,
             1.950e02,
-            -7.005e05,
-            -1.901e04,
-            -1.737e03,
-            -3.111e04,
+            -2.191e05,
+            1.654e04,
+            1.011e04,
+            -4.644e03,
         ],
         [
             1.984e02,
@@ -1551,10 +1551,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             5.193e01,
             6.658e02,
             1.899e02,
-            -6.618e05,
-            -1.831e04,
-            -1.688e03,
-            -2.833e04,
+            -2.070e05,
+            1.575e04,
+            9.798e03,
+            -4.228e03,
         ],
         [
             1.980e02,
@@ -1562,10 +1562,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             5.196e01,
             6.697e02,
             1.898e02,
-            -6.748e05,
-            -1.849e04,
-            -1.660e03,
-            -3.077e04,
+            -2.111e05,
+            1.595e04,
+            9.621e03,
+            -4.596e03,
         ],
         [
             1.960e02,
@@ -1573,10 +1573,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             5.181e01,
             6.764e02,
             1.999e02,
-            -6.882e05,
-            -1.859e04,
-            -1.622e03,
-            -2.499e04,
+            -2.153e05,
+            1.596e04,
+            9.384e03,
+            -3.718e03,
         ],
         [
             1.988e02,
@@ -1584,10 +1584,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             5.180e01,
             6.780e02,
             1.979e02,
-            -6.667e05,
-            -1.809e04,
-            -1.600e03,
-            -2.555e04,
+            -2.085e05,
+            1.539e04,
+            9.246e03,
+            -3.802e03,
         ],
         [
             1.991e02,
@@ -1595,10 +1595,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             5.174e01,
             6.698e02,
             1.972e02,
-            -5.978e05,
-            -1.809e04,
-            -1.589e03,
-            -2.782e04,
+            -1.870e05,
+            1.525e04,
+            9.182e03,
+            -4.143e03,
         ],
         [
             1.986e02,
@@ -1606,10 +1606,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             5.175e01,
             6.669e02,
             1.948e02,
-            -6.080e05,
-            -1.806e04,
-            -1.619e03,
-            -2.830e04,
+            -1.902e05,
+            1.520e04,
+            9.380e03,
+            -4.212e03,
         ],
         [
             1.986e02,
@@ -1617,10 +1617,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             5.178e01,
             6.670e02,
             1.965e02,
-            -6.241e05,
-            -1.795e04,
-            -1.663e03,
-            -2.348e04,
+            -1.952e05,
+            1.512e04,
+            9.660e03,
+            -3.480e03,
         ],
     ],
     [
@@ -1630,10 +1630,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             2.222e02,
             2.692e02,
             1.240e02,
-            -6.622e05,
-            -3.899e04,
-            3.034e03,
-            -1.467e05,
+            -2.072e05,
+            4.133e04,
+            -2.037e04,
+            -2.202e04,
         ],
         [
             1.432e03,
@@ -1641,10 +1641,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             2.231e02,
             2.683e02,
             1.240e02,
-            -6.727e05,
-            -3.886e04,
-            3.040e03,
-            -1.444e05,
+            -2.105e05,
+            4.117e04,
+            -2.041e04,
+            -2.168e04,
         ],
         [
             1.430e03,
@@ -1652,10 +1652,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             2.248e02,
             2.675e02,
             1.235e02,
-            -6.444e05,
-            -3.858e04,
-            3.023e03,
-            -1.387e05,
+            -2.016e05,
+            4.092e04,
+            -2.030e04,
+            -2.085e04,
         ],
         [
             1.436e03,
@@ -1663,10 +1663,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             2.231e02,
             2.667e02,
             1.244e02,
-            -6.301e05,
-            -3.852e04,
-            3.006e03,
-            -1.275e05,
+            -1.972e05,
+            4.087e04,
+            -2.019e04,
+            -1.921e04,
         ],
         [
             1.447e03,
@@ -1674,10 +1674,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             2.226e02,
             2.650e02,
             1.254e02,
-            -5.698e05,
-            -3.717e04,
-            2.969e03,
-            -1.106e05,
+            -1.783e05,
+            3.951e04,
+            -1.994e04,
+            -1.672e04,
         ],
         [
             1.430e03,
@@ -1685,10 +1685,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             2.232e02,
             2.641e02,
             1.254e02,
-            -5.759e05,
-            -3.911e04,
-            2.974e03,
-            -1.045e05,
+            -1.802e05,
+            4.147e04,
+            -1.998e04,
+            -1.571e04,
         ],
         [
             1.457e03,
@@ -1696,10 +1696,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             2.258e02,
             2.621e02,
             1.247e02,
-            -5.770e05,
-            -3.842e04,
-            3.002e03,
-            -9.320e04,
+            -1.805e05,
+            4.070e04,
+            -2.015e04,
+            -1.398e04,
         ],
         [
             1.456e03,
@@ -1707,10 +1707,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             2.276e02,
             2.646e02,
             1.246e02,
-            -5.637e05,
-            -3.962e04,
-            2.988e03,
-            -8.621e04,
+            -1.764e05,
+            4.198e04,
+            -2.006e04,
+            -1.299e04,
         ],
         [
             1.484e03,
@@ -1718,10 +1718,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             2.252e02,
             2.668e02,
             1.241e02,
-            -5.527e05,
-            -4.099e04,
-            2.969e03,
-            -8.990e04,
+            -1.729e05,
+            4.340e04,
+            -1.995e04,
+            -1.352e04,
         ],
         [
             1.475e03,
@@ -1729,10 +1729,10 @@ INC_OUTCOME_NON_MEDIA_FIXED = np.array([
             2.238e02,
             2.669e02,
             1.244e02,
-            -5.546e05,
-            -4.105e04,
-            2.999e03,
-            -8.896e04,
+            -1.735e05,
+            4.349e04,
+            -2.014e04,
+            -1.338e04,
         ],
     ],
 ])

meridian/analysis/visualizer.py

@@ -465,14 +465,14 @@ class ModelFit:
     else:
       y_axis_label = summary_text.KPI_LABEL
     plot = (
-        alt.Chart(model_fit_df, width=c.VEGALITE_FACET_DEFAULT_WIDTH)
+        alt.Chart(model_fit_df, width=c.VEGALITE_FACET_EXTRA_LARGE_WIDTH)
         .mark_line()
         .encode(
             x=alt.X(
                 f'{c.TIME}:T',
                 title='Time period',
                 axis=alt.Axis(
-                    format='%Y %b',
+                    format=c.QUARTER_FORMAT,
                     grid=False,
                     tickCount=8,
                     domainColor=c.GREY_300,
@@ -1405,7 +1405,7 @@ class MediaSummary:
       confidence_level: float = c.DEFAULT_CONFIDENCE_LEVEL,
       selected_times: Sequence[str] | None = None,
       marginal_roi_by_reach: bool = True,
-      non_media_baseline_values: Sequence[str | float] | None = None,
+      non_media_baseline_values: Sequence[float] | None = None,
   ):
     """Initializes the media summary metrics based on the model data and params.
 
@@ -1420,13 +1420,11 @@ class MediaSummary:
         next dollar spent only impacts reach, holding frequency constant.  If
         this argument is False, we assume the next dollar spent only impacts
         frequency, holding reach constant.
-      non_media_baseline_values: Optional list of shape (n_non_media_channels,).
-        Each element is either a float (which means that the fixed value will be
-        used as baseline for the given channel) or one of the strings "min" or
-        "max" (which mean that the global minimum or maximum value will be used
-        as baseline for the values of the given non_media treatment channel). If
-        None, the minimum value is used as baseline for each non_media treatment
-        channel.
+      non_media_baseline_values: Optional list of shape
+        `(n_non_media_channels,)`. Each element is a float denoting the fixed
+        value which will be used as baseline for the given channel. If `None`,
+        the values defined with `ModelSpec.non_media_baseline_values`
+        will be used.
     """
     self._meridian = meridian
     self._analyzer = analyzer.Analyzer(meridian)
@@ -1629,7 +1627,7 @@ class MediaSummary:
       confidence_level: float | None = None,
       selected_times: Sequence[str] | None = None,
       marginal_roi_by_reach: bool = True,
-      non_media_baseline_values: Sequence[str | float] | None = None,
+      non_media_baseline_values: Sequence[float] | None = None,
   ):
     """Runs the computation for the media summary metrics with new parameters.
 
@@ -1644,31 +1642,47 @@ class MediaSummary:
         dollar spent only impacts reach, holding frequency constant. If `False`,
         the assumption is the next dollar spent only impacts frequency, holding
         reach constant.
-      non_media_baseline_values: Optional list of shape (n_non_media_channels,).
-        Each element is either a float (which means that the fixed value will be
-        used as baseline for the given channel) or one of the strings "min" or
-        "max" (which mean that the global minimum or maximum value will be used
-        as baseline for the values of the given non_media treatment channel). If
-        None, the minimum value is used as baseline for each non_media treatment
-        channel.
+      non_media_baseline_values: Optional list of shape
+        `(n_non_media_channels,)`. Each element is a float denoting the fixed
+        value which will be used as baseline for the given channel. If `None`,
+        the values defined with `ModelSpec.non_media_baseline_values`
+        will be used.
     """
     self._confidence_level = confidence_level or self._confidence_level
     self._selected_times = selected_times
     self._marginal_roi_by_reach = marginal_roi_by_reach
     self._non_media_baseline_values = non_media_baseline_values
 
-  def plot_channel_contribution_area_chart(self) -> alt.Chart:
+  def plot_channel_contribution_area_chart(
+      self, time_granularity: str = c.QUARTERLY
+  ) -> alt.Chart:
     """Plots a stacked area chart of the contribution share per channel by time.
 
+    Args:
+      time_granularity: The granularity for the time axis. Options are `weekly`
+        or `quarterly`. Defaults to `quarterly`.
+
     Returns:
       An Altair plot showing the contribution share per channel by time.
+
+    Raises:
+      ValueError: If time_granularity is not one of the allowed constants.
     """
+    if time_granularity not in c.TIME_GRANULARITIES:
+      raise ValueError(
+          f'time_granularity must be one of {c.TIME_GRANULARITIES}'
+      )
+
+    x_axis_format = (
+        c.DATE_FORMAT if time_granularity == c.WEEKLY else c.QUARTER_FORMAT
+    )
+
     outcome_df = self._transform_contribution_metrics(
         include_non_paid=True, aggregate_times=False
     )
 
     # Ensure proper ordering for the stacked area chart. Baseline should be at
-    # the bottom.  Separate the *stacking* order from the *legend* order.
+    # the bottom. Separate the *stacking* order from the *legend* order.
     stack_order = sorted([
         channel
         for channel in outcome_df[c.CHANNEL].unique()
@@ -1691,7 +1705,7 @@ class MediaSummary:
     )
 
     plot = (
-        alt.Chart(outcome_df, width=c.VEGALITE_FACET_LARGE_WIDTH)
+        alt.Chart(outcome_df, width=c.VEGALITE_FACET_EXTRA_LARGE_WIDTH)
         .mark_area()
         .transform_calculate(
             sort_channel=f'indexof({stack_order}, datum.channel)'
@@ -1701,7 +1715,7 @@ class MediaSummary:
                 f'{c.TIME}:T',
                 title='Time period',
                 axis=alt.Axis(
-                    format='%Y Q%q',
+                    format=x_axis_format,
                     grid=False,
                     tickCount=8,
                     domainColor=c.GREY_300,
@@ -1730,12 +1744,13 @@ class MediaSummary:
                     labelFontSize=c.AXIS_FONT_SIZE,
                     labelFont=c.FONT_ROBOTO,
                     title=None,
+                    orient='bottom',
                 ),
                 scale=alt.Scale(domain=legend_order),
                 sort=legend_order,
             ),
             tooltip=[
-                alt.Tooltip(f'{c.TIME}:T', format='%Y-%m-%d'),
+                alt.Tooltip(f'{c.TIME}:T', format=c.DATE_FORMAT),
                 c.CHANNEL,
                 alt.Tooltip(f'{c.INCREMENTAL_OUTCOME}:Q', format=',.2f'),
             ],
@@ -1751,16 +1766,31 @@ class MediaSummary:
     )
     return plot
 
-  def plot_channel_contribution_bump_chart(self) -> alt.Chart:
-    """Plots a bump chart of channel contribution rank over time (Quarterly).
+  def plot_channel_contribution_bump_chart(
+      self, time_granularity: str = c.QUARTERLY
+  ) -> alt.Chart:
+    """Plots a bump chart of channel contribution rank over time.
 
     This chart shows the relative rank of each channel's contribution,
-    including the baseline, based on incremental outcome at the end of each
+    including the baseline, based on incremental outcome. Depending on the
+    time_granularity, ranks are shown either weekly or at the end of each
     quarter. Rank 1 represents the highest contribution.
 
+    Args:
+      time_granularity: The granularity for the time axis. Options are `weekly`
+        or `quarterly`. Defaults to `quarterly`.
+
     Returns:
-      An Altair plot showing the contribution rank per channel by quarter.
+      An Altair plot showing the contribution rank per channel by time.
+
+    Raises:
+      ValueError: If time_granularity is not one of the allowed constants.
     """
+    if time_granularity not in c.TIME_GRANULARITIES:
+      raise ValueError(
+          f'time_granularity must be one of {c.TIME_GRANULARITIES}'
+      )
+
     outcome_df = self._transform_contribution_metrics(
         include_non_paid=True, aggregate_times=False
     )
@@ -1770,30 +1800,37 @@ class MediaSummary:
         method='first', ascending=False
     )
 
-    # Filter data to keep only the last available date within each quarter
-    # for a quarterly view of ranking changes.
-    unique_times = pd.Series(outcome_df[c.TIME].unique()).sort_values()
-    quarters = unique_times.dt.to_period('Q')
-    quarterly_dates = unique_times[~quarters.duplicated(keep='last')]
-    quarterly_rank_df = outcome_df[
-        outcome_df[c.TIME].isin(quarterly_dates)
-    ].copy()
+    if time_granularity == c.QUARTERLY:
+      # Filter data to keep only the last available date within each quarter
+      # for a quarterly view of ranking changes.
+      unique_times = pd.Series(outcome_df[c.TIME].unique()).sort_values()
+      quarters = unique_times.dt.to_period('Q')
+      quarterly_dates = unique_times[~quarters.duplicated(keep='last')]
+      plot_df = outcome_df[outcome_df[c.TIME].isin(quarterly_dates)].copy()
+      x_axis_format = c.QUARTER_FORMAT
+      tooltip_time_format = c.QUARTER_FORMAT
+      tooltip_time_title = 'Quarter'
+    else:
+      plot_df = outcome_df.copy()
+      x_axis_format = c.DATE_FORMAT
+      tooltip_time_format = c.DATE_FORMAT
+      tooltip_time_title = 'Week'
 
     legend_order = [c.BASELINE] + sorted([
         channel
-        for channel in quarterly_rank_df[c.CHANNEL].unique()
+        for channel in plot_df[c.CHANNEL].unique()
         if channel != c.BASELINE
     ])
 
     plot = (
-        alt.Chart(quarterly_rank_df, width=c.VEGALITE_FACET_DEFAULT_WIDTH)
+        alt.Chart(plot_df, width=c.VEGALITE_FACET_EXTRA_LARGE_WIDTH)
         .mark_line(point=True)
         .encode(
             x=alt.X(
                 f'{c.TIME}:T',
                 title='Time period',
                 axis=alt.Axis(
-                    format='%Y Q%q',
+                    format=x_axis_format,
                     grid=False,
                     domainColor=c.GREY_300,
                 ),
@@ -1819,12 +1856,17 @@ class MediaSummary:
                     labelFontSize=c.AXIS_FONT_SIZE,
                     labelFont=c.FONT_ROBOTO,
                     title=None,
+                    orient='bottom',
                 ),
                 scale=alt.Scale(domain=legend_order),
                 sort=legend_order,
             ),
             tooltip=[
-                alt.Tooltip(f'{c.TIME}:T', format='%Y Q%q', title='Quarter'),
+                alt.Tooltip(
+                    f'{c.TIME}:T',
+                    format=tooltip_time_format,
+                    title=tooltip_time_title,
+                ),
                 alt.Tooltip(f'{c.CHANNEL}:N', title='Channel'),
                 alt.Tooltip('rank:O', title='Rank'),
                 alt.Tooltip(