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

meridian/model/eda/eda_outcome.py

@@ -0,0 +1,200 @@
+# 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.
+
+"""Meridian EDA Outcome."""
+
+import dataclasses
+import enum
+import typing
+import pandas as pd
+import xarray as xr
+
+__all__ = [
+    "EDASeverity",
+    "EDAFinding",
+    "AnalysisLevel",
+    "AnalysisArtifact",
+    "PairwiseCorrArtifact",
+    "StandardDeviationArtifact",
+    "VIFArtifact",
+    "KpiInvariabilityArtifact",
+    "EDACheckType",
+    "ArtifactType",
+    "EDAOutcome",
+]
+
+
+@enum.unique
+class EDASeverity(enum.Enum):
+  """Enumeration for the severity of an EDA check's finding."""
+
+  # For the non-critical findings.
+  INFO = enum.auto()
+  # For the non-critical findings that require user attention.
+  ATTENTION = enum.auto()
+  # For unacceptable, model-blocking data errors.
+  ERROR = enum.auto()
+
+
+@dataclasses.dataclass(frozen=True)
+class EDAFinding:
+  """Encapsulates a single, specific finding from an EDA check.
+
+  Attributes:
+      severity: The severity level of the finding.
+      explanation: A human-readable description about the EDA check and a
+        potential actionable guidance on how to address or interpret this
+        specific finding.
+  """
+
+  severity: EDASeverity
+  explanation: str
+
+
+@enum.unique
+class AnalysisLevel(enum.Enum):
+  """Enumeration for the level of an analysis.
+
+  Attributes:
+    OVERALL: Computed across all geos and time. When the analysis is performed
+      on national data, this level is equivalent to the NATIONAL level.
+    NATIONAL: Computed across time for data aggregated to the national level.
+      When the analysis is performed on national data, this level is equivalent
+      to the OVERALL level.
+    GEO: Computed across time, for each geo.
+  """
+
+  OVERALL = enum.auto()
+  NATIONAL = enum.auto()
+  GEO = enum.auto()
+
+
+@dataclasses.dataclass(frozen=True)
+class AnalysisArtifact:
+  """Base dataclass for analysis artifacts.
+
+  Specific EDA artifacts should inherit from this class to store check-specific
+  data for downstream processing (e.g., plotting).
+
+  Attributes:
+    level: The level of the analysis.
+  """
+
+  level: AnalysisLevel
+
+
+@dataclasses.dataclass(frozen=True)
+class PairwiseCorrArtifact(AnalysisArtifact):
+  """Encapsulates artifacts from a single pairwise correlation analysis.
+
+  Attributes:
+    corr_matrix: Pairwise correlation matrix.
+    extreme_corr_var_pairs: DataFrame of variable pairs exceeding the
+      correlation threshold.
+    extreme_corr_threshold: The threshold used to identify extreme correlation
+      pairs.
+  """
+
+  corr_matrix: xr.DataArray
+  extreme_corr_var_pairs: pd.DataFrame
+  extreme_corr_threshold: float
+
+
+@dataclasses.dataclass(frozen=True)
+class StandardDeviationArtifact(AnalysisArtifact):
+  """Encapsulates artifacts from a standard deviation analysis.
+
+  Attributes:
+    variable: The variable for which standard deviation is calculated.
+    std_ds: Dataset with stdev_with_outliers and stdev_without_outliers.
+    outlier_df: DataFrame with outliers.
+  """
+
+  variable: str
+  std_ds: xr.Dataset
+  outlier_df: pd.DataFrame
+
+
+@dataclasses.dataclass(frozen=True)
+class VIFArtifact(AnalysisArtifact):
+  """Encapsulates artifacts from a single VIF analysis.
+
+  Attributes:
+    vif_da: DataArray with VIF values.
+    outlier_df: DataFrame with extreme VIF values.
+  """
+
+  vif_da: xr.DataArray
+  outlier_df: pd.DataFrame
+
+
+@dataclasses.dataclass(frozen=True)
+class KpiInvariabilityArtifact(AnalysisArtifact):
+  """Encapsulates artifacts from a KPI invariability analysis.
+
+  Attributes:
+    kpi_da: DataArray of the KPI that is examined for variability.
+    kpi_stdev: The standard deviation of the KPI, which is used to test the KPI
+      invariability.
+  """
+
+  kpi_da: xr.DataArray
+  kpi_stdev: xr.DataArray
+
+
+@enum.unique
+class EDACheckType(enum.Enum):
+  """Enumeration for the type of an EDA check."""
+
+  PAIRWISE_CORRELATION = enum.auto()
+  STANDARD_DEVIATION = enum.auto()
+  MULTICOLLINEARITY = enum.auto()
+  KPI_INVARIABILITY = enum.auto()
+
+
+ArtifactType = typing.TypeVar("ArtifactType", bound="AnalysisArtifact")
+
+
+@dataclasses.dataclass(frozen=True)
+class EDAOutcome(typing.Generic[ArtifactType]):
+  """A dataclass for the outcomes of a single EDA check function.
+
+  An EDA check function can discover multiple issues. This object groups all of
+  those individual issues, reported as a list of `EDAFinding` objects.
+
+  Attributes:
+    check_type: The type of the EDA check that is being performed.
+    findings: A list of all individual issues discovered by the check.
+    analysis_artifacts: A list of analysis artifacts from the EDA check.
+  """
+
+  check_type: EDACheckType
+  findings: list[EDAFinding]
+  analysis_artifacts: list[ArtifactType]
+
+  @property
+  def get_geo_artifact(self) -> ArtifactType | None:
+    """Returns the geo-level analysis artifact."""
+    for artifact in self.analysis_artifacts:
+      if artifact.level == AnalysisLevel.GEO:
+        return artifact
+    return None
+
+  @property
+  def get_national_artifact(self) -> ArtifactType | None:
+    """Returns the national-level analysis artifact."""
+    for artifact in self.analysis_artifacts:
+      if artifact.level == AnalysisLevel.NATIONAL:
+        return artifact
+    return None

meridian/model/eda/eda_spec.py

@@ -0,0 +1,84 @@
+# 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.
+
+"""Meridian EDA Spec."""
+
+import dataclasses
+from typing import Any, Callable, Dict, TypeAlias
+
+__all__ = [
+    "AggregationConfig",
+    "VIFSpec",
+    "EDASpec",
+]
+
+AggregationFn: TypeAlias = Callable[..., Any]
+AggregationMap: TypeAlias = Dict[str, AggregationFn]
+_DEFAULT_VIF_THRESHOLD = 1000
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class AggregationConfig:
+  """A configuration for customizing variable aggregation functions.
+
+  The aggregation function can be called in the form `f(x, axis=axis, **kwargs)`
+  to return the result of reducing an `np.ndarray` over an integer valued axis.
+  It's recommended to explicitly define the aggregation functions instead of
+  using lambdas.
+
+  Attributes:
+    control_variables: A dictionary mapping control variable names to
+      aggregation functions. Defaults to `np.sum` if a variable is not
+      specified.
+    non_media_treatments: A dictionary mapping non-media variable names to
+      aggregation functions. Defaults to `np.sum` if a variable is not
+      specified.
+  """
+
+  control_variables: AggregationMap = dataclasses.field(default_factory=dict)
+  non_media_treatments: AggregationMap = dataclasses.field(default_factory=dict)
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class VIFSpec:
+  """A spec for the EDA VIF check.
+
+  Attributes:
+    geo_threshold: The threshold for geo-level VIF.
+    overall_threshold: The threshold for overall VIF.
+    national_threshold: The threshold for national VIF.
+  """
+
+  geo_threshold: float = _DEFAULT_VIF_THRESHOLD
+  overall_threshold: float = _DEFAULT_VIF_THRESHOLD
+  national_threshold: float = _DEFAULT_VIF_THRESHOLD
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class EDASpec:
+  """A container for all user-configurable EDA check specs.
+
+  This object allows users to customize the behavior of the EDA checks
+  by passing a single configuration object into the EDAEngine constructor,
+  avoiding a large number of arguments.
+
+  Attributes:
+    aggregation_config: A configuration object for custom aggregation functions.
+    vif_spec: A configuration object for the EDA VIF check.
+  """
+
+  aggregation_config: AggregationConfig = dataclasses.field(
+      default_factory=AggregationConfig
+  )
+  vif_spec: VIFSpec = dataclasses.field(default_factory=VIFSpec)

meridian/model/eda/meridian_eda.py

@@ -0,0 +1,220 @@
+# 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 Meridian related exploratory data analysis (EDA) functionalities."""
+from __future__ import annotations
+
+from typing import Literal, TYPE_CHECKING, Union
+
+import altair as alt
+from meridian import constants
+from meridian.model.eda import constants as eda_constants
+import pandas as pd
+
+if TYPE_CHECKING:
+  from meridian.model import model  # pylint: disable=g-bad-import-order,g-import-not-at-top
+
+__all__ = [
+    'MeridianEDA',
+]
+
+
+class MeridianEDA:
+  """Class for running pre-modeling exploratory data analysis for Meridian InputData."""
+
+  _PAIRWISE_CORR_COLOR_SCALE = alt.Scale(
+      domain=[-1.0, 0.0, 1.0],
+      range=['#1f78b4', '#f7f7f7', '#e34a33'],  # Blue-light grey-Orange
+      type='linear',
+  )
+
+  def __init__(
+      self,
+      meridian: model.Meridian,
+  ):
+    self._meridian = meridian
+
+  def generate_and_save_report(self, filename: str, filepath: str):
+    """Generates and saves the 2 page HTML report containing findings in EDA about given InputData.
+
+    Args:
+      filename: The filename for the generated HTML output.
+      filepath: The path to the directory where the file will be saved.
+    """
+    # TODO: Implement.
+    raise NotImplementedError()
+
+  def plot_pairwise_correlation(
+      self, geos: Union[int, list[str], Literal['nationalize']] = 1
+  ) -> alt.Chart:
+    """Plots the Pairwise Correlation data.
+
+    Args:
+      geos: Defines which geos to plot. - int: The number of top geos to plot,
+        ranked by population. - list[str]: A specific list of geo names to plot.
+        - 'nationalize': Aggregates all geos into a single national view.
+        Defaults to 1 (plotting the top geo). If the data is already at a
+        national level, this parameter is ignored and a national plot is
+        generated.
+
+    Returns:
+      Altair chart(s) of the Pairwise Correlation data.
+    """
+    geos_to_plot = self._validate_and_get_geos_to_plot(geos)
+    is_national = self._meridian.is_national
+    nationalize_geos = geos == 'nationalize'
+
+    if is_national or nationalize_geos:
+      pairwise_corr_artifact = (
+          self._meridian.eda_engine.check_national_pairwise_corr().get_national_artifact
+      )
+      if pairwise_corr_artifact is None:
+        raise ValueError('EDAOutcome does not have national artifact.')
+    else:
+      pairwise_corr_artifact = (
+          self._meridian.eda_engine.check_geo_pairwise_corr().get_geo_artifact
+      )
+      if pairwise_corr_artifact is None:
+        raise ValueError('EDAOutcome does not have geo artifact.')
+    pairwise_corr_data = pairwise_corr_artifact.corr_matrix.to_dataframe()
+
+    charts = []
+    for geo_to_plot in geos_to_plot:
+      title = (
+          'Pairwise correlations among all treatments and controls for'
+          f' {geo_to_plot}'
+      )
+
+      if not (is_national or nationalize_geos):
+        plot_data = (
+            pairwise_corr_data.xs(geo_to_plot, level=constants.GEO)
+            .rename_axis(
+                index=[eda_constants.VARIABLE_1, eda_constants.VARIABLE_2]
+            )
+            .reset_index()
+        )
+      else:
+        plot_data = pairwise_corr_data.rename_axis(
+            index=[eda_constants.VARIABLE_1, eda_constants.VARIABLE_2]
+        ).reset_index()
+      plot_data.columns = [
+          eda_constants.VARIABLE_1,
+          eda_constants.VARIABLE_2,
+          eda_constants.CORRELATION,
+      ]
+      unique_variables = plot_data[eda_constants.VARIABLE_1].unique()
+      variable_to_index = {name: i for i, name in enumerate(unique_variables)}
+
+      plot_data['idx1'] = plot_data[eda_constants.VARIABLE_1].map(
+          variable_to_index
+      )
+      plot_data['idx2'] = plot_data[eda_constants.VARIABLE_2].map(
+          variable_to_index
+      )
+      lower_triangle_data = plot_data[plot_data['idx2'] > plot_data['idx1']]
+
+      charts.append(
+          self._plot_2d_heatmap(lower_triangle_data, title, unique_variables)
+      )
+    final_chart = (
+        alt.vconcat(*charts)
+        .resolve_legend(color='independent')
+        .configure_axis(labelAngle=315)
+        .configure_title(anchor='start')
+        .configure_view(stroke=None)
+    )
+    return final_chart
+
+  def _plot_2d_heatmap(
+      self, data: pd.DataFrame, title: str, unique_variables: list[str]
+  ) -> alt.Chart:
+    """Plots a 2D heatmap."""
+    # Base chart with position encodings
+    base = (
+        alt.Chart(data)
+        .encode(
+            x=alt.X(
+                f'{eda_constants.VARIABLE_1}:N',
+                title=None,
+                sort=unique_variables,
+                scale=alt.Scale(domain=unique_variables),
+            ),
+            y=alt.Y(
+                f'{eda_constants.VARIABLE_2}:N',
+                title=None,
+                sort=unique_variables,
+                scale=alt.Scale(domain=unique_variables),
+            ),
+        )
+        .properties(title=title)
+    )
+
+    # Heatmap layer (rectangles)
+    heatmap = base.mark_rect().encode(
+        color=alt.Color(
+            f'{eda_constants.CORRELATION}:Q',
+            scale=self._PAIRWISE_CORR_COLOR_SCALE,
+            legend=alt.Legend(title=eda_constants.CORRELATION),
+        ),
+        tooltip=[
+            eda_constants.VARIABLE_1,
+            eda_constants.VARIABLE_2,
+            alt.Tooltip(f'{eda_constants.CORRELATION}:Q', format='.3f'),
+        ],
+    )
+
+    # Text annotation layer (values)
+    text = base.mark_text().encode(
+        text=alt.Text(f'{eda_constants.CORRELATION}:Q', format='.3f'),
+        color=alt.value('black'),
+    )
+
+    # Combine layers and apply final configurations
+    chart = (heatmap + text).properties(width=350, height=350)
+
+    return chart
+
+  def _generate_pairwise_correlation_report(self) -> str:
+    """Creates the HTML snippet for Pairwise Correlation report section."""
+    # TODO: Implement.
+    raise NotImplementedError()
+
+  def _validate_and_get_geos_to_plot(
+      self, geos: Union[int, list[str], Literal['nationalize']]
+  ) -> list[str]:
+    """Validates and returns the geos to plot."""
+    ## Validate
+    is_national = self._meridian.is_national
+    if is_national or geos == 'nationalize':
+      geos_to_plot = [constants.NATIONAL_MODEL_DEFAULT_GEO_NAME]
+    elif isinstance(geos, int):
+      if geos > len(self._meridian.input_data.geo) or geos <= 0:
+        raise ValueError(
+            'geos must be a positive integer less than or equal to the number'
+            ' of geos in the data.'
+        )
+      geos_to_plot = self._meridian.input_data.get_n_top_largest_geos(geos)
+    else:
+      geos_to_plot = geos
+
+    if (
+        not is_national and geos != 'nationalize'
+    ):  # if national then geos_to_plot will be ignored
+      for geo in geos_to_plot:
+        if geo not in self._meridian.input_data.geo:
+          raise ValueError(f'Geo {geo} does not exist in the data.')
+      if len(geos_to_plot) != len(set(geos_to_plot)):
+        raise ValueError('geos must not contain duplicate values.')
+
+    return geos_to_plot

meridian/model/knots.py

@@ -250,12 +250,28 @@ class AKS:
   def __init__(self, data: input_data.InputData):
     self._data = data
 
-  def automatic_knot_selection(self) -> AKSResult:
+  def automatic_knot_selection(
+      self,
+      base_penalty: np.ndarray | None = None,
+      min_internal_knots: int = 1,
+      max_internal_knots: int | None = None,
+  ) -> AKSResult:
     """Calculates the optimal number of knots for Meridian model using Automatic knot selection with A-spline.
 
+    Args:
+      base_penalty: A vector of positive penalty values. The adaptive spline
+        regression is performed for every value of penalty.
+      min_internal_knots: The minimum number of internal knots. Defaults to 1.
+      max_internal_knots: The maximum number of internal knots. If None, this
+        value is calculated as the number of initial knots minus the total count
+        of all treatment and control variables. Otherwise, the user-provided
+        value will be used.
+
     Returns:
       Selected knots and the corresponding B-spline model.
     """
+    if base_penalty is None:
+      base_penalty = self._BASE_PENALTY
     n_times = len(self._data.time)
     n_geos = len(self._data.geo)
 
@@ -265,11 +281,12 @@ class AKS:
         np.repeat([range(n_times)], n_geos, axis=0), (n_geos * n_times,)
     )
 
-    knots, min_internal_knots, max_internal_knots = (
-        self._calculate_initial_knots(x)
+    knots = self._calculate_initial_knots(x)
+    max_internal_knots = self._calculate_and_validate_max_internal_knots(
+        knots, min_internal_knots, max_internal_knots
     )
     geo_scaling_factor = 1 / np.sqrt(len(self._data.geo))
-    penalty = geo_scaling_factor * self._BASE_PENALTY
+    penalty = geo_scaling_factor * base_penalty
 
     aspline = self.aspline(x=x, y=y, knots=knots, penalty=penalty)
     n_knots = np.array([len(x) for x in aspline[constants.KNOTS_SELECTED]])
@@ -288,7 +305,7 @@ class AKS:
   def _calculate_initial_knots(
       self,
       x: np.ndarray,
-  ) -> tuple[np.ndarray, int, int]:
+  ) -> np.ndarray:
     """Calculates initial knots based on unique x values.
 
     Args:
@@ -298,38 +315,7 @@ class AKS:
     Returns:
       A tuple containing:
         - The calculated knots.
-        - The minimum number of internal knots.
-        - The maximum number of internal knots.
     """
-    n_media = (
-        len(self._data.media_channel)
-        if self._data.media_channel is not None
-        else 0
-    )
-    n_rf = (
-        len(self._data.rf_channel) if self._data.rf_channel is not None else 0
-    )
-    n_organic_media = (
-        len(self._data.organic_media_channel)
-        if self._data.organic_media_channel is not None
-        else 0
-    )
-    n_organic_rf = (
-        len(self._data.organic_rf_channel)
-        if self._data.organic_rf_channel is not None
-        else 0
-    )
-    n_non_media = (
-        len(self._data.non_media_channel)
-        if self._data.non_media_channel is not None
-        else 0
-    )
-    n_controls = (
-        len(self._data.control_variable)
-        if self._data.control_variable is not None
-        else 0
-    )
-
     x_vals_unique = np.unique(x)
     min_x_data, max_x_data = x_vals_unique.min(), x_vals_unique.max()
     knots = x_vals_unique[
@@ -340,18 +326,39 @@ class AKS:
     # fewer degree of freedom than the total number of knots to function.
     # Dropping the final knot is a natural and practical choice because it
     # often has minimal impact on the overall model fit.
-    knots = knots[:-1]
-    min_internal_knots = 1
-
-    max_internal_knots = (
-        len(knots)
-        - n_media
-        - n_rf
-        - n_organic_media
-        - n_organic_rf
-        - n_non_media
-        - n_controls
+    return knots[:-1]
+
+  def _calculate_and_validate_max_internal_knots(
+      self,
+      knots: np.ndarray,
+      min_internal_knots: int = 1,
+      max_internal_knots: int | None = None,
+  ) -> int:
+    """Calculates the max internal knots, and validates the range.
+
+    Args:
+      knots: Initial knots to calculate max internal knots from.
+      min_internal_knots: The minimum number of internal knots.
+      max_internal_knots: The maximum number of internal knots. If None, this
+        value will be calculated, otherwise will use user provided value.
+
+    Returns:
+      The maximum number of internal knots.
+    """
+    n_features = sum(
+        len(feature) if feature is not None else 0
+        for feature in [
+            self._data.media_channel,
+            self._data.rf_channel,
+            self._data.organic_media_channel,
+            self._data.organic_rf_channel,
+            self._data.non_media_channel,
+            self._data.control_variable,
+        ]
     )
+
+    if max_internal_knots is None:
+      max_internal_knots = len(knots) - n_features
     if min_internal_knots > len(knots):
       raise ValueError(
           'The minimum number of internal knots cannot be greater than the'
@@ -362,8 +369,7 @@ class AKS:
           'The maximum number of internal knots cannot be less than the minimum'
           ' number of internal knots.'
       )
-
-    return knots, min_internal_knots, max_internal_knots
+    return max_internal_knots
 
   def aspline(
       self,

meridian/model/media.py

@@ -63,8 +63,8 @@ class MediaTensors:
     media_spend: A tensor constructed from `InputData.media_spend`.
     media_transformer: A `MediaTransformer` to scale media tensors using the
       model's media data.
-    media_scaled: The media tensor normalized by population and by the median
-      value.
+    media_scaled: The media tensor after pre-modeling transformations including
+      population scaling and scaling by the median non-zero value.
     prior_media_scaled_counterfactual: A tensor containing `media_scaled` values
       corresponding to the counterfactual scenario required for the prior
       calculation. For ROI priors, the counterfactual scenario is where media is
@@ -169,8 +169,9 @@ class OrganicMediaTensors:
     organic_media: A tensor constructed from `InputData.organic_media`.
     organic_media_transformer: A `MediaTransformer` to scale media tensors using
       the model's organic media data.
-    organic_media_scaled: The organic media tensor normalized by population and
-      by the median value.
+    organic_media_scaled: The organic media tensor after pre-modeling
+      transformations including population scaling and scaling by the media
+      non-zero value.
   """
 
   organic_media: backend.Tensor | None = None
@@ -214,8 +215,8 @@ class RfTensors:
     rf_spend: A tensor constructed from `InputData.rf_spend`.
     reach_transformer: A `MediaTransformer` to scale RF tensors using the
       model's RF data.
-    reach_scaled: A reach tensor normalized by population and by the median
-      value.
+    reach_scaled: A reach tensor after pre-modeling transformations including
+      population scaling and scaling by the median non-zero value.
     prior_reach_scaled_counterfactual: A tensor containing `reach_scaled` values
       corresponding to the counterfactual scenario required for the prior
       calculation. For ROI priors, the counterfactual scenario is where reach is
@@ -324,8 +325,9 @@ class OrganicRfTensors:
     organic_frequency: A tensor constructed from `InputData.organic_frequency`.
     organic_reach_transformer: A `MediaTransformer` to scale organic RF tensors
       using the model's organic RF data.
-    organic_reach_scaled: An organic reach tensor normalized by population and
-      by the median value.
+    organic_reach_scaled: An organic reach tensor after pre-modeling
+      transformations including population scaling and scaling by the median
+      non-zero value.
   """
 
   organic_reach: backend.Tensor | None = None