Documentation

The Problem

You’re spending more on ads every quarter and trusting the numbers less. The platforms say your campaigns are working. Your CFO says prove it. And nobody can separate weather-driven sales from ad-driven sales — because the two are confounded.

If you sell sunscreen, outdoor furniture, beverages, HVAC, apparel, or anything else where weather moves the needle, you already feel this. A sunny weekend explodes demand and your bids don’t move fast enough. A cold snap kills conversions and you’re still spending yesterday’s budget. The weather is in your dashboards — you just can’t act on it.

The Complexity Gap

Marketing teams write rules: “boost sunscreen ads when it’s hot.” But weather-demand relationships are multi-variable, non-linear, and category-specific. Temperature alone has interaction effects with humidity, UV index, wind speed, precipitation, and the trailing five-day trajectory. A hot day in Phoenix (where 105°F is normal) is categorically different from a hot day in Seattle (where 85°F is an event). Rules collapse the moment reality gets complicated.

The gap between what a rule system can represent and what weather actually does to demand is enormous. Thagorus closes that gap with a causal model that captures the full surface of weather-demand interaction — not the <0.001% a rule system covers.

How It Works

The core question Thagorus answers is not “does weather affect demand?” (it obviously does). The question is: how much of the sales lift you see on a hot weekend was caused by your ads, and how much would have happened anyway because of the weather?

Weather as a Natural Experiment

The econometric solution to this is instrumental variables — finding a source of variation that shifts demand but is uncorrelated with advertising decisions. Philip G. Wright used weather as the first instrument in the history of econometrics (1928), estimating demand elasticities for agricultural commodities using regional rainfall.

Weather works as an instrument because it satisfies the core requirements by construction: advertisers cannot cause the weather, daily weather realizations are not anticipated by budget cycles set weeks in advance, and weather measurably shifts consumer demand across dozens of product categories. Dell, Jones & Olken (2014) survey 83 papers in top-5 economics journals that use weather for causal identification.

Continuous Identification

Google’s Meridian recommends geo-holdout experiments for causal calibration. Each experiment costs real revenue, takes 4-8 weeks, and produces a single noisy estimate for a single channel. Most brands run one or two per year.

Weather-shock identification inverts this tradeoff: it provides thousands of natural experiments per year across every geography, at zero cost, for every channel simultaneously. The LCDM uses weather shocks — deviations from seasonal norms — as continuous natural experiments. Every cold snap, heat wave, and rainstorm that departs from expectations provides exogenous demand variation that separates weather-driven sales from ad-driven sales.

This is not weather-triggered ad targeting. It is weather-driven causal identification — a fundamentally different capability.

Architecture

The LCDM is not a single model. It is a stack of complementary models, each contributing a different capability — running on a single node, no Spark, no warehouse, no distributed compute overhead.

Pipeline Stages

What the Model Sees

The Network

James and Stein proved something in 1961 that startled the statistics community: estimating three or more quantities separately is always worse than estimating them together. Always. This result is so counterintuitive it sparked a decade of debate. Efron & Morris (1975) demonstrated it using baseball batting averages — a 71% error reduction.

Cross-Tenant Learning

Most advertisers on the platform have limited history: perhaps 6-12 months of daily data across a handful of markets. Estimating market-category-specific demand elasticities from this alone is noisy. We address this with empirical Bayes shrinkage: each tenant’s parameter estimates are pulled toward the network-wide posterior, with the degree of pull determined by data quality.

A new sunscreen brand joining the platform instantly inherits UV-demand patterns learned across all personal care brands on the network. A mature brand with two years of data retains its own estimates with minimal shrinkage. The math is settled (James & Stein, 1961; Efron & Morris, 1975). The question is not whether to pool — it is how aggressively (Gelman & Hill, 2006).

Safety Guards

Integration

The API accepts weather context and returns dollar-denominated spend recommendations with full evidence trails. Built on FastAPI with OpenAPI schema generation. All endpoints are versioned under /v1 and require API key authentication via the X-WV-Key header. Responses include product-level lift estimates, budget shift amounts in USD, confidence intervals, and the specific conditions that would reverse the recommendation.

Sample Request

curl -X POST https://api.weathervane.ai/v1/recommend \
  -H "X-WV-Key: wv_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": "sunco-sunscreen",
    "dma": "phoenix-az",
    "date_range": "2026-06-14/2026-06-16",
    "weather_context": {
      "temperature_f": 103,
      "uv_index": 9.2,
      "humidity_pct": 18,
      "wind_mph": 5,
      "cloud_cover_pct": 8,
      "temp_derivative_1": 2.5,
      "consecutive_hot_days": 3
    }
  }'

Sample Response

{
  "recommendation": {
    "action": "increase_spend",
    "budget_shift_usd": 23400,
    "confidence_interval_90": [19800, 27100],
    "products": [
      {
        "sku": "spf50-beach-lotion",
        "lift_pct": 41,
        "note": "UV-driven, peak elasticity zone"
      },
      {
        "sku": "after-sun-aloe",
        "lift_pct": 28,
        "note": "24h UV lag → burn-care window"
      },
      {
        "sku": "zinc-face-shield",
        "lift_pct": 18,
        "note": "Outdoor athlete segment"
      }
    ],
    "break_conditions": [
      "cloud_cover > 60% → pause recommendation",
      "temperature > 105F → monitor for indoor-inversion",
      "forecast_uncertainty > 8F → widen intervals"
    ]
  },
  "evidence_bundle_url": "/v1/evidence/phx-20260614-sunscreen"
}

Webhook Pattern

Register a webhook URL to receive real-time alerts when weather conditions cross actionable thresholds. Webhooks fire within 15 minutes with the full evidence bundle: the triggering weather signal, the dollar-denominated recommendation, the confidence interval, and the conditions that would reverse the call.

curl -X POST https://api.weathervane.ai/v1/webhooks \
  -H "X-WV-Key: wv_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-dsp.com/wv-trigger",
    "events": [
      "weather_shock.uv_spike",
      "weather_shock.heat_wave",
      "weather_shock.cold_snap",
      "weather_shock.precip_event"
    ],
    "dma_filter": ["phoenix-az", "denver-co", "chicago-il"],
    "categories": ["sunscreen", "cold-beverage", "outerwear"],
    "min_budget_shift_usd": 5000
  }'

Getting Started

Safety & Guardrails

Thagorus is designed to be wrong safely. Every automated system eventually encounters conditions outside its training distribution. The question is not whether the model will be wrong — it is whether the system degrades gracefully when it is.

We pre-register four evaluation components that customers can run on their own data without our involvement: decision lift (does the policy improve incremental profit vs. baselines?), calibration (do confidence intervals match realized coverage?), ablation (does removing weather features degrade performance specifically in weather-sensitive categories?), and safety audit (how often do circuit breakers trigger, and what is the distribution of drawdowns?).

Roadmap

Thagorus is honest about what exists and what is planned. The science is designed. The first pipeline is built. Real-world validation with design partners is the current milestone.

• Weather-shock identification v1.0

  Natural experiments using weather deviations across markets for continuous causal identification.
• Hierarchical partial pooling v1.0

  Empirical Bayes shrinkage across tenants and categories. James-Stein theorem guarantees improvement for 3+ entities.
• Evidence bundles v1.0

  Confidence intervals, break conditions, backtests, and full audit trails with every recommendation.
• Shadow mode with human-in-the-loop v1.0

  Model generates recommendations; humans approve. Safety default for all new tenants.
• Deep learning demand models

  Cross-attention weather encoding, temporal transformers, and time-series foundation model integration for zero-shot new category onboarding.
• Reinforcement learning optimization

  Weather-contingent budget policies with model predictive control. Closed-loop optimization that adjusts as forecasts update.
• Federated cross-tenant intelligence

  Privacy-preserving cross-tenant learning. Each tenant contributes to the network without exposing raw data.
• Cross-economy demand graph

  A heatwave in Phoenix increases sunscreen demand, shifts discretionary spending in Tucson, reroutes cold-chain logistics from Dallas, and moves insurance pricing in Scottsdale. These cascades emerge from the graph.

If you’ve read this far, you should probably talk to us.

References

The LCDM draws on a deep body of work in causal inference, hierarchical modeling, control theory, and marketing science. Key references:

1. Wright, P. G. (1928). The Tariff on Animal and Vegetable Oils. Macmillan. First instrumental variables estimation in econometric history, using weather to identify demand elasticities.
2. James, W. & Stein, C. (1961). Estimation with quadratic loss. Proceedings of the Fourth Berkeley Symposium. Proved that pooled estimation always dominates individual estimation for three or more quantities.
3. Efron, B. & Morris, C. (1975). Data analysis using Stein’s estimator and its generalizations. Journal of the American Statistical Association, 70(350), 311-319. 71% error reduction demonstrated with baseball batting averages.
4. Dell, M., Jones, B. F., & Olken, B. A. (2014). What do we learn from the weather? The new climate-economy literature. Journal of Economic Literature, 52(3), 740-798. Canonical survey of 83 papers using weather as an instrument for causal identification.
5. Gordon, B. R., Zettelmeyer, F., Bhatt, N., & Dias, F. (2019). A comparison of approaches to advertising measurement. Marketing Science, 38(6), 913-940. Documents the failure of observational MMMs vs. randomized experiments.
6. Shapiro, B. T., Hitsch, G. J., & Tuchman, A. E. (2021). TV advertising effectiveness and profitability. Econometrica, 89(4), 1855-1879. Panel data with instrumental variables for ad effectiveness measurement.
7. Gelman, A. & Hill, J. (2006). Data Analysis Using Regression and Multilevel/Hierarchical Models. Cambridge University Press. Practical framework for partial pooling and hierarchical models.
8. Chernozhukov, V. et al. (2018). Double/debiased machine learning for treatment and structural parameters. The Econometrics Journal, 21(1), C1-C68. Orthogonal scores for causal estimation with high-dimensional nuisance parameters.