motac

Road-constrained spatio-temporal Hawkes processes for event forecasting on road networks.

Getting started

• Installation
  • Requirements
  • Install
• Model overview
  • Substrate (road constraints)
  • Hawkes intensity (discrete time)
  • Count likelihood
  • Simulation and observation noise
  • Forecasting and evaluation
• Parameter recovery (road Hawkes)
  • What is tested
  • Model recap (recovery target)
  • Running locally
  • Notes on tolerances
• Likelihood and inference
  • Intensity recap
  • Poisson likelihood
  • Negative Binomial likelihood (NB2)
  • Maximum likelihood estimation
  • Regularization and stability guardrails
  • Smooth speed-of-movement gate
  • Practical notes
• Backtesting and benchmarks
  • Rolling-origin protocol
  • Probabilistic forecasts
  • Metrics
  • Baselines
  • Reproducible artifacts
• Loaders
  • Chicago events via canonical loader
  • ACLED events via canonical loader

Tutorials

• Tutorial: Synthetic quickstart (detailed)
  • 2. Simulate a synthetic world
  • 3. Visualize the synthetic data
  • 4. Connect locations to a regular grid
  • 5. Model definition and math
  • 6. Fit the Hawkes model
  • 7. Reconstruct intensities on the training window
  • 8. Forecast the future and evaluate accuracy
• Tutorial: POI features (baseline)
  • What you get
  • Configuration knobs (SubstrateConfig)
  • Example JSON config
  • Inspecting feature names
  • Related reference
• End-to-end: ingest → spatial join → query
  • 1) Raw input: newline-delimited JSON (JSONL)
  • 2) Ingest to the canonical Arrow table (and optionally write Parquet)
  • 3) Build a regular grid and assign cell_id
  • 4) Query: filter and aggregate
• Worked example: Chicago backtest (committed fixture)
• Worked example: Gaza ACLED backtest (local cache)

API reference

• Schema
  • Dataset
  • Event
  • EventRecord
  • EventTable
  • validate_event_record()
  • validate_event_table()
• Substrate
  • Building
  • Cache artefacts
  • POI features
  • API reference
• Model API
  • Core road-Hawkes API
  • Stability diagnostics
  • Marked Hawkes scaffolding
• Neural kernels API
  • Contract validation helper
• Evaluation
  • BacktestResult
  • backtest_fit_forecast_nll()
  • BacktestConfig
  • run_backtest_report()
  • BenchmarkSuiteConfig
  • run_benchmark_suite()
  • ProfileResult
  • profile_fit_forecast()
  • EvalConfig
  • evaluate_synthetic()
  • BacktestResult
  • backtest_fit_forecast_nll()
  • ProfileResult
  • profile_fit_forecast()
• Command line interface
  • main()

Project

• Architecture
• Contributing