# OMRAT – Open Maritime Risk Analysis Tool

OMRAT is a QGIS plugin that calculates how often ships in a waterway are expected to run aground, collide with structures, or collide with each other. It implements the IWRAP methodology (Friis-Hansen 2008, Pedersen 1995) as an open-source tool, so the result is comparable with the IALA reference implementation but everything happens inside QGIS.

Given a shipping route, traffic volume per ship type, a bathymetry layer, and a list of structures, OMRAT returns expected accidents per year for each of the main accident types:

- Drifting grounding / allision / anchoring – ships that lose propulsion and drift into shallow water, a structure, or anchor successfully.

- Powered grounding / allision – ships under power that fail to turn at a bend and continue straight into an obstacle.

- Ship-ship collisions – head-on, overtaking, crossing, and bend collisions.

## Three ways to read this documentation

Pick the path that fits what you’re trying to do.

I want to… | Read
--- | ---
run OMRAT for the first time on the supplied example project | Quickstart
set up an AIS database so OMRAT can pull traffic for legs | Database setup and AIS ingestion
learn what each tab of the plugin does | User Guide
understand what the risk numbers mean | Theory (what is calculated), then Drifting Risk Calculations / Ship-Ship Collision Calculations / Powered Grounding and Allision
understand how the calculation is implemented (function by function, call tree) | Code Flow: From “Run Model” to Results, then the per-accident chapters Code Flow: Drifting Model / Code Flow: Ship-Ship Collision Model / Code Flow: Powered Grounding & Allision (Cat II)
look up a specific field in the `.omrat` JSON file or the `data` dict passed to the calculation | .omrat data format

## The two-track philosophy

Every accident type has two chapters:

- A theory chapter (Track 1) explaining what the calculation measures, deriving the formulas, and listing the assumptions. Read this if you’re an analyst interpreting a result or comparing against IWRAP.

- A code-flow chapter (Track 2) walking the actual function calls that happen when Run Model is pressed. Read this if you’re a developer tracing an output back to the code that produced it, or extending / reviewing the calculation.

The two tracks deliberately overlap so you can start reading in one and cross over to the other without getting lost.

## Contents

Getting Started

- Project Overview
  - What OMRAT does
  - Who OMRAT is for
  - The methodology in one paragraph
  - Background and funding
  - What’s next
- Installation
  - Prerequisites
  - Installing the Plugin (recommended)
  - Manual dependency install (fallback)
  - Verifying the Installation
- Database setup and AIS ingestion
  - Architecture in one paragraph
  - 1. Stand up the database
  - 2. Install OMRAT’s Python dependencies
  - Supported AIS file formats
  - 3. Walk the wizard
  - 4. Verify with a smoke test
  - 5. Run risk analysis as before
  - Database schema reference
  - Static + state row deduplication
  - ETA combination
  - Incremental ingestion (re-runs are cheap)
  - Index strategy: build after bulk load
  - Threshold tuning
  - Operational notes
  - Troubleshooting
- Quickstart
  - Before you start
  - 1. Open the plugin
  - 2. Load the example project
  - 3. Sanity-check each tab (30 seconds)
  - 4. Run the model
  - 5. Inspect the map result layers
  - 6. Where to read next
  - Troubleshooting
- Quickstart - from scratch
  - 1. Open the plugin (no project loaded)
  - 2. Place legs on the map
  - 3. Bring in depth data
  - 4. Define obstacles (objects)
  - 5. Settings: drift, ship categories, causation, AIS
  - 6. Run the model
  - 7. Inspect the results

Using OMRAT

- Concepts
  - Route, segment, leg
  - Direction
  - Traffic cell
  - Wind rose
  - Drift corridor
  - Obstacle shadow
  - Probability hole (\(h_X\))
  - Repair-time distribution and \(P_{NR}\)
  - Anchoring
  - Causation factor
  - Category I vs Category II (powered)
  - Lateral distribution
  - Standard nautical compass convention
  - The `data` dict
  - Run Model vs Run Analysis
- User Guide
  - The dock widget
  - Route tab
  - Traffic tab
  - Depths tab
  - Objects tab
  - Distributions tab
  - Drift Analysis tab
  - Results tab
  - Settings menu
  - File menu
  - Run history (Previous runs)
  - Tips and best practices
- Workflows
  - Build a project from scratch (no AIS)
  - Build a project from AIS
  - Import an existing IWRAP XML
  - Export for use in IWRAP
  - Inspect the dominant obstacle on a risk number
  - Debug why a number looks wrong
  - Speed up a slow calculation
  - Reproduce an old result
  - Run a calculation without the QGIS UI (headless)
  - Compare two result sets

Theory (what is calculated)

- Theory (what is calculated)
  - The IWRAP framework in one equation
  - Default causation factors
  - Lateral traffic distribution
  - Coordinate systems
  - Compass convention
  - References
- Drifting Risk Calculations
  - Overview of the Drifting Model
  - `run analysis` vs `run model`
  - Common Parameters Used in the Examples
  - Exposure Base
  - Repair Time and \(P_{NR}\)
  - The Probability “Hole” \(h_X\)
  - Directional Distance to an Obstacle
  - Level 1 — Single Polygon, Single Ship, Single Leg
  - Level 1b — Distance from the Leg Centreline vs the Distribution Centre
  - Level 2 — Two Legs, Multiple Ship Categories
  - Level 3 — Blocking Polygon (Shadow Coverage)
  - Level 4 — Anchoring
  - Level 5 — Complete Cascade
  - Shadow Algorithm (Quad-Sweep)
  - Drift Corridor Visualisation (`run analysis` only)
  - Pipeline and Source Code Pointers
  - Summary
- Ship-Ship Collision Calculations
  - Overview
  - Head-On Collisions
  - Overtaking Collisions
  - Crossing Collisions
  - Bend Collisions
  - Calculation Workflow
  - Summary of Equations
- Powered Grounding and Allision
  - Overview
  - Category I: Direct Overlap
  - Category II: Missed Turn at Bend
  - Shadow-Aware Ray Casting
  - Draft Filtering for Grounding
  - Computation Pipeline
  - Visualization
  - Combined Powered Risk
  - Comparison with Drifting Risk
  - Causation Factor Summary
- Junctions and the transition matrix
  - How a transition matrix changes the calculation
  - Validating routes before computing
  - Editing a matrix manually
  - JSON layout
  - Behind the scenes
- Oil-spill consequence – catastrophe rates
  - At a glance
  - The four input dialogs
  - Worked example
  - Headless validation
  - Behind the scenes
  - Limitations and TODOs

Code Flow (how it is calculated)

- Code Flow: From “Run Model” to Results
  - Reading map
  - Entry point: the “Run Model” button
  - Background orchestration: `CalculationTask`
  - Where the inputs come from
  - The `Calculation` facade
  - Completion and UI fan-out
- Code Flow: Drifting Model
  - Entry point
  - Top-level call tree
  - `_build_transformed()`: lat/lon -> UTM
  - `_compute_reach_distance()`
  - Depth merging (optional)
  - Phase 1: `_precompute_spatial()` (`spatial`, 0–40 %)
  - Phase 2: `_precompute_shadow_layer()` (`shadow`, 0–50 %)
  - Phase 3: `_precompute_bucket_memo()` (`shadow`, 50–100 %)
  - Phase 4: `_iterate_traffic_and_sum()` (`cascade`, 60–90 %)
  - Completion (`layers`, 90–100 %)
  - Function reference
  - Debug trace
- Code Flow: Ship-Ship Collision Model
  - Entry point
  - Top-level call tree
  - Data pulled from `data`
  - `run_ship_collision_model()`: orchestrator
  - Shared helpers
  - `_calc_head_on_collisions()`
  - `_calc_overtaking_collisions()`
  - `_calc_bend_collisions()`
  - `_calc_crossing_collisions()`
  - The pure-math helpers
  - Output
  - Function reference
- Code Flow: Powered Grounding & Allision (Cat II)
  - Entry points
  - Top-level call tree
  - Shared inputs
  - Projection: `SimpleProjector`
  - `run_powered_grounding_model()`
  - `run_powered_allision_model()`
  - `_build_legs_and_obstacles()`
  - `_run_all_computations()`
  - `_compute_cat2_with_shadows()`
  - `_extract_edges_local()`
  - Output: the traffic accumulation loop
  - Interactive visualiser
  - Function reference

Reference

- `.omrat` data format
  - Top-level layout
  - `pc` – causation factors
  - `drift` – drifting model parameters
  - `traffic_data` – traffic matrix per leg/direction
  - `traffic_scaling` – project-level scaling state
  - `segment_data` – per-leg geometry and parameters
  - `depths` – bathymetry polygons
  - `objects` – structure polygons
  - `ship_categories` – type + LOA bin definitions
  - Output keys (round-tripped, not inputs)
  - Optional / developer-only flags
  - Run history: master DB + per-run GeoPackages
  - Minimal valid project (synthetic)
- Code Architecture
  - Directory Structure
  - Data Flow
  - Key Classes
  - Data Structures
  - Background Task Execution
  - IWRAP Integration
  - Project Persistence
- API Reference
  - compute.basic_equations
  - compute.run_calculations
  - geometries.drift
  - geometries.calculate_probability_holes
  - geometries.result_layers
  - omrat_utils

## Indices

- Index

- Module Index

- Search Page

## Citing OMRAT

If you use OMRAT in a publication, please cite the project repository (https://github.com/axelande/OMRAT) together with the IWRAP references it implements (Friis-Hansen 2008, Pedersen 1995). A full bibliography is at the bottom of Theory (what is calculated).