How pymc-labs/pymc-marketing works
Main components
• Core Library (pymc_marketing package)
• Submodules: mmm (models, builders, components), clv (models, distributions, utilities), customer_choice (MVITS), bass, model_builder, model_config, model_graph, mlflow integration, plotting, utils.
• CLI / Scripts
• scripts/run_notebooks, scripts/docker, scripts/generate_gallery, scripts/slowest_tests, scripts/warnings_in_tests.
• Documentation Site
• Sphinx source in docs/source, ReadTheDocs integration (.readthedocs.yml).
• Generated API reference, gallery notebooks, guides.
• Streamlit Explainer App
• streamlit/mmm-explainer folder with pages, config.toml.
• Data Assets
• data/raw CSVs, config_files (YAML), processed training sets.
• CI/CD & DevOps
• GitHub workflows for tests, notebooks, UML, PyPI releases.
• pre-commit, Makefile, environment.yml, pyproject.toml.
• External Services
• PyPI (package distribution), ReadTheDocs (docs hosting), GitHub (source), Codecov (coverage), Docker Hub (optional), MLflow tracking (optional at runtime).
Relationships & interactions
• Users import the Core Library into Jupyter notebooks or production Python code.
• CLI scripts call the Core Library APIs (e.g., generate_gallery → docs, run_notebooks → execute examples).
• The Streamlit App imports Core Library to expose interactive visualizations.
• GitHub Actions workflows:
• test.yml installs environment.yml/pyproject, runs unit tests (tests/).
• test_notebook.yml uses nbformat to execute docs notebooks.
• pypi.yml builds and publishes to PyPI.
• rtd-link-preview builds docs and updates ReadTheDocs preview.
• Data flow:
• Raw data in data/ → Core Library preprocessing → model fitting → output artifacts (plots, models).
• Docker:
• scripts/docker/Dockerfile bundles Core Library, Jupyter for easy notebook access.
Architectural patterns & principles
• Modular design: clear separation of concerns (MMM, CLV, CSA, Bass).
• Builder pattern: YAML-driven model builders for MMM (builders/factories, yaml).
• Plugin-style extensibility: ability to swap adstock/saturation functions.
• CI as code: GitHub workflows orchestrate testing, docs, releases.
• Documentation-first: gallery and guide notebooks integrated into docs pipeline.
Technologies, frameworks & libraries
• Python (typing, pyproject.toml packaging).
• PyMC (probabilistic modeling), ArviZ (diagnostics).
• Sphinx & MyST-NB for docs.
• Streamlit for explainer app.
• Conda-Forge environment (environment.yml).
• GitHub Actions for CI/CD.
• Docker for container images.
• MLflow for experiment tracking (optional integration).