Quick Start Guide

Get up and running with GeoLift in 5 minutes to measure the causal impact of your marketing campaigns.

Business Value in 30 Seconds

Problem Solved: Measure true incremental lift from regional marketing campaigns
Why It Matters: Prove ROI, optimize budget allocation, avoid false positives
Integration: Works alongside MMM, attribution, and A/B testing
Impact: Enables data-driven optimization for 10-30% efficiency improvements
Process: 3 simple steps - find controls, check power, measure lift

Installation

pip install -e .
# Optional (GPU acceleration for Stage 1 Power on CUDA 12.x):
# pip install cupy-cuda12x

Your First Analysis in 3 Steps

Step 1: Prepare Your Data

Create a CSV file with your sales data containing these columns:

  • date - Date of observation

  • geo - Geographic unit identifier (DMA, state, etc.)

  • sales - Your outcome metric

  • treatment - Binary indicator (1 for treated markets, 0 for control)

Example data structure:

date,geo,sales,treatment
2023-01-01,501,1000,0
2023-01-01,502,1200,1
2023-01-02,501,1050,0
2023-01-02,502,1300,1

Step 2: Run the Analysis

Run the end-to-end pipeline (Power → Donor → Inference) with the provided sample configs:

python runme.py

Or run individual stages:

  • Power analysis (GPU optional):

    python recipes/power_calculator_sparsesc.py \
  --config data-config/power_analysis_config.yaml \
  --use-gpu --jobs -1

  • Donor evaluation:

    python recipes/donor_evaluator.py --config data-config/donor_eval_config.yaml

  • Inference:

    python recipes/geolift_multi_cell.py --config data-config/geolift_analysis_config.yaml

Step 3: View Results

After the pipeline completes, check these outputs:

  • Power: outputs/multicell_power_analysis/

    • power_curves.png, power_analysis_results.csv

  • Donor evaluation: outputs/multicell_donor_eval/

    • donor_eval_results.csv, donor_map_*.png

  • Inference: outputs/multicell_geolift_analysis/

    • geolift_results.json, geolift_diagnostics.json, uplift_timeseries.png

  • Compact reports (summary):

    • outputs/geolift_pipeline_report.md, outputs/geolift_pipeline_report.html

What You’ll Get

  • Causal Impact Estimate: How much incremental lift your campaign generated

  • Statistical Significance: P-values and confidence intervals

  • Visual Diagnostics: Pre/post treatment plots and synthetic control fit

  • Business Metrics: ROI, cost per incremental unit, and efficiency metrics

Next Steps

  • Need more control? → See User Guide for detailed configuration

  • Want to understand the methods? → Check Advanced Topics

  • Having issues? → Review FAQ for common solutions

Sample Output

Your analysis will produce:

=== GeoLift Analysis Results ===
Treatment Period: 2023-06-01 to 2023-08-31
Treated Markets: [502, 503]

Causal Impact:
- Absolute Lift: +2,450 units (95% CI: +1,200 to +3,700)
- Relative Lift: +15.2% (95% CI: +7.8% to +22.6%)
- P-value: 0.003 (statistically significant)

Business Impact:
- Total Incremental Revenue: $245,000
- Campaign Cost: $50,000
- Incremental ROI: 4.9x

Ready to dive deeper? Continue to the User Guide for comprehensive workflows and best practices.