PyMC-Marketing

The pymc-marketing MMM API provides several advanced Bayesian modeling capabilities:

• Custom Priors and Likelihoods: Incorporate domain knowledge via prior distributions.
• Adstock Transformation: Optimize carry-over effects in marketing channels.
• Saturation Effects: Model diminishing returns on media investments.
• Custom Functions: Implement your own adstock and saturation functions.
• Time-varying Intercept/Media Contribution: Capture baseline and efficiency changes over time using Gaussian processes.
• Causal Identification: Use directed acyclic graphs (DAGs) to identify meaningful variables.
• Inference Algorithms: Choose between various NUTS samplers like BlackJax, NumPyro, and Nutpie.
• Out-of-sample Predictions: Forecast future performance for scenario planning.
• Budget Optimization: Efficiently allocate spend across channels for maximum ROI.
• Experiment Calibration: Integrate lift tests to fine-tune the model.

The pymc_marketing package is organized into several specialized modules for Bayesian marketing analytics. You can access specific functionalities by importing from these submodules:

• mmm: Marketing Mix Modeling tools.
• clv: Customer Lifetime Value modeling.
• customer_choice: Customer Choice Analysis (CSA).
• bass: Bass diffusion models.
• causal_utils: Utilities for causal inference.
• data: Data handling and processing.
• model_builder: Tools for constructing models.
• model_config: Configuration management for models.
• model_graph: Model graph representations.
• prior & special_priors: Bayesian prior specifications.
• metrics: Evaluation metrics.
• plot: Visualization tools.
• serialization & serialization_migration: Saving and loading models.
• mlflow: Integration with MLflow for experiment tracking.
• utils, pytensor_utils, paths, hsgp_kwargs, pie: Various helper and utility modules.

Deciding whether to use the high-level MMM class or a custom pm.Model depends on your modeling requirements.

Use the MMM class if you need:

• Built-in scaling for channels and targets.
• Automated visualization (e.g., plot.waterfall_components_decomposition(), plot.contributions_over_time()).
• Integration with BudgetOptimizerWrapper.
• Built-in add_lift_test_measurements() and TimeSliceCrossValidator.
• Easy save() and load() functionality.

Use a custom pm.Model if you need:

• Arbitrary hierarchical structures beyond supported dimensions.
• Custom likelihood functions (the MMM class defaults to Normal).
• Custom intercepts like splines or changepoints.
• Sum-to-zero constraints (using pm.ZeroSumNormal).
• Multi-equation or linked models.

Note: If you move to a custom model, you must manually reimplement scaling, contribution decomposition, and optimization.

The MMM class in pymc-marketing is a high-level wrapper that provides scaling, plotting, budget optimization, and serialization. You should only build a custom model using pm.Model and standalone components when the MMM class cannot express your specific requirements.

Common reasons to go custom include:

• Non-standard hierarchical structures: e.g., partial pooling across both geography and product lines simultaneously.
• Custom time-varying baselines: e.g., spline-based intercepts, changepoint models, or non-GP approaches.
• Custom likelihoods: e.g., Student-t, ZeroInflatedPoisson, or mixture likelihoods.
• Missing components: e.g., custom covariate transformations or non-linear interactions not yet in the MMM class.
• Full parameterization control: e.g., manual centering or sum-to-zero constraints on seasonality.
• Multi-equation models: e.g., linking an MMM to a separate demand or pricing model.

Budget bounds constrain per-channel (and optionally per-geo) allocation. Bounds are specified as xr.DataArray objects. You can define single-geo bounds, multidimensional (Channel x Geo) bounds, or use the optimizer_xarray_builder helper.

Single-Geo Bounds Structure:

• Dimensions: ["channel", "bound"]
• Coordinates: channel (list of channel names), bound (["lower", "upper"])

Multidimensional Bounds (Channel x Geo) Structure:

• Dimensions: ["channel", "geo", "bound"]
• Coordinates: channel, geo, bound

import numpy as np
import xarray as xr
from pymc_marketing.mmm.budget_optimizer import optimizer_xarray_builder

# Option 1: Manual Single-Geo Bounds
budget_bounds = xr.DataArray(
    data=np.array([
        [0.5, 1.5],   # tv: 50%-150% of equal share
        [0.3, 2.0],   # radio: 30%-200%
        [0.5, 1.5],   # social
    ]) * equal_share_per_channel,
    dims=["channel", "bound"],
    coords={
        "channel": channel_columns,
        "bound": ["lower", "upper"],
    },
)

# Option 2: Multidimensional Bounds (Channel x Geo)
budget_bounds = xr.DataArray(
    data=np.stack([
        np.full((n_channels, n_geos), 0.0),       # lower bounds
        np.full((n_channels, n_geos), max_budget),  # upper bounds
    ], axis=-1),
    dims=["channel", "geo", "bound"],
    coords={
        "channel": channel_columns,
        "geo": geos,
        "bound": ["lower", "upper"],
    },
)

# Option 3: Using the Builder Helper
budget_bounds = optimizer_xarray_builder(
    value=np.array([
        [0.5 * equal_share, 1.5 * equal_share],   # tv
        [0.3 * equal_share, 2.0 * equal_share],   # radio
        [0.5 * equal_share, 1.5 * equal_share],   # social
    ]),
    channel=channel_columns,
    bound=["lower", "upper"],
)

Custom Constraints

Use pymc_marketing.mmm.constraints.Constraint to implement logic beyond simple bounds (e.g., spend ratios). Pass a list of these to optimize_budget.

Custom Budget Distribution (Flighting)

By default, budget is distributed equally. To implement temporal patterns (flighting), pass a budget_distribution_over_period xr.DataArray to both optimize_budget and sample_response_distribution. Values along the date dimension must sum to 1 for each combination of other dimensions.

Fixing Channels

Pass a boolean xr.DataArray to budgets_to_optimize to decide which channels to optimize and which to keep at a fixed budget.

# Custom Constraint Example: tv must be at least 2x radio
import pytensor.tensor as pt
from pymc_marketing.mmm.constraints import Constraint

def tv_ge_2x_radio(budgets_sym, total_budget_sym, optimizer):
    tv_idx = list(channel_columns).index("tv")
    radio_idx = list(channel_columns).index("radio")
    return budgets_sym[tv_idx] - 2 * budgets_sym[radio_idx]

constraint = Constraint(
    key="tv_ge_2x_radio",
    constraint_type="ineq",
    constraint_fun=tv_ge_2x_radio,
)

# Applying constraints
allocation, result = optimizable_model.optimize_budget(
    budget=budget_per_period,
    budget_bounds=budget_bounds,
    constraints=[constraint],
    minimize_kwargs={"method": "SLSQP"},
)