Replace scan in BetaGeoBetaBinom

.github/workflows/ci.yml

@@ -7,14 +7,21 @@ on:
     branches: [main]
 
 env:
-  OLDEST_PYMC_VERSION: "5.10.4"
+  # The lower bound from the pyproject.toml file
+  OLDEST_PYMC_VERSION: "$(grep -E 'pymc *>' pyproject.toml | sed -n 's/.*>=\\([0-9]*\\.[0-9]*\\.[0-9]*\\).*/\\1/p')"
 
 jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v3
+    - uses: pre-commit/[email protected]
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        config: [ {python-version: "3.9", oldest-pymc: false}, {python-version: "3.11", oldest-pymc: true}]
+        config: [ {python-version: "3.10", oldest-pymc: false}, {python-version: "3.12", oldest-pymc: true}]
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python
@@ -57,6 +64,23 @@ jobs:
           name: "test_slow"
           fail_ci_if_error: false
 
+  example_notebooks:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.12"
+    - name: Install dependencies
+      run: |
+        sudo apt-get install graphviz
+        pip install -e .[docs]
+        pip install -e .[test]
+    - name: Run notebooks
+      run: make run_notebooks
+
+
   all:
     if: ${{ always() }}
     runs-on: ubuntu-latest

.github/workflows/pypi.yml

@@ -17,7 +17,7 @@ jobs:
           fetch-depth: 0
       - uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: "3.10"
       - name: Build the sdist and the wheel
         run: |
           pip install build
@@ -27,7 +27,7 @@ jobs:
           mkdir -p test-sdist
           cd test-sdist
           python -m venv venv-sdist
-          venv-sdist/bin/python -m pip install ../dist/pymc-marketing*.tar.gz
+          venv-sdist/bin/python -m pip install ../dist/pymc_marketing*.tar.gz
           echo "Checking import and version number (on release)"
           venv-sdist/bin/python -c "import pymc_marketing as pmm; assert pmm.__version__ == '${{  github.ref_name }}' if '${{ github.ref_type }}' == 'tag' else pmm.__version__; print(pmm.__version__)"
           cd ..
@@ -62,7 +62,7 @@ jobs:
           repository-url: https://test.pypi.org/legacy/
       - uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: "3.10"
       - name: Test pip install from test.pypi
         run: |
           python -m venv venv-test-pypi

.pre-commit-config.yaml

@@ -2,32 +2,37 @@ ci:
   autofix_prs: false
 
 repos:
+  - repo: https://github.com/lucianopaz/head_of_apache
+    rev: "0.0.3"
+    hooks:
+      - id: head_of_apache
+        args:
+          - --author=The PyMC Labs Developers
+          - --exclude=docs/
+          - --exclude=scripts/
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.3.4
+    rev: v0.5.0
     hooks:
       - id: ruff
+        types_or: [ python, pyi, jupyter ]
         args: ["--fix", "--output-format=full"]
+        exclude: ^docs/source/notebooks/clv/dev/
       - id: ruff-format
+        types_or: [ python, pyi, jupyter ]
+        exclude: ^docs/source/notebooks/clv/dev/
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.9.0
+    rev: v1.10.1
     hooks:
       - id: mypy
         args: [--ignore-missing-imports]
         files: ^pymc_marketing/
         additional_dependencies: [numpy>=1.20, pandas-stubs]
-  - repo: https://github.com/nbQA-dev/nbQA
-    rev: 1.8.5
-    hooks:
-    - id: nbqa-ruff
-      args: ["--fix", "--output-format=full"]
-      files: ^docs/source/notebooks/
-      exclude: ^docs/source/notebooks/clv/dev/
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
       - id: debug-statements
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
       - id: check-added-large-files
-        exclude: ^notebooks/
+        exclude: ^docs/source/notebooks/

CONTRIBUTING.md

@@ -169,4 +169,4 @@ Classes
 
 ---
 
-This guide takes some inspiration from the [Bambi guide to contributing](https://github.com/bambinos/bambi/blob/main/docs/CONTRIBUTING.md)
+This guide takes some inspiration from the [Bambi guide to contributing](https://github.com/bambinos/bambi/blob/main/CONTRIBUTING.md)

Makefile

@@ -1,4 +1,4 @@
-.PHONY: init lint check_lint test html cleandocs
+.PHONY: init lint check_lint test html cleandocs run_notebooks
 
 init:
 	python3 -m pip install -e .
@@ -23,3 +23,6 @@ html:
 
 cleandocs:
 	rm -r "docs/build" "docs/jupyter_execute" "docs/source/api/generated"
+
+run_notebooks:
+	python scripts/run_notebooks/runner.py

README.md

@@ -1,25 +1,42 @@
 <div align="center">
 
-![PyMC-Marketing Logo](docs/source/_static/marketing-logo-light.jpg)
+![PyMC-Marketing Logo](https://github.com/pymc-labs/pymc-marketing/blob/main/docs/source/_static/marketing-logo-light.jpg)
 
 </div>
 
 ----
 
-![Build](https://github.com/pymc-labs/pymc-marketing/workflows/ci/badge.svg)
+![Build](https://github.com/pymc-labs/pymc-marketing/actions/workflows/ci.yml/badge.svg)
 [![codecov](https://codecov.io/gh/pymc-labs/pymc-marketing/branch/main/graph/badge.svg?token=OBV3BS5TYE)](https://codecov.io/gh/pymc-labs/pymc-marketing)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![docs](https://readthedocs.org/projects/pymc-marketing/badge/?version=latest)](https://docs.readthedocs.io/en/latest/)
 [![PyPI Version](https://img.shields.io/pypi/v/pymc-marketing.svg)](https://pypi.python.org/pypi/pymc-marketing)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/pymc-marketing.svg)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
 # <span style="color:limegreen">PyMC-Marketing</span>: Bayesian Marketing Mix Modeling (MMM) & Customer Lifetime Value (CLV)
 
 ## Marketing Analytics Tools from [PyMC Labs](https://www.pymc-labs.com)
 
-
 Unlock the power of **Marketing Mix Modeling (MMM)** and **Customer Lifetime Value (CLV)** analytics with PyMC-Marketing. This open-source marketing analytics tool empowers businesses to make smarter, data-driven decisions for maximizing ROI in marketing campaigns.
 
+----
+
+This repository is supported by [PyMC Labs](https://www.pymc-labs.com).
+
+<center>
+    <img src="https://github.com/pymc-labs/pymc-marketing/blob/main/docs/source/_static/labs-logo-light.png" width="50%" />
+</center>
+
+For businesses looking to integrate PyMC-Marketing into their operational framework, [PyMC Labs](https://www.pymc-labs.com) offers expert consulting and training. Our team is proficient in state-of-the-art Bayesian modeling techniques, with a focus on Marketing Mix Models (MMMs) and Customer Lifetime Value (CLV). For more information see [here](#-schedule-a-free-consultation-for-mmm--clv-strategy).
+
+Explore these topics further by watching our video on [Bayesian Marketing Mix Models: State of the Art](https://www.youtube.com/watch?v=xVx91prC81g).
+
+### Community Resources
+
+- [Bayesian discord server](https://discord.gg/swztKRaVKe)
+- [PyMC discourse](https://discourse.pymc.io/)
+
 ## Quick Installation Guide for Marketing Mix Modeling (MMM) & CLV
 
 To dive into MMM and CLV analytics, set up a specialized environment, `marketing_env`, via conda-forge:
@@ -37,22 +54,73 @@ We provide a `Dockerfile` to build a Docker image for PyMC-Marketing so that is
 
 ## In-depth Bayesian Marketing Mix Modeling (MMM) in PyMC
 
-Leverage our Bayesian MMM API to tailor your marketing strategies effectively. Based on the research [Jin, Yuxue, et al. “Bayesian methods for media mix modeling with carryover and shape effects.” (2017)](https://research.google/pubs/pub46001/),  and integrating the expertise from core PyMC developers, our API provides:
+Leverage our Bayesian MMM API to tailor your marketing strategies effectively. Leveraging on top of the research article [Jin, Yuxue, et al. “Bayesian methods for media mix modeling with carryover and shape effects.” (2017)](https://research.google/pubs/pub46001/),  and extending it by integrating the expertise from core PyMC developers, our API provides:
 
+- **Custom Priors and Likelihoods**: Tailor your model to your specific business needs by including domain knowledge via prior distributions.
 - **Adstock Transformation**: Optimize the carry-over effects in your marketing channels.
 - **Saturation Effects**: Understand the diminishing returns in media investments.
+- **Customize adstock and saturation functions:** You can select from a variety of adstock and saturation functions. You can even implement your own custom functions.
+- **Time-varying Intercept:** Capture time-varying baseline contributions in your model (using modern and efficient Gaussian processes approximation methods).
+- **Time-varying Media Contribution:** Capture time-varying media efficiency in your model (using modern and efficient Gaussian processes approximation methods).
+- **Visualization and Model Diagnostics**: Get a comprehensive view of your model's performance and insights.
+- **Choose among many inference algorithms**: We provide the option to choose between various NUTS samplers (e.g. BlackJax, NumPyro and Nutpie). See the [example notebook](https://www.pymc-marketing.io/en/stable/notebooks/general/other_nuts_samplers.html) for more details.
+- **Out-of-sample Predictions**: Forecast future marketing performance with credible intervals. Use this for simulations and scenario planning.
 - **Budget Optimization**: Allocate your marketing spend efficiently across various channels for maximum ROI.
-- **Experiment Calibration**: Fine-tune your model based on empirical experiments for more unified view of marketing.
+- **Experiment Calibration**: Fine-tune your model based on empirical experiments for a more unified view of marketing.
+
+### MMM Quickstart
+
+```python
+import pandas as pd
+from pymc_marketing.mmm import MMM
+
+data_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/mmm_example.csv"
+data = pd.read_csv(data_url, parse_dates=["date_week"])
+
+mmm = MMM(
+    adstock="geometric",
+    saturation="logistic",
+    date_column="date_week",
+    channel_columns=["x1", "x2"],
+    control_columns=[
+        "event_1",
+        "event_2",
+        "t",
+    ],
+    adstock_max_lag=8,
+    yearly_seasonality=2,
+)
+```
+
+Initiate fitting and get a visualization of some of the outputs with:
+
+```python
+X = data.drop("y",axis=1)
+y = data["y"]
+mmm.fit(X,y)
+mmm.plot_components_contributions();
+```
+
+![](https://github.com/pymc-labs/pymc-marketing/blob/main/docs/source/_static/mmm_plot_components_contributions.png)
+
+Once the model is fitted, we can further optimize our budget allocation as we are including diminishing returns and carry-over effects in our model.
+
+<center>
+    <img src="/docs/source/_static/mmm_plot_plot_channel_contributions_grid.png" width="80%" />
+</center>
 
 Explore a hands-on [simulated example](https://pymc-marketing.readthedocs.io/en/stable/notebooks/mmm/mmm_example.html) for more insights into MMM with PyMC-Marketing.
 
-### Essential Reading for Marketing Mix Modeling (MMM):
+${\color{red}\textbf{Warning!}}$ We will deprecate the `DelayedSaturatedMMM` class in the next releases.
+Please use the `MMM` class instead.
+
+### Essential Reading for Marketing Mix Modeling (MMM)
 
 - [Bayesian Media Mix Modeling for Marketing Optimization](https://www.pymc-labs.com/blog-posts/bayesian-media-mix-modeling-for-marketing-optimization/)
 - [Improving the Speed and Accuracy of Bayesian Marketing Mix Models](https://www.pymc-labs.com/blog-posts/reducing-customer-acquisition-costs-how-we-helped-optimizing-hellofreshs-marketing-budget/)
 - [Johns, Michael and Wang,  Zhenyu. "A Bayesian Approach to Media Mix Modeling"](https://www.youtube.com/watch?v=UznM_-_760Y)
 - [Orduz, Juan. "Media Effect Estimation with PyMC: Adstock, Saturation & Diminishing Returns"](https://juanitorduz.github.io/pymc_mmm/)
-- [A Comprehensive Guide to Bayesian Marketing Mix Modeling](https://1749.io/resource-center/f/a-comprehensive-guide-to-bayesian-marketing-mix-modeling)
+- [A Comprehensive Guide to Bayesian Marketing Mix Modeling](https://1749.io/learn/f/a-comprehensive-guide-to-bayesian-marketing-mix-modeling)
 
 ## Unlock Customer Lifetime Value (CLV) with PyMC
 
@@ -62,40 +130,63 @@ Explore our detailed CLV examples using data from the [`lifetimes`](https://gith
 
 - [CLV Quickstart](https://pymc-marketing.readthedocs.io/en/stable/notebooks/clv/clv_quickstart.html)
 - [BG/NBD model](https://pymc-marketing.readthedocs.io/en/stable/notebooks/clv/bg_nbd.html)
+- [Pareto/NBD model](https://pymc-marketing.readthedocs.io/en/stable/notebooks/clv/pareto_nbd.html)
 - [Gamma-Gamma model](https://pymc-marketing.readthedocs.io/en/stable/notebooks/clv/gamma_gamma.html)
 
 ### Examples
 
-|                | **Non-contractual** | **Contractual**                 |
-|----------------|---------------------|---------------------------------|
-| **Continuous** | Buying groceries    | Audible                         |
-| **Discrete**   | Cinema ticket       | Monthly or yearly subscriptions |
+|                | **Non-contractual** | **Contractual**                |
+|----------------|---------------------|--------------------------------|
+| **Continuous** | online purchases    | ad conversion time             |
+| **Discrete**   | concerts & sports events   | recurring subscriptions |
+
+### CLV Quickstart
+
+```python
+import matplotlib.pyplot as plt
+import pandas as pd
+import seaborn as sns
+from pymc_marketing import clv
+
+data_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/clv_quickstart.csv"
+data = pd.read_csv(data_url)
+data["customer_id"] = data.index
+
+beta_geo_model = clv.BetaGeoModel(data=data)
+
+beta_geo_model.fit()
+```
+
+Once fitted, we can use the model to predict the number of future purchases for known customers, the probability that they are still alive, and get various visualizations plotted.
 
----
+![](https://github.com/pymc-labs/pymc-marketing/blob/main/docs/source/_static/expected_purchases.png)
+
+See the Examples section for more on this.
 
 ## Why PyMC-Marketing vs other solutions?
 
 PyMC-Marketing is and will always be free for commercial use, licensed under [Apache 2.0](LICENSE). Developed by core developers behind the popular PyMC package and marketing experts, it provides state-of-the-art measurements and analytics for marketing teams.
 
-Due to its open source nature and active contributor base, new features get added constantly. Missing a feature or want to contribute? Fork our repository and submit a pull request. For any questions, feel free to [open an issue](https://github.com/your-repo/issues).
+Due to its open-source nature and active contributor base, new features are constantly added. Are you missing a feature or want to contribute? Fork our repository and submit a pull request. If you have any questions, feel free to [open an issue](https://github.com/your-repo/issues).
+
+### Thanks to our contributors!
+
+[![https://github.com/pymc-devs/pymc/graphs/contributors](https://contrib.rocks/image?repo=pymc-labs/pymc-marketing)](https://github.com/pymc-labs/pymc-marketing/graphs/contributors)
+
 
 ## Marketing AI Assistant: MMM-GPT with PyMC-Marketing
 
 Not sure how to start or have questions? MMM-GPT is an AI that answers questions and provides expert advice on marketing analytics using PyMC-Marketing.
 
 **[Try MMM-GPT here.](https://mmm-gpt.com/)**
 
-
-
 ## 📞 Schedule a Free Consultation for MMM & CLV Strategy
 
 Maximize your marketing ROI with a [free 30-minute strategy session](https://calendly.com/niall-oulton) with our PyMC-Marketing experts. Learn how Bayesian Marketing Mix Modeling and Customer Lifetime Value analytics can boost your organization by making smarter, data-driven decisions.
 
-For businesses looking to integrate PyMC-Marketing into their operational framework, [PyMC Labs](https://www.pymc-labs.com) offers expert consulting and training. Our team is proficient in state-of-the-art Bayesian modeling techniques, with a focus on Marketing Mix Models (MMMs) and Customer Lifetime Value (CLV). Explore these topics further by watching our video on [Bayesian Marketing Mix Models: State of the Art](https://www.youtube.com/watch?v=xVx91prC81g).
-
 We provide the following professional services:
 
-- **Custom Models**: We tailor niche marketing anayltics models to fit your organization's unique needs.
-- **Build Within PyMC-Marketing**: Our team are experts leveraging the capabilities of PyMC-Marketing to create robust marketing models for precise insights.
+- **Custom Models**: We tailor niche marketing analytics models to fit your organization's unique needs.
+- **Build Within PyMC-Marketing**: Our team members are experts leveraging the capabilities of PyMC-Marketing to create robust marketing models for precise insights.
 - **SLA & Coaching**: Get guaranteed support levels and personalized coaching to ensure your team is well-equipped and confident in using our tools and approaches.
 - **SaaS Solutions**: Harness the power of our state-of-the-art software solutions to streamline your data-driven marketing initiatives.