Physics-Informed Marketing Mix Modeling pimmm

Physics-Informed Marketing Mix Modeling pimmm is a focused Python library that unifies machine‑learning response surfaces with continuous‑time innovation‑diffusion physics to produce physically realistic long‑term adoption forecasts.

By embedding the Generalized Bass Model (GBM) Ordinary Differential Equations directly into empirical response pipelines, pimmm addresses early‑stage non‑identifiability and enforces natural saturation and imitation dynamics. This makes trajectory forecasting more robust when training data is limited to early adoption phases.

---

Purpose and Scope

Important positioning note

pimmm is not a full‑featured MMM platform and is not intended to replace specialized tools such as PyMC‑Marketing, Google Meridian, scikit‑learn, statsmodels, or other tabular foundation model packages. Instead, pimmm is intentionally complementary:

• We add physics. pimmm takes response surfaces produced by industry‑grade packages and enforces continuous‑time diffusion physics on top of them.
• You keep your favorite tooling. Use your preferred ML or Bayesian tool to estimate the spend→effort mapping; use pimmm to convert that mapping into physically consistent adoption trajectories.
• We focus on realism and integration. Our goal is to provide a lightweight, well‑documented bridge that preserves the strengths of existing ecosystems while adding structural, interpretable dynamics.

Native scikit‑learn support
pimmm natively supports any scikit‑learn API compliant model as the base case — no wrapper required. The provided wrappers (Google Meridian, TabFM, PyMC) convert other enterprise or foundation models into scikit‑learn‑compliant response models so they plug into pimmm the same way as native scikit‑learn estimators.

If you need a full MMM suite with every enterprise feature out of the box, use the specialized platform that best fits your workflow and integrate pimmm where physics and long‑term forecasting matter.

---

Key Features

• Physics‑Informed ODE Dynamics
  Enforces continuous‑time innovation (p) and imitation (q) dynamics and natural saturation caps (F(t) \le 1).

• Open Architecture and ML Integration
  Works with standard scikit‑learn estimators out of the box and with Tabular Foundation Models and enterprise MMM platforms via adapter wrappers.

• Google Meridian Wrapper
  Built‑in adapter for Google Meridian to let enterprise MMM outputs be used directly as the empirical response surface inside the physics layer.

• TabFM Wrapper
  Built‑in adapter for Tabular Foundation Models so large pretrained tabular models can supply latent effort trajectories to the ODE solver.

• PyMC Marketing Wrapper
  New: A PyMC‑based response wrapper enables Bayesian response surface estimation and uncertainty propagation through the ODE solver.

• Scikit‑Learn API Compliance
  Designed to follow .fit() and .predict() semantics for easy integration into MLOps pipelines.

• Early‑Stage Robustness
  Specifically designed to bound long‑term adoption when training data is limited to early penetration phases.

---

🚀 Quickstart

import numpy as np
from sklearn.ensemble import GradientBoostingRegressor
from pimmm import PhysicsInformedMMM

# 1. Load your spend inputs (X) and adoption trajectories (y)
X_spend = ... # Marketing spend features
y_adoption = ... # Observed market penetration [0, 1]

# 2. Instantiate PI-MMM with any Scikit-Learn driver
model = PhysicsInformedMMM(
    response_model=GradientBoostingRegressor(),
    dt=0.5
)

# 3. Fit on early-stage adoption data
model.fit(X_spend, y_adoption)

# 4. Forecast continuous adoption S-curves
predictions = model.predict(X_spend_future)

# 5. Extract recovered physical constants
print(model.get_params_summary())
# Output: {'Innovation (p)': 0.012, 'Imitation (q)': 0.341, 'Scale Factor (gamma)': 0.82}

---

📦 Installation

pip install git+https://github.com/lgpintomkt/pimmm.git

📚 Academic Foundations & References

pimmm is developed as part of ongoing PhD research in Mathematics at the University of Évora, Portugal (IIFA / CIMA / DMAT). The core architecture, reduction hierarchy, and effort-time equivalences implemented in this package are formally established across the following works:

Peer-Reviewed Publications

• Pinto, L. G., Cavique, L., Gomes, O., & Santos, J. M. A. (2024). Inhomogeneous Marketing Mix Diffusion. In F. Botta, M. Macedo, H. Barbosa, & R. Menezes (Eds.), Complex Networks XV. CompleNet-Live 2024 (Springer Proceedings in Complexity, pp. 29–41). Springer, Cham. https://doi.org/10.1007/978-3-031-57515-0_3
• Pinto, L. G., Cavique, L., & Santos, J. M. A. (2022). Marketing Mix and New Product Diffusion Models. Procedia Computer Science, 204, 885–890. https://doi.org/10.1016/j.procs.2022.08.107
• Henriques, R., & Pinto, L. (2023). A novel evaluation framework for recommender systems in big data environments. Expert Systems with Applications, 231, 120659. https://doi.org/10.1016/j.eswa.2023.120659