# User Guide

This chapter walks through the plugin tab by tab, explaining what every button and field does. It assumes you’ve already installed OMRAT (Installation) and opened the dock widget (Quickstart).

Need a term defined? See Concepts. Need a specific workflow (“I have AIS data, how do I …”)? See Workflows.

## The dock widget

OMRAT’s entire UI lives in one dockable widget. The top of the widget has a menu bar (File, Settings, View) and the main area has a stack of tabs:

The dock widget. Menu at top, tabs in the middle, progress and messages at the bottom.

The workflow is to fill tabs left-to-right, then press Run Model on the Results tab. You can come back and tweak any tab and rerun.

## Route tab

The Route tab lists every leg of the shipping route.

A route is a polyline split into one or more segments (legs). Each segment has:

- Start_Point / End_Point – lon/lat of the two endpoints.

- Width – the lateral extent (metres) used to draw the corridor marker on the map. This is visualisation only; the actual lateral spread used in the calculation comes from the Distributions tab.

- Dirs – the two direction labels auto-derived from the segment’s compass bearing (`"North going"` / `"South going"`, etc.).

- bearing – stored compass bearing in degrees.

- ai1, ai2 – IWRAP “position check interval” in seconds for directions 1 and 2. Used by the powered-grounding / allision calculations (\(N_{II} = P_c Q \cdot m \cdot \exp(-d/(a_i V))\)).

### Digitising a route

1. Click Add Route to start digitising.

2. Click on the map to set the first waypoint.

3. Click again to create a leg; each subsequent click adds a segment.

4. Click Stop Route when done.

Segments are automatically assigned an ID (`1`, `2`, …) and a default width of 5000 m.

### Editing a segment

Select a segment in the route table and edit its geometry directly on the map using QGIS’s standard vertex-editing tools. OMRAT listens to the geometry-change signal and:

- Updates the Start_Point / End_Point values in the table,

- Recomputes direction labels and stored `bearing`,

- Recomputes `line_length` (metres) via UTM projection.

The recomputed values are included in project save and in IWRAP XML export, so map geometry and exported model stay in sync.

### Junctions, crossings and merging

Crossing and merging collisions arise wherever two or more legs meet or cross. OMRAT models the meeting point as a junction carrying a transition matrix that says how traffic from each inbound leg splits across the outbound legs. There is no separate “add crossing” action in the UI:

- Snap two leg endpoints together (or share a common waypoint when digitising) and OMRAT registers a junction automatically on save.

- Legs that cross in the middle (true X intersections, no shared endpoint) are detected when you click Update all distributions; you’ll be prompted to split each crossing into four sub-legs that meet at a new junction. Splitting also offers to copy the parent legs’ traffic onto the sub-legs.

- Open Settings -> Junction transition matrix… to inspect or edit how traffic distributes at each junction. Rows default from geometry (deflection-angle heuristic) and are overwritten by AIS counts when a database is connected; user edits stick.

See Junctions and the transition matrix for the math and the AIS-vs-geometry-vs-user hierarchy.

### Saving the route

The on-canvas leg layers in the QGIS Layers panel are memory layers and disappear when you close QGIS. The persistent source of truth is the project file: File -> Save .omrat writes the route (start / end / width / dirs / bearing) plus traffic / depths / objects / distributions to a single JSON file. File -> Open .omrat rebuilds the leg layers from that JSON, so there is no separate “save layer” step.

### What flows downstream

Field | Used by
--- | ---
`Start_Point` / `End_Point` | Every accident type (leg geometry).
`line_length` | Drifting base exposure, ship-ship collision candidate count.
`ai1`, `ai2` | Powered grounding + allision (\(\exp(-d/(a_i V))\)).
`bearing` | Crossing-collision geometry to detect leg pairs that share a waypoint.

## Traffic tab

The Traffic tab. Matrix rows are ship types, columns are LOA (length) bins.

Every segment, in every direction, has its own traffic matrix. Select a segment and direction using the dropdowns at the top, then pick a variable (Frequency, Speed, Draught, Height, Beam) to edit.

### Matrix shape

- Rows – ship types (configurable under Settings -> Ship Categories; defaults to the 21 IMO types used by IWRAP).

- Columns – LOA bins (also configurable; defaults to 15 bins from <50 m to >350 m).

### Variables

Variable | Units | Used by
--- | --- | ---
Frequency (ships/year) | ships/year | Every accident type (exposure).
Speed (knots) | knots | Powered grounding/allision, head-on + overtaking + crossing collisions, drifting exposure.
Draught (meters) | m | Powered grounding depth binning, drifting grounding filter.
Ship heights (meters) | m | Powered allision (clearance check: short ships pass under high structures).
Ship Beam (meters) | m | Ship-ship collision geometry.
Scaling (%) | percent | Per-cell frequency multiplier applied just before risk integration. `100` = no scaling (default). See Scaling traffic up or down below.

### Scaling traffic up or down

The Traffic tab has an easy option for bumping all (or some) of the traffic up or down by a percentage – useful for “what if the forecast goes up 30 %?” sensitivities without editing every cell.

All scaling controls live in a Traffic scaling group box to the left of the matrix. The box is collapsible and starts collapsed so the matrix gets the full width on first open – tick its title checkbox to expand the controls, untick again to fold them away.

- Global scaling [%] spinbox inside the group is the master multiplier. `130` means every ticked ship-type row gets its Scaling (%) cells set to 130, so \(Q_{effective} = Q \cdot 1.30\) for those rows.

- Follow global per ship type is the list of checkboxes below the spinbox – one per ship type. Tick (default) = “follow the global”; untick = “leave this row’s values alone”. Use it to exclude e.g. passenger traffic from a cargo-forecast bump.

- Switch the variable dropdown to `Scaling (%)` to see and edit the per-cell values directly. Typing a value into a cell auto-unticks that ship-type row – the typed number is treated as your explicit override and survives future global changes.

- Reset all to 100 % clears every override: all checkboxes re-tick, the global snaps to `100`, every cell goes back to `100`.

The scaling matrix is per-leg / per-direction, but the global broadcast covers every leg + direction at once. AIS refresh and IWRAP import only overwrite Frequency – never Scaling – so a saved `+30 %` survives every traffic update.

### Importing from AIS

If you have access to an AIS database:

1. Settings -> AIS connection settings – enter host, port, database, schema, user, password.

2. Select a segment in the route table.

3. Click Update AIS. The plugin queries the database for every vessel passage that crossed the segment’s buffer and populates the traffic table automatically.

The query time is shown in the QGIS log panel.

Note

No AIS database yet? See Database setup and AIS ingestion for the end-to-end guide: standing up the PostGIS schema, ingesting raw NMEA / CSV files through the Database setup wizard, and verifying the tables before clicking Update AIS in OMRAT.

## Depths tab

The Depths tab. One row per depth polygon.

Each row has:

- id – a short label (auto-generated `d1` … or user-set).

- depth – the water depth at this polygon (metres below chart datum).

- Polygon – the WKT geometry, in lon/lat (EPSG:4326).

### Adding depths

Three ways:

- Add Simple Depth – enter a depth value, draw a polygon on the map.

- Load Depth – pick a shapefile; OMRAT imports every polygon and uses the `depth` attribute (or the first numeric attribute) as the depth value.

- Get GEBCO Depths – requires an OpenTopography API key in Settings. The plugin downloads GEBCO bathymetry for the project bbox + padding and vectorises it into depth polygons at the depths you specify.

### How depths drive the calculation

- Drifting grounding: a polygon’s depth is compared against each ship’s draught. Only polygons shallower than the ship’s draught are grounding hazards for that ship.

- Drifting anchoring: a polygon is an anchoring zone if its depth is less than `anchor_d * draught` (configurable under Drift settings).

- Powered grounding: the shallowest depth encountered along a ray cast from the leg’s bend gives the grounding contribution (\(N_{II} = P_c Q m \exp(-d/(a_i V))\)).

## Objects tab

The Objects tab. One row per structure.

Structures are bridges, wind-turbine foundations, platforms, piers. Each row has:

- id – label.

- height – height of the structure above waterline (metres). Ships shorter than this pass under without colliding.

- Polygon – the WKT footprint.

### Adding structures

- Add Simple Object – enter a height, draw a polygon on the map.

- Load Object – pick a shapefile with a `height` attribute.

### How objects drive the calculation

- Drifting allision: any ship that drifts into the polygon contributes, regardless of height. There is deliberately no clearance check – a drifting ship has no propulsion and cannot steer away from a structure, so it will impact something on its drift trajectory whether or not its superstructure clears the deck of a bridge. If you want every passing ship counted against an object (e.g. wind-turbine foundations, bridge piers), simply set the object’s `height` to `0`.

- Powered allision: `ship_height < object_height` passes under (no collision) – the powered ship is assumed to clear the structure’s deck. Otherwise the standard Cat II probability formula applies. Set `object_height = 0` to disable the clearance check and count every powered ship as well (typical for wind farms and full-height piers).

## Distributions tab

The Distributions tab. Two directions per segment; each direction can have up to three Gaussians plus a uniform component.

Per segment, per direction, you can define the lateral traffic distribution – the PDF of where ships are positioned relative to the leg centerline.

### Fields

Control | Meaning
--- | ---
`mean{d}_{i}` | Mean of normal component `i` (direction `d`), metres.
`std{d}_{i}` | Standard deviation of normal component `i`.
`weight{d}_{i}` | Weight of normal component `i` (weights normalised to 1).
`u_min{d}` / `u_max{d}` | Uniform component bounds, metres.
`u_p{d}` | Weight of the uniform component.

The plot at the bottom of the tab shows the combined PDF with the sum of (up to 3) normals + 1 uniform.

### Why this matters

The lateral distribution enters the calculations in three places:

1. Powered grounding / allision – defines the “lateral spread” of rays cast across the leg (\(N_\mathrm{rays} = 500\) rays at `mean +/- 4 std`).

2. Ship-ship collisions – defines \((\mu, \sigma)\) of each direction for the Gaussian-overlap probability.

3. Drifting – defines the corridor width (`5 * sigma`) and feeds the analytical probability-hole integral.

A segment with zero weights produces zero ship-ship collisions on that direction pair, and a zero-width corridor for drifting – both silent failures. Always check the plot.

## Drift Analysis tab

The Drift Analysis tab produces a visual drift-corridor layer.

This tab does not compute the risk – it draws drift corridors for visual inspection. Use it to sanity-check whether the corridors actually reach the obstacles you expect them to hit.

### Fields

- Depth threshold – hide depth polygons shallower than this (so the corridor isn’t cluttered by the near-shore bathymetry).

- Height threshold – same for structures.

- Run Drift Analysis – kicks off `DriftCorridorTask` in a background thread.

### Output

Per leg, per wind-rose direction, a polygon layer is added to the map showing where a drifting ship from that leg in that direction could reach, minus the footprints of any obstacles it would ground or collide on.

Drift corridors around a leg, coloured by direction. The darker regions are where the ship has already grounded on a shallower polygon closer to the leg.

## Run Analysis tab (Results)

Note

This is the tab labelled Run Analysis in the dock widget. The heading “Results” is the historic name and is still used in some reference material – they are the same tab.

The Results tab.

Clicking Run Model kicks off a `CalculationTask` that runs all four risk models in sequence. The task runs in the background so QGIS stays responsive.

### Result fields

All values are annual accident frequencies (expected events per year). They appear in scientific notation (`1.148e-01` means 0.1148 events/year or roughly one event every 9 years).

Field | Meaning
--- | ---
LEPDriftAllision | Drifting + hitting a structure.
LEPDriftingGrounding | Drifting + running aground on a depth polygon.
LEPPoweredGrounding | Under power, failing to turn, hitting a depth polygon.
LEPPoweredAllision | Under power, failing to turn, hitting a structure.
LEPHeadOnCollision | Two ships on the same leg in opposite directions.
LEPOvertakingCollision | Same leg, same direction, different speeds.
LEPCrossingCollision | Two legs that share a waypoint at a non-trivial angle.
LEPMergingCollision | Ship fails to turn at a bend on the same leg.

The View button next to each field opens a drill-down dialog with per-segment and per-obstacle contributions. These are useful for locating the single obstacle that dominates the total risk.

## Settings menu

Settings are split across four sub-dialogs accessed from the Settings menu.

### Drift settings

Drift settings dialog.

Field | Meaning
--- | ---
`drift_p` | Blackout rate per ship-year (default 1.0). Multiplied by a per-type override from `blackout_by_ship_type` – e.g. RoRo = 0.1.
`anchor_p` | Probability of a successful anchor given the ship is in an anchoring-depth region (default 0.7).
`anchor_d` | Anchor-depth factor. A ship with draught \(T\) can anchor in water shallower than \(\mathrm{anchor\_d} \cdot T\).
`speed` | Drift speed in knots.
Wind rose | Probability per compass direction. Eight values that must sum to 1.
Repair time | Lognormal / Weibull / Normal CDF parameters for the time-to-repair distribution used to compute \(P_{NR}\).

### Causation factors

Default values come from Fujii (1974), Pedersen (1995), and the IALA IWRAP manual. See Theory (what is calculated) for the reference table.

### Ship Categories

Edit the type names (rows of the traffic matrix) and the LOA bins (columns). Changing these rebuilds the Traffic tab matrix.

### AIS connection

Connection parameters for an AIS PostgreSQL/PostGIS database. Values are stored in the project file; the password is stored in plain text, so treat `.omrat` files as sensitive if you fill this in.

This dialog only stores credentials. To stand up the database itself, ingest raw AIS files, and verify that segments are queryable, see Database setup and AIS ingestion.

## File menu

- Save / Load – writes / reads the project as a single JSON file with extension `.omrat`. Every tab’s contents is included. See .omrat data format for the full schema.

- Export to IWRAP XML / Import from IWRAP XML – exchange with the IALA IWRAP reference tool. Useful for cross-validating OMRAT results against IWRAP on the same project.

## Run history (Previous runs)

OMRAT keeps a history of every Run Model invocation in two places:

- one per-run GeoPackage in the output folder you select, named `<model_name>_<YYYYMMDD_HHMMSS>.gpkg`, holding the actual spatial result layers for that run.

- one lightweight metadata row in the master history database (`omrat_history.sqlite` under the user app-data folder) holding the run name, timestamp, elapsed duration, every total probability, and a pointer (`output_dir` + `output_filename`) to the per-run file.

This split keeps the master DB small even after many runs, and gives you one easy-to-archive `.gpkg` per run.

The master database location:

- Windows: `%APPDATA%\\OMRAT\\omrat_history.sqlite`.

- Linux: `~/.local/share/OMRAT/omrat_history.sqlite`.

- macOS: `~/Library/Application Support/OMRAT/omrat_history.sqlite`.

### Output folder + Run Model gating

Run Model is disabled until you select an output folder. Use the File path `...` button on the Run Analysis tab to pick one – the chosen path is remembered between sessions. Once a valid folder is selected, Run Model becomes available.

### Naming a run

The Name of the model field on the Run Analysis tab becomes the run’s name AND the per-run GeoPackage’s filename prefix. Leave it blank and OMRAT auto-names the run `run_<YYYYMMDD>_<HHMMSS>` based on the start time.

Note: result layers are no longer auto-added to the QGIS canvas at the end of a run. Use Add selected run results to map (see below) when you want to look at them.

### The Previous runs table

The Previous runs table on the Run Analysis tab shows three columns: Name, Date, Duration – enough to pick a run without scrolling. Click a row (or several rows) and the result fields below the table fill in:

- Single selection – each result LineEdit shows that run’s total probability, e.g. `1.140e-01`.

- Multi-selection – the LineEdits become side-by-side comparisons of the form `1.140e-01 | 1.252e-01 (Δ+9.8%) | 0.992e-01 (Δ-13.0%)`. The first selected run is the baseline; each subsequent run carries its relative difference (`Δ` percentage) to that baseline.

Below the table is an Add selected run results to map button. Click it with a single row selected to load that run’s per-run GeoPackage as new layers in the QGIS Layers panel, styled graduated red->green like the live-run output. Multiple selection disables this button – pick one run at a time when loading on the canvas.

The right-click context menu on the table provides:

- Add results to map – same as the button (single selection only).

- Delete from history – removes only the row from the master DB; the per-run `.gpkg` file stays on disk so you can keep archived results around if you want.

- Delete from history + remove .gpkg file – removes both. Asks for confirmation.

You can also reach the table via File -> Manage previous runs…, which switches to the Run Analysis tab and refreshes the table.

### Result-layer attributes

After a run finishes, six new layers (when applicable) appear on the canvas:

Layer | Geometry | Key attributes
--- | --- | ---
Drifting Allision Results | Polygon | `obstacle_id`, `total_edge_probability` (alias Total edge probability), `object_probability` (alias Object probability), plus per-segment columns and a `leg_<id>` column per leg that contributed.
Drifting Grounding Results | Polygon | same shape as Allision.
Powered Allision Results | Line (per leg) | `segment_id`, `total_edge_probability` (powered-allision probability summed across every contributing structure for this leg), `value_max` (max structure height on this leg), one `obs_<id>` column per contributing structure.
Powered Grounding Results | Line (per leg) | `segment_id`, `total_edge_probability` (powered-grounding probability summed across every contributing depth contour for this leg), `value_max` (max depth on this leg), one `obs_<id>` column per contributing depth.
Ship-Ship Collision (per leg) | Line | `leg_id`, `head_on`, `overtaking`, `combined`.
Ship-Ship Collision (waypoints) | Point | `waypoint`, `crossing`, `bend`, `combined`.

All layers are graduated red->green by `total_edge_probability` / `combined`. The line layer is rendered semi-transparent and ~3 mm wide so the underlying route stays visible.

## Tips and best practices

- Start with default causation factors. Only adjust if you have local accident data to support different values.

- Check the distribution plot on every segment before you trust a result. A zero-weight distribution silently zeroes that segment’s contribution for some accident types.

- Use Drift Analysis before Run Model on a new project – if corridors don’t reach the obstacles you care about, your result will be near zero and you’ll waste time investigating why.

- Result layers colour-code by contribution. Red polygons are your “risk hotspots” and usually the right place to look if the total seems implausibly high.

- Keep your repair-time distribution realistic. If it says 90 % of blackouts are repaired in 10 minutes, grounding risk will be near zero regardless of traffic.

- Save often. The full result (including the debug-trace breakdown per obstacle, if enabled) is serialised with File -> Save, so a finished run is reproducible.