Market Matching: Models
Overview
Market Matching offers three matching algorithms. All produce ranked control markets with similarity scores and balance diagnostics, but they differ in which features they use and how similarity is computed.
| Method | Features used | Similarity approach | Best for |
|---|---|---|---|
| balanced | 8 fingerprint features | Euclidean distance (scaled) | Default — full behavioral comparison |
| causal | 7 features (excludes outcome_cv) | Propensity score distance | Causal-style pairing emphasis |
| quick | 3 features (mean, std, trend) | Euclidean on core features | Fast screening or large datasets |
All three use the same SMD-based balance check downstream.
Geo fingerprints (input to all methods)
Before matching, each market is summarized into a fingerprint from its outcome time series:
- Level — mean outcome
- Volatility — standard deviation, coefficient of variation
- Trend — Theil-Sen slope (robust to outliers)
- Seasonality — STL decomposition strength
- Stability — autocorrelation, residual variance, spikiness
- Range — min–max spread
Similarity is computed by comparing these fingerprints between the test market and each candidate control.
1) Balanced matching (default)
How it works
- Uses 8 fingerprint features (all except propensity-related fields)
- Features are standardized (zero mean, unit variance)
- Similarity =
1 / (1 + euclidean_distance)between test and control fingerprints - Higher score = closer match
Strengths
- Most comprehensive behavioral comparison
- Good default for most use cases
- Balances depth and interpretability
When to use
- Standard matching runs
- When you want the fullest pre-period comparison
- When match quality matters more than speed
Plain-language summary
"Find control markets whose sales patterns look most like the test market across level, trend, seasonality, and stability."
2) Causal matching
How it works
- Uses 7 fingerprint features (excludes
outcome_cv) - Computes a propensity score for each market via logistic regression
- Similarity =
1 / (1 + propensity_score_distance) - Emphasizes markets that would be assigned similar treatment probability in a causal framework
Strengths
- Aligns with causal inference best practices
- Useful when you want propensity-aware pairing
- Reduces reliance on raw outcome level alone
When to use
- When causal rigor in control selection is a priority
- When outcome level differences are large but behavioral patterns are similar
- As an alternative to balanced when results need comparison
Plain-language summary
"Match markets that are statistically likely to behave the same way, not just markets with similar average sales."
3) Quick matching
How it works
- Uses only 3 core features:
mean_outcome,std_outcome,trend - Same euclidean similarity formula as balanced, but on fewer dimensions
- Faster execution with simpler comparison
Strengths
- Fastest matching option
- Good for initial screening
- Works when data history is limited
When to use
- Quick exploratory matching
- Large numbers of candidate markets
- When you need a fast first pass before a deeper balanced run
Plain-language summary
"Quickly find markets with similar average sales, volatility, and trend direction."
Balance check (shared across all methods)
After controls are ranked, each test–control pair is evaluated for balance:
- SMD (Standardized Mean Difference) is computed per feature
- Time-series autocorrelation is accounted for in effective sample size
- Pair is balanced when all feature SMDs are within threshold
Balance status appears in:
- primary results table,
- quality assessment,
- PDF report heatmap.
How to choose a method
| Situation | Recommended method |
|---|---|
| Standard production run | balanced |
| Causal experiment setup | causal |
| Fast screening / many geos | quick |
| Unsure which to use | Start with balanced, compare with causal if needed |
Quality gate
An autonomous quality filter runs after matching:
- Pairs below minimum match quality may be dropped
- Unbalanced pairs can be excluded (configurable)
- If all pairs fail, the system may salvage the top available pair with a warning
Warning comments you may see:
- "No similar markets found for selected test market(s)"
- "Filtered out poor-quality market candidates"
- "All markets failed strict quality threshold — salvaged top candidate"
Key outputs per method
Regardless of which algorithm runs, each match result includes:
| Output | What it means |
|---|---|
| treatment_geo | Test market analyzed |
| control_geos | Selected control markets |
| similarities | Similarity score per control (0–1, higher is better) |
| balance_stats | Per-feature SMD values |
| is_balanced | Whether the pair passes balance threshold |
| method | Which algorithm produced this result |
| quality_score | Overall match reliability (0–1) |
For the full pipeline sequence, see market-matching-methodology.
For interpreting final outputs, see market-matching-results.