Fuel Detective User Guide

Practical interpretation for operations, analytics, and anomaly triage.

JS Labs Index| UK Fuel Dashboard| Fuel Detective Report| LLM info

Dataset scope UK national forecourt full-history dataset

Core model signal change_probability

Uncertainty signal Bootstrap 10/50/90 percentiles

Validation mode Walk-forward CV

Brand intelligence Data-driven positioning stats

Location intelligence Postcode-sector market map

Is The Narrative Correct?

Mostly yes The key value is timing decisions, local competition context, and anomaly triage.

Important caveat change_probability is a proxy for likely near-term update behavior (based on recency labeling), not a guaranteed direction or exact size of a future price move.

Decision Confidence Framework

Decision lane	Rule	Recommended action
Action now	`change_probability >= 0.70` and `(upper - lower) <= 0.20` and no `high` anomaly.	Apply operational routing or pricing response.
Validate first	`anomaly_level == "high"` or `diesel_cheaper_anomaly == 1` or wide uncertainty interval.	Run manual checks before taking action.
Monitor	No strong signal and no critical anomaly.	Keep under routine monitoring and re-evaluate on next refresh.

What Each Output Means

Field	Meaning	How to use it
`change_probability`	Model estimate that station behaves like a near-term updater.	Use policy thresholds (for example, >= 0.70) for action queues.
`change_prob_lower`, `change_prob_median`, `change_prob_upper`	Bootstrap uncertainty band (10th/50th/90th percentiles).	Prefer decisions with narrow uncertainty width.
`anomaly_score` and `anomaly_level`	Combined statistical and business-rule anomaly severity.	Triage `high` first for human review.
`diesel_cheaper_anomaly`	Diesel below petrol at station level.	Validate quickly; often data or pricing edge case.
`price_vs_competitor_avg`	Station E10 relative to local competitor average.	Detect local mispricing and tension points.
`is_cheapest_in_area`	Station is at or near local minimum.	Candidate for immediate dispatch/fill strategy.
`postcode_sector`	Outer postcode sector extracted from station postcode.	Use for local routing and area-level policy rules.
`brand_avg_vs_comp`, `brand_price_position_score`	Learned brand behavior versus local competition from data.	Compare station behavior against its brand baseline.
`sector_avg_price`, `sector_price_range`, `sector_herfindahl`	Postcode-sector baseline, dispersion, and market concentration.	Prioritize concentrated sectors and high spread sectors for review.
`competition_intensity`, `local_pressure`	Nearby competitor count and cheaper-station pressure in sector.	Estimate short-term pressure on outlier prices.

New Market Intelligence Outputs

output/brand_positioning_stats.csv: learned brand pricing and update behavior.
output/postcode_sector_stats.csv: postcode-sector market structure metrics.
output/brand_positioning.png: brand strategy scatter plot.
output/postcode_sector_map.png: postcode-sector geospatial intelligence view.

Suggested Operating Rules

Act when change_probability >= 0.70.
Require uncertainty width (upper - lower) <= 0.20.
Escalate all anomaly_level == "high" rows.
Review diesel_cheaper_anomaly == 1 within the same day.

ROI Calculator (Scenario Estimate)

This is a planning estimate, not a guaranteed outcome.

Vehicles

Liters per vehicle per day

Price edge (pence per liter)

Operating days per year

Estimated annual savings: GBP 0.00

annual_savings_gbp = vehicles * liters_per_vehicle_per_day * (price_edge_pence_per_liter / 100.0) * operating_days_per_year

How To Run

cd hetzner_deploy/js_labs/ukfuel_detective
python3 -m py_compile fuel_detective.py
python3 fuel_detective.py

Outputs are written to ukfuel_detective/output/, including fuel_detective_report.html, brand_positioning.png, and postcode_sector_map.png.

Known Limits

No direct causal estimate for why a station will move.
Label design is recency-based, not explicit future delta labeling.
External market shocks are not modeled directly.
Upstream data quality can still affect outputs.