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

schema/model_consumer.py

@@ -0,0 +1,133 @@
+# 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.
+
+"""Consumes a trained Meridian model and produces an `Mmm` proto.
+
+The `Mmm` proto contains parts collected from the core model as well as
+analysis results from trained model processors.
+"""
+
+from collections.abc import Mapping, Sequence
+import functools
+import inspect
+from typing import Any, Generic, TypeAlias, TypeVar
+
+from meridian.model import model
+from mmm.v1 import mmm_pb2 as mmm_pb
+from schema.processors import model_kernel_processor
+from schema.processors import model_processor
+
+
+__all__ = [
+    "ModelConsumer",
+]
+
+
+SpecType: TypeAlias = type[model_processor.Spec]
+ProcType = TypeVar("ProcType", bound=type[model_processor.ModelProcessor])
+
+
+class ModelConsumer(Generic[ProcType]):
+  """Consumes a trained Meridian model and produces an `Mmm` proto.
+
+  Attributes:
+    model_processors: A preset list of model processor types.
+  """
+
+  def __init__(
+      self,
+      model_processors_classes: Sequence[ProcType],
+  ):
+    self._model_processors_classes = model_processors_classes
+
+  @functools.cached_property
+  def specs_to_processors_classes(
+      self,
+  ) -> dict[SpecType, ProcType]:
+    """Returns a mapping of spec types to their corresponding processor types.
+
+    Raises:
+      ValueError: If multiple model processors are found for the same spec type.
+    """
+    specs_to_processors_classes = {}
+    for processor_class in self._model_processors_classes:
+      if (
+          specs_to_processors_classes.get(processor_class.spec_type())
+          is not None
+      ):
+        raise ValueError(
+            "Multiple model processors found for spec type:"
+            f" {processor_class.spec_type()}"
+        )
+      specs_to_processors_classes[processor_class.spec_type()] = processor_class
+    return specs_to_processors_classes
+
+  def __call__(
+      self,
+      mmm: model.Meridian,
+      specs: Sequence[model_processor.Spec],
+      model_id: str = "",
+  ) -> mmm_pb.Mmm:
+    """Produces an `Mmm` schema for the model along with its analyses results.
+
+    Args:
+      mmm: A trained Meridian model. A trained model has its posterior
+        distributions already sampled.
+      specs: A sequence of specs that specify the analyses to run on the model.
+        Specs of the same type will be grouped together and executed together by
+        the corresponding model processor.
+      model_id: An optional model identifier.
+
+    Returns:
+      A proto containing the model kernel at rest and its analysis results.
+    """
+
+    # Group specs by their type.
+    specs_by_type = {}
+    for spec in specs:
+      specs_by_type.setdefault(spec.__class__, []).append(spec)
+
+    tmodel = model_processor.TrainedModel(mmm)
+    processor_params = {
+        "trained_model": tmodel,
+    }
+
+    output = mmm_pb.Mmm()
+    # Attach the model kernel to the Mmm proto.
+    model_kernel_processor.ModelKernelProcessor(mmm, model_id)(output)
+
+    # Perform analysis or optimization.
+    for spec_type, specs in specs_by_type.items():
+      processor_type = self.specs_to_processors_classes[spec_type]
+      processor = _create_processor(processor_type, processor_params)
+      # Attach the output of the processor to the output proto.
+      processor(specs, output)
+
+    return output
+
+
+def _create_processor(
+    processor_type: ProcType,
+    processor_params: Mapping[str, Any],
+) -> model_processor.ModelProcessor:
+  """Creates a processor of the given type with a subset of the given params."""
+  # Clone the given parameters dict first.
+  params = dict(processor_params)
+  # Remove any parameters that are not in the processor's constructor signature.
+  sig = inspect.signature(processor_type.__init__)
+  if not any(p.kind == p.VAR_KEYWORD for p in sig.parameters.values()):
+    for missing in params.keys() - sig.parameters.keys():
+      del params[missing]
+  # Finally, construct the concrete processor.
+  return processor_type(**params)

schema/processors/__init__.py

@@ -0,0 +1,77 @@
+# 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 Model Processor Library.
+
+This package provides a collection of processors designed to operate on trained
+Meridian models. These processors facilitate various post-training tasks,
+including model analysis, insight generation, and budget optimization.
+
+The processors are built upon a common framework defined in the
+`model_processor` module, which establishes the base classes and interfaces for
+builtin processors in this package, as well as for creating custom processors.
+Each processor typically takes a trained Meridian model object and additional
+specifications as input, producing structured output, in protobuf format.
+
+These structured outputs can then be used to generate insights, visualizations,
+and other artifacts that help users understand and optimize their marketing
+strategy. For instance, the `schema.converters` package provides tools to
+flatten these outputs into tabular Google Sheets tables suitable for a Meridian
+Looker Studio dashboard's data sources.
+
+Available Processor Modules:
+
+-   `model_processor`: Defines the abstract base classes `ModelProcessor` and
+    `ModelProcessorSpec`, which serve as the foundation for all processors
+    in this package.
+-   `model_kernel_processor`: A processor to extract and serialize the core
+    components and parameters of the trained Meridian model.
+-   `model_fit_processor`: Generates various goodness-of-fit statistics and
+    diagnostic metrics for the trained model.
+-   `marketing_processor`: Performs marketing mix analysis, including
+    contribution analysis, response curves, and ROI calculations.
+-   `budget_optimization_processor`: Provides tools for optimizing marketing
+    budgets based on the model's predictions to achieve specific goals.
+-   `reach_frequency_processor`: Analyzes and optimizes based on reach and
+    frequency metrics, if applicable to the model structure.
+
+Each processor defines its own spec language. For instance, the budget
+optimization processor would take a `BudgetOptimizationSpec` object as input,
+which defines the constraints and parameters of the optimization problem a
+user wants to explore.
+
+A trained Meridian model is generally a requisite input for all processors.
+Generally, a `model_processor.TrainedModel` wrapper object is passed to each
+processor, along with its processor-specific spec. For example:
+
+```python
+# Assuming 'trained_model' is a loaded Meridian model object
+processor = model_fit_processor.ModelFitProcessor(trained_model)
+result = processor([model_fit_processor.ModelFitSpec()])
+
+# `result` is a structured `ModelFit` proto that describes the model's goodness
+# of fit analysis.
+```
+
+For more details on these processors' sub-API, please refer to the documentation
+of the individual modules.
+"""
+
+from schema.processors import budget_optimization_processor
+from schema.processors import common
+from schema.processors import marketing_processor
+from schema.processors import model_fit_processor
+from schema.processors import model_kernel_processor
+from schema.processors import model_processor
+from schema.processors import reach_frequency_optimization_processor