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 <your_git_url>/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:

• Use the demo configuration (demo/demo_config.yml)

• Process the demo dataset (demo/demo_data.csv)

• Generate detailed results in a timestamped folder under results/

Step 3: Examine the results

After running the demo, explore the generated outputs:

# Navigate to the results folder (created with timestamp)
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 src.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

  • Run mode selection (scenario planning or optimization)

• 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 the mathematically optimal budget allocation to maximize ROI or other specified objectives using advanced optimization algorithms.

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, add to your configuration file:

# For Scenario Planning (default)
run_mode: "scenario_planning"

# For Optimization
run_mode: "optimization"

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