causalscience/retail-campaign-simulator

Retail Campaign Simulator

Overview

The Retail Campaign Simulator is an interactive application that generates and analyzes synthetic retail marketing campaign data. It provides detailed insights into campaign performance through comprehensive analysis and interactive visualizations. Whether you're testing campaign strategies, optimizing promotional tactics, or analyzing customer segment performance, this tool provides a realistic environment for retail marketing experimentation.

Technology Stack

• —Python: Core programming language
• —Gradio: User-friendly interface
• —DuckDB: Efficient data storage and query processing
• —Plotly: Interactive data visualizations
• —Faker: Synthetic data generation

Features

Data Generation

Generate customizable synthetic data including:

• —Customer profiles across multiple segments
• —Detailed transaction records
• —Campaign effectiveness metrics
• —Customer segmentation (Loyalty Members, High-Spending Customers, Email Subscribers, New and Lapsed Customers)
• —Channel distribution (Digital, Flagship Stores, Standard Stores)

All generated data is stored in campaign_db.duckdb within a data directory.

Analysis & Reports

Analyze the generated data to obtain detailed reports on:

• —Campaign Impact Analysis: Compare test vs. control groups to measure overall campaign lift
• —Test and control demand metrics
• —Demand per customer analysis
• —Incremental revenue calculations

• —Segment Performance: Analyze which customer segments responded best
• —Segment-level test vs. control comparisons
• —Incremental sales by segment
• —Return on investment by customer type

• —Channel Effectiveness: Compare performance across shopping channels
• —Digital vs. flagship vs. standard store performance
• —Channel-specific incremental metrics
• —Customer shopping patterns

• —Tactical Response Rates: Evaluate which promotional tactics worked best
• —Tactic-level response rates by segment
• —Per-responder revenue metrics
• —Markdown efficiency analysis

Interactive Visualizations

Visual analyses include:

• —Tactic Response Rates by Segment
• —Time Series Demand
• —Weekly Incremental Demand
• —Regional Demand Analysis
• —Top Performing Stores
• —Transaction Amount Distribution
• —Margin vs. Promotional Discounts

Access and Installation

This application is hosted on Hugging Face Spaces and requires no installation. Simply access it through your web browser at:

https://huggingface.co/spaces/[your-username]/retail-campaign-simulator

All processing occurs on the Hugging Face servers, so you don't need to install any dependencies locally.

Usage Guide

Steps to Operate

1. 1.Navigate to the Generate Data tab:
2. 2.Set your parameters (or use defaults for initial testing)
3. 3.Click Generate Data
4. 4.Move to the Analyze Data tab
5. 5.Upload your generated campaign_db.duckdb file
6. 6.Click Run Final Analysis to generate reports and visualizations

Example Use Cases

• —Segment Optimization: Adjust segment weights and compare incremental revenue per segment to determine where to focus marketing efforts
• —Promotional Mix Testing: Modify offer effectiveness and rates to find the optimal combination of promotions
• —Channel Strategy: Compare performance between digital and store channels by adjusting the online percentage and digital boost
• —Store Format Analysis: See how flagship stores perform compared to standard locations

Configurable Parameters Explained

Basic Parameters

• —Number of Customers: Total unique customers in the simulation
• —Number of Transactions: Total transactions generated across all customers
• —Campaign Dates: Define the time period for the campaign

Campaign Structure

• —Control Group Percentage: Portion of customers who don't receive promotions (essential for measuring lift)
• —Segment Weights: Relative distribution of customers across segments
• —Higher weights increase the proportion of customers in that segment
• —Set weights to 0 to exclude segments entirely
• —Online Channel Percentage: Percentage of customers who prefer shopping online vs in-store

Financial Parameters

• —Base Purchase Amount:
• —Mean: The average transaction amount before promotions
• —Std Dev: Variance in transaction amounts (higher = more variable spending)
• —Response Multiplier Preset: How differently segments respond to offers
• —Default: Balanced response across segments
• —High Variance: More dramatic differences between segment responses
• —Low Variance: More uniform response across segments

Promotional Offers

• —Effectiveness: Multiplier for how well each tactic drives additional sales
• —Values > 1.0 increase the impact of an offer
• —Values < 1.0 decrease the impact
• —Rate: The percentage of transaction value provided as a discount
• —Example: A rate of 0.2 means a 20% discount on eligible purchases

Regional Parameters

• —Max Store Count: Number of physical store locations in the simulation
• —Digital Channel Boost: Multiplier for digital channel performance (higher values = stronger online sales)

Using Your Own Data

While the application can generate synthetic data, you can also use it with your own campaign data by following these guidelines:

Required Data Structure

To use your own data, you'll need to create a DuckDB database with two specific tables:

1. Contacts Table (Contacts_Campaign)

2. Transaction Table (Demand_Campaign)

Creating Your Own DuckDB File

You can create and populate the required DuckDB database in any way that works for your workflow:

1. 1.Create the database with the schema matching the tables described above
2. 2.Populate the tables using your preferred method (SQL inserts, importing from CSV/JSON/Parquet, programmatic data loading, etc.)
3. 3.Optionally, create indices for better performance:

CREATE INDEX idx_contacts_party_id ON Contacts_Campaign (party_id);
CREATE INDEX idx_demand_cal_dt ON Demand_Campaign (cal_dt);

1. 1.Save the DuckDB file and upload it in the Analyze Data tab

Adapting Your Existing Data

If your data doesn't perfectly match this schema:

1. 1.Customer/Contact Data:
2. 2.Must have unique customer IDs
3. 3.Must have test/control designation
4. 4.Should include segmentation if possible

1. 1.Transaction Data:
2. 2.Must link to customer IDs
3. 3.Must include transaction amounts
4. 4.Must have dates within campaign period
5. 5.Should include channel information
6. 6.Promotional tactic fields can be populated with your specific tactics

1. 1.Mandatory Fields (minimum required):
2. 2.In Contacts: partyid, controlgrp_ind
3. 3.In Demand: partyid, controlgrpind, caldt, demand

License

Open-source and free for modification under the MIT License.