Merge branch 'main' into advi-basic-functionality

.github/pull_request_template.md

@@ -15,24 +15,8 @@
 ## Checklist
 <!--- Make sure you have completed the following steps before submitting your PR -->
 <!--- Feel free to type an `x` in all the boxes below to let us know you have completed the steps: -->
-- [ ] Checked that [the pre-commit linting/style checks pass](https://docs.pymc.io/en/latest/contributing/python_style.html)
+- [ ] Checked that [the pre-commit linting/style checks pass](https://www.pymc-marketing.io/en/latest/contributing/index.html). Feel free to comment [`pre-commit.ci autofix` to auto-fix](https://pre-commit.ci/#configuration-autofix_prs).
 - [ ] Included tests that prove the fix is effective or that the new feature works
-- [ ] Added necessary documentation (docstrings and/or example notebooks)
+- [ ] Added necessary documentation (docstrings and/or example notebooks) using [numpydoc format](https://numpydoc.readthedocs.io/en/latest/format.html).
 - [ ] If you are a pro: each commit corresponds to a [relevant logical change](https://wiki.openstack.org/wiki/GitCommitMessages#Structural_split_of_changes)
 <!--- You may find this guide helpful: https://mainmatter.com/blog/2021/05/26/keeping-a-clean-git-history/ -->
-
-## Modules affected
-<!--- Please list the modules that are affected by this PR by typing an `x` in the boxes below: -->
-- [ ] MMM
-- [ ] CLV
-- [ ] Customer Choice
-<!--- Additionally, if you are a maintainer or reviewer, please make sure that the appropriate labels are added to this PR -->
-
-## Type of change
-<!--- Select one of the categories below by typing an `x` in the box -->
-- [ ] New feature / enhancement
-- [ ] Bug fix
-- [ ] Documentation
-- [ ] Maintenance
-- [ ] Other (please specify):
-<!--- Additionally, if you are a maintainer or reviewer, please make sure that the appropriate labels are added to this PR -->

.github/release.yml

@@ -11,6 +11,9 @@ changelog:
     - title: Major Changes 🛠
       labels:
         - major
+    - title: Deprecations 🚨
+      labels:
+        - deprecation
     - title: New Features 🎉
       labels:
         - enhancement

.github/workflows/pre-commit.yml

@@ -0,0 +1,14 @@
+name: pre-commit
+
+on:
+  push:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v3
+      with:
+        python-version: "3.12"
+    - uses: pre-commit/action@v3.0.1

.github/workflows/test.yml

@@ -16,6 +16,10 @@ on:
      - "tests/**.py"
      - "pymc_marketing/**"
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 env:
   # 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')"

.github/workflows/test_notebook.yml

@@ -18,6 +18,10 @@ on:
      - "docs/source/notebooks/**.ipynb"
      - "!docs/source/notebooks/*/dev/**.ipynb"
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   example_notebooks:
     runs-on: ubuntu-latest
@@ -31,6 +35,6 @@ jobs:
       run: |
         sudo apt-get install graphviz
         pip install -e .[docs]
-        pip install -e .[test]
+        pip install -e .[test,dag]
     - name: Run notebooks
       run: make run_notebooks

.pre-commit-config.yaml

@@ -1,17 +1,18 @@
 ci:
   autofix_prs: false
+  skip: [mypy]
 
 repos:
   - repo: https://github.com/lucianopaz/head_of_apache
-    rev: "0.0.3"
+    rev: "0.1.0"
     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.9.1
+    rev: v0.9.5
     hooks:
       - id: ruff
         types_or: [python, pyi, jupyter]
@@ -21,7 +22,7 @@ repos:
         types_or: [python, pyi, jupyter]
         exclude: ^docs/source/notebooks/clv/dev/
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.14.1
+    rev: v1.15.0
     hooks:
       - id: mypy
         args: [--ignore-missing-imports]

CONTRIBUTING.md

@@ -182,6 +182,13 @@ Classes
 
 ![](docs/source/uml/classes_customer_choice.png)
 
+## 2025 CLV Roadmap
+
+![](docs/source/_static/clv_roadmap_2025.png)
+
+Review [task prioritization YAML](scripts/roadmaps/clv_tasks_priority.yaml) and open repo
+[issues](https://github.com/pymc-labs/pymc-marketing/issues?q=is%3Aissue%20state%3Aopen%20label%3ACLV) to work on.
+
 ---
 
 This guide takes some inspiration from the [Bambi guide to contributing](https://github.com/bambinos/bambi/blob/main/CONTRIBUTING.md)

README.md

@@ -68,6 +68,7 @@ Leverage our Bayesian MMM API to tailor your marketing strategies effectively. L
 | Time-varying Intercept                     | Capture time-varying baseline contributions in your model (using modern and efficient Gaussian processes approximation methods). See [guide notebook](https://www.pymc-marketing.io/en/stable/notebooks/mmm/mmm_time_varying_media_example.html).                                                                                                                                       |
 | Time-varying Media Contribution            | Capture time-varying media efficiency in your model (using modern and efficient Gaussian processes approximation methods). See the [guide notebook](https://www.pymc-marketing.io/en/stable/notebooks/mmm/mmm_tvp_example.html).                                                                                                                                                        |
 | Visualization and Model Diagnostics        | Get a comprehensive view of your model's performance and insights.                                                                                                                                                                                                                                                                                                                      |
+| Causal Identification                      | Input a business driven directed acyclic graph to identify the meaningful variables to include into the model to be able to draw causal conclusions. For a concrete example see the [guide notebook](https://www.pymc-marketing.io/en/stable/notebooks/mmm/mmm_causal_identification.html).                                                                                             |
 | 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.                                                                                                                                                     |
 | GPU Support                                | PyMC's multiple backends allow for GPU acceleration.                                                                                                                                                                                                                                                                                                                                    |
 | Out-of-sample Predictions                  | Forecast future marketing performance with credible intervals. Use this for simulations and scenario planning.                                                                                                                                                                                                                                                                          |
@@ -102,7 +103,7 @@ mmm = MMM(
 )
 ```
 
-Initiate fitting and get a visualization of some of the outputs with:
+Initiate fitting and get insightful plots and summaries. For example, we can plot the components contributions:
 
 ```python
 X = data.drop("y",axis=1)
@@ -113,13 +114,20 @@ mmm.plot_components_contributions();
 
 ![](docs/source/_static/mmm_plot_components_contributions.png)
 
+You can compute channels efficienty and compare them with the estimated return on ad spend (ROAS).
+
+<center>
+    <img src="docs/source/_static/roas_efficiency.png" width="70%" />
+</center>
+
 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.
+- 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.
+- Get started with a complete end-to-end analysis: from model specification to budget allocation. See the [guide notebook](https://www.pymc-marketing.io/en/stable/notebooks/mmm/mmm_case_study.html).
 
 ### Essential Reading for Marketing Mix Modeling (MMM)
 
@@ -139,12 +147,12 @@ Dynamic and interactive visualization of key Marketing Mix Modeling (MMM) concep
 
 Understand and optimize your customer's value with our **CLV models**. Our API supports various types of CLV models, catering to both contractual and non-contractual settings, as well as continuous and discrete transaction modes.
 
-- [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)
+- [CLV Quickstart](https://www.pymc-marketing.io/en/stable/notebooks/clv/clv_quickstart.html)
+- [BG/NBD model](https://www.pymc-marketing.io/en/stable/notebooks/clv/bg_nbd.html)
+- [Pareto/NBD model](https://www.pymc-marketing.io/en/stable/notebooks/clv/pareto_nbd.html)
+- [Gamma-Gamma model](https://www.pymc-marketing.io/en/stable/notebooks/clv/gamma_gamma.html)
 - [Shifted Beta-Geo model](https://www.pymc-marketing.io/en/stable/notebooks/clv/sBG.html)
-- [Modified BG/NBD model](https//pymc-marketing.readthedocs.io/en/stable/notebooks/clv/mbg_nbd.html)
+- [Modified BG/NBD model](https://www.pymc-marketing.io/en/stable/notebooks/clv/mbg_nbd.html)
 
 ### Examples
 
@@ -207,13 +215,17 @@ mvits = MVITS(
 # Fit model
 mvits.fit(X, y)
 
-# Plot counterfactuals
-mvits.plot_counterfactual()
-
 # Plot causal impact on market share
 mvits.plot_causal_impact_market_share()
+
+# Plot counterfactuals
+mvits.plot_counterfactual()
 ```
 
+<center>
+    <img src="docs/source/_static/conterfactual.png" width="100%" />
+</center>
+
 See our example notebooks for [saturated markets](https://www.pymc-marketing.io/en/stable/notebooks/customer_choice/mv_its_saturated.html) and [unsaturated markets](https://www.pymc-marketing.io/en/stable/notebooks/customer_choice/mv_its_unsaturated.html) to learn more about customer choice modeling with PyMC-Marketing.
 
 ## Why PyMC-Marketing vs other solutions?

docs/source/conf.py

@@ -10,7 +10,7 @@
 # General information about the project.
 project = "pymc-marketing"
 author = "PyMC Labs"
-copyright = f"2022, {author}"
+copyright = f"2022-%Y, {author}"
 html_title = "Open Source Marketing Analytics Solution"
 
 # The master toctree document.

docs/source/guide/mmm/comparison.md

@@ -16,4 +16,4 @@ Given the popularity of the Media Mix Modelling (MMM) approach, there are many p
 | Custom priors | ✅ | ✅ | ❌ | ❌ | ✅ |
 | Lift-test calibration | ✅  | ❌ | ✅ | ❌ | ✅ |
 | Out of sample predictions | ✅ | ✅ | ❌ | ✅ | ✅ |
-| Unit-tested | ✅ | ✅ | ❌ | ✅ | ? |
+| Unit-tested | ✅ | ✅ | ❌ | ✅ | ✅ |

docs/source/index.md

@@ -131,12 +131,12 @@ Leverage our Bayesian MMM API to tailor your marketing strategies effectively. L
 
 Understand and optimize your customer's value with our **CLV models**. Our API supports various types of CLV models, catering to both contractual and non-contractual settings, as well as continuous and discrete transaction modes:
 
-- [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)
+- [CLV Quickstart](https://www.pymc-marketing.io/en/stable/notebooks/clv/clv_quickstart.html)
+- [BG/NBD model](https://www.pymc-marketing.io/en/stable/notebooks/clv/bg_nbd.html)
+- [Pareto/NBD model](https://www.pymc-marketing.io/en/stable/notebooks/clv/pareto_nbd.html)
+- [Gamma-Gamma model](https://www.pymc-marketing.io/en/stable/notebooks/clv/gamma_gamma.html)
 - [Shifted Beta-Geo model](https://www.pymc-marketing.io/en/stable/notebooks/clv/sBG.html)
-- [Modified BG/NBD model](https//pymc-marketing.readthedocs.io/en/stable/notebooks/clv/mbg_nbd.html)
+- [Modified BG/NBD model](https://www.pymc-marketing.io/en/stable/notebooks/clv/mbg_nbd.html)
 
 Each of these models is tailored to different types of data and business scenarios:
 

docs/source/notebooks/clv/clv_quickstart.ipynb

@@ -24,7 +24,7 @@
     "* **[BG/BB model](https://www.pymc-marketing.io/en/latest/api/generated/pymc_marketing.clv.models.beta_geo_beta_binom.BetaGeoBetaBinomModel.html)** for discrete time, contractual modeling\n",
     "* **Exponential Gamma model** for discrete time, contractual modeling (coming soon)\n",
     "* **[Gamma-Gamma model](https://pymc-marketing.readthedocs.io/en/stable/notebooks/clv/gamma_gamma.html)** for expected monetary value\n",
-    "* **[Modified BG/NBD model](https://pymc-marketing.readthedocs.io/en/stable/notebooks/clv/mbg_nbd.html)**, similar to [BG/NBD model](https://pymc-marketing.readthedocs.io/en/stable/notebooks/clv/bg_nbd.html) but assigning \"drop out\" probability after first purchase\n",
+    "* **[Modified BG/NBD model](https://pymc-marketing.readthedocs.io/en/stable/notebooks/clv/mbg_nbd.html)**, similar to the BG/NBD model, but assumes non-repeat customers are still active.\n",
     "\n",
     "This table contains a breakdown of the four BTYD modeling domains, and examples for each:\n",
     "\n",

docs/source/notebooks/index.md

@@ -10,6 +10,7 @@ Here you will find a collection of examples and how-to guides for using PyMC-Mar
 mmm/mmm_allocation_assessment
 mmm/mmm_budget_allocation_example
 mmm/mmm_case_study
+mmm/mmm_causal_identification
 mmm/mmm_components
 mmm/mmm_counterfactuals
 mmm/mmm_evaluation