Quickstart Guide

This guide provides a complete walkthrough for getting started with AMMM on your local machine (e.g., Linux laptop).

Recommended Process for Getting Started

Step 1: Set up your environment

First, ensure you have Python 3.10-3.12 installed. Then set up a fresh virtual environment:

# Clone the repository
git clone https://github.com/tandpds/ammm.git
cd ammm

# Create and activate a fresh virtual environment
python -m venv venv_ammm
source venv_ammm/bin/activate  # On Windows: venv_ammm\Scripts\activate

# Upgrade build tooling (recommended)
python -m pip install --upgrade pip setuptools wheel

# Install AMMM in development mode
pip install -e .

Note for Windows users: We recommend using Conda for easier installation of dependencies like Prophet. See the Installation guide for Conda instructions.

Step 2: Run the demo pipeline

Start with the provided demo to understand how AMMM works:

# Run the demo with example data and configuration
python runme.py

This command will:

• If data-config/ exists: auto-detect a single config file and a single data file from that folder
• Otherwise: fall back to the demo configuration (demo/demo_config.yml) and demo dataset (demo/demo_data.csv)
• Write outputs under results/ by default (override with --results-dir)

Step 3: Examine the results

After running the demo, explore the generated outputs:

# Navigate to the results folder
cd results/

# Key outputs to examine:
# - png/: Diagnostic plots and visualizations
# - csv/: Data exports and decomposition results
# - json/: Model configuration used
# - other/: Prophet model and ELPD diagnostics

** Pay special attention to diagnostics:**

• model_fit_predictions.png - Check how well the model fits your data
• model_trace.png - Verify MCMC convergence
• model_priors_and_posteriors.png - Understand parameter distributions
• response_curves.png - Review saturation curves for each channel

Step 4: Follow the documentation for guidance

For best practices and guidance:

1. Start with Getting Started Guide:

   • Review Data Preparation
   • Understand Configuration

2. Model Development Best Practices:

   • Variable Selection: Think carefully about which variables to include
   • Diagnostics First: Always examine diagnostic plots before trusting results
   • Be Systematic: Model different specifications to get a complete empirical view
   • Iterate: Start simple, add complexity gradually

3. Key Documentation Resources:

   • AMMM Methodology - Understand the underlying model
   • Interpreting Results - Make sense of outputs
   • Troubleshooting Guide - Common issues and solutions

Step 5: Customize for your data

Once comfortable with the demo, adapt it for your own data:

from ammm.driver import MMMBaseDriverV2

# Point to your own files
config_file = "path/to/your/config.yml"
data_file = "path/to/your/data.csv"
holidays_file = "path/to/holidays.xlsx"  # Optional
output_folder = "your_results"

# Initialize and run
driver = MMMBaseDriverV2(
    config_filename=config_file,
    input_filename=data_file,
    holidays_filename=holidays_file,
    results_filename=output_folder
)
driver.main()

Understanding the Demo Files

The demo/ directory contains everything you need to get started:

• demo_config.yml: Example configuration showing all available options

  • Media transformation settings (saturation, adstock)
  • Model parameters and priors
  • Optimization settings
  • Output preferences
  • Budget analysis settings (scenario planning vs optimisation) are selected via runme.py CLI flags

• demo_data.csv: Sample marketing dataset with:

  • Date column for time series
  • KPI/target variable (e.g., sales, conversions)
  • Media spend columns for different channels
  • Control variables (price, promotions, etc.)

• runme.py: Simple script showing how to run the pipeline

  • Loads configuration and data
  • Initializes the AMMM driver
  • Runs the complete modeling workflow

• holidays.xlsx (optional): Holiday calendar for seasonality modeling

Choosing a Run Mode

AMMM supports two distinct run modes that determine the type of optimization analysis performed:

Scenario Planning Mode (Default)

This mode evaluates multiple budget allocation scenarios to help you understand the impact of different spending strategies. It’s ideal for exploring “what-if” scenarios and comparing different budget allocations.

Key outputs:

• csv/budget_scenario_results.csv - Detailed comparison of scenarios
• png/scenario_*.png - Visual comparisons and analysis

Best for: Strategic planning, budget presentations, understanding trade-offs

Optimization Mode

This mode finds a mathematically optimal budget allocation under a fixed total budget by:

1. Fitting per-channel response curves from the MMM (spend → expected contribution), then
2. Solving a constrained non-linear optimisation problem (SciPy SLSQP) to maximise total expected contribution subject to budget and per-channel bounds.

Key outputs:

• csv/optimization_results.csv - Optimal budget allocation
• png/budget_optimisation.png - Current vs. optimal visualization

Best for: Finding the single best allocation, maximizing returns

To select a run mode, use the runme.py CLI flags:

# Scenario planning (default)
python runme.py

# Scenario planning with custom scenario percentages
python runme.py --scenarios "-10,-5,0,5,10"

# Single-period budget optimisation (disable scenarios)
python runme.py --no-scenarios

# Multi-period optimisation (e.g., 13 weeks)
python runme.py --multiperiod --multiperiod-weeks 13

Quick Tips for Success

✅ DO:

• Start with the demo to understand the workflow
• Carefully review diagnostic plots
• Test multiple model specifications
• Use lift test calibration if you have experimental data
• Document your modeling decisions

❌ DON’T:

• Skip diagnostic checks
• Use results from poorly converged models
• Include too many variables without justification
• Ignore warnings in the output

Pipeline Usage

We provide two convenience scripts, aligned with runme.py, to run the full pipeline:

• Linux/macOS: run_pipeline_linux.sh
• Windows: run_pipeline_windows.bat

Typical usage

# Linux/macOS (first time only)
chmod +x run_pipeline_linux.sh

# Run with default scenario planning
./run_pipeline_linux.sh

# Disable scenarios
./run_pipeline_linux.sh --no-scenarios

# Custom scenario percentages
./run_pipeline_linux.sh --scenarios "-10,-5,0,5,10"

# Provide explicit file paths (overrides auto-detection)
./run_pipeline_linux.sh \
  --data data-config/demo_data.csv \
  --config data-config/demo_config.yml \
  --holidays data-config/holidays.xlsx

:: Windows (from Command Prompt)
run_pipeline_windows.bat

:: Disable scenarios
run_pipeline_windows.bat --no-scenarios

:: Custom scenario percentages
run_pipeline_windows.bat --scenarios "-10,-5,0,5,10"

:: Provide explicit file paths (overrides auto-detection)
run_pipeline_windows.bat ^
  --data "data-config\demo_data.csv" ^
  --config "data-config\demo_config.yml" ^
  --holidays "data-config\holidays.xlsx"

Need Help?

• Check the Troubleshooting Guide for common issues
• Review the Configuration Reference for parameter details

Next Steps

After successfully running the demo:

1. Data Preparation: Learn how to prepare your own data in Data Preparation Guide
2. Configuration: Deep dive into configuration options in Configuration Guide
3. Advanced Features: Explore Lift Test Calibration and Prior Calibration
4. Optimization: Learn about Budget Optimization