I’m building OpenTrace ML, an open-source Python and Go toolkit for developers experimenting with traffic forecasting, road observations, and GPS/map workflows.
In simple terms: it helps you turn a road-damage observation into something you can place on a map, compare models that predict traffic counts, and move a trained linear forecasting model from Python into Go.
Status checked October 7, 2026: main is at a2cdb42. The capabilities below are already merged; this article refresh is not a new software release. The project remains pre-alpha.
Repository · Contributor guide · Discussions
1. Compare traffic forecasts before choosing a model
OpenTrace ML includes persistence, daily seasonal-naive, incremental linear, and CPU neural forecasting models. The neural model is a small scikit-learn multilayer perceptron that uses recent traffic counts and calendar features. Input and target scaling are learned from training data only.
A useful first project is a notebook that compares all four models on the same chronological folds and plots error by forecast lead. Rolling backtests validate timestamp alignment and reject duplicates, gaps, and invalid targets.
Start with the repository’s original synthetic data, which needs no external dataset download:
git clone https://github.com/vrajpatell/opentrace-ml.git
cd opentrace-ml
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
python examples/benchmark_traffic_models.py --synthetic-demo
On Windows PowerShell, activate the environment with .venv\Scripts\Activate.ps1 instead.
To use your own hourly CSV with date_time and traffic_volume columns:
import pandas as pd
from opentrace_ml import NeuralTrafficForecaster
from opentrace_ml.datasets import select_hourly_traffic_window
raw = pd.read_csv("traffic.csv", parse_dates=["date_time"])
frame = select_hourly_traffic_window(raw, samples=720)
model = NeuralTrafficForecaster(lags=24, random_state=42)
model.fit_frame(frame)
forecast = model.forecast(
frame["date_time"].iloc[-1] + pd.Timedelta(hours=1),
periods=24,
)
print(forecast)
This example needs 720 consecutive hourly observations. The window helper collapses agreeing duplicate readings, rejects conflicting ones, and never fills gaps. Output columns are timestamp and predicted_traffic_volume. Neural learning is batch-based: fit again to learn new data. Forecasts are traffic counts for one series, not travel-time or ETA predictions.
2. Train a linear model in Python and forecast in Go
Python handles training; a data-only JSON snapshot carries the scaler, linear coefficients, intercept, and lag history to the native Go execution core.
From the repository root, with a supported Go toolchain installed:
python examples/export_traffic_model.py --synthetic-demo --output /tmp/opentrace-traffic.json
(cd go && go run ./examples/forecast /tmp/opentrace-traffic.json \
2026-09-04T00:00:00Z 2026-09-04T01:00:00Z)
This is linear-model inference. Neural export and Go neural inference are still open work. See the portable inference guide for the contract and parity tests.
3. Turn road observations into a map layer
The library can parse Pascal VOC road-damage annotations, adapt callable detectors, interpolate detections onto a timestamped GPS trace, and export GeoJSON. A small offline example uses an original annotation fixture:
python examples/road_damage_route_demo.py tests/fixtures/rdd_sample.xml
You could build a survey-layer viewer or an evaluation report with per-class precision, recall, F1, and TP/FP/FN counts. The library supplies the components; you supply your application and any appropriately licensed detector or data.
4. Experiment with private trace preparation and map matching
GPX preparation requires explicit consent, pseudonymizes trip IDs, and cleans samples. An engine-independent map-matching contract represents matched and unmatched observations. Route scoring combines damage, congestion, uncertainty, and distance signals.
These are experimental building blocks. A trip pseudonym does not make location data anonymous. The aggregation/export gate is still open work. OpenTrace does not automatically edit OpenStreetMap, and road-damage detections are not an authorized source for OSM edits.
What the benchmark actually says
The documented initial experiment used one September 2018 window from the UCI Metro Interstate Traffic Volume dataset: 720 hours, 480 initial training hours, and ten 24-hour test folds.
| Model | MAE, traffic counts | MAPE |
|---|---|---|
| Persistence | 2276.82 | 107.57% |
| Seasonal, 24 steps | 543.00 | 26.35% |
| Online linear | 3308.64 | 99.99% |
| Neural MLP | 470.01 | 33.05% |
These are recorded historical results, not a fresh benchmark run. All ten neural fits reached the iteration cap. The seasonal baseline had lower percentage error, and the online model needs investigation. One window does not establish general accuracy; the synthetic demo only demonstrates execution.
The source code is Apache-2.0. External datasets, maps, and weights keep their own licenses and attribution requirements; see DATA_LICENSES.md. There is no bundled pretrained detector, production map matcher, hosted API, or complete routing service.
Choose a small contribution
- ML evaluation: propose two additional evaluation windows and check continuity before tuning models — #20.
- Streaming ML: reproduce and investigate online scaling/underfitting — #21.
- Go and neural networks: propose a versioned, data-only neural export contract — #22.
- GIS: add a tiny offline OSM fixture with provenance — #3.
- Computer vision: build an optional RTMDet adapter — #4.
- GPS and privacy: help with recording-gap segmentation #8 or reviewed aggregation #10.
A reproducible bug report, a clear example, or a focused documentation improvement is a useful contribution. Comment on an issue with your proposed scope before starting.
What would make this useful in your work: a forecast-comparison notebook, a Python/Go integration, or a road-observation map? What would you need to trust its results?
Disclosure: This article was prepared with AI assistance and checked against the repository documentation.
Top comments (0)