Docs

Overview

Ananke reads ship position reports (AIS) and holds each one to the same ship’s earlier reports and to what its hull and the sea allow. It runs on your machine, reads your files and writes its findings to a folder you name. It opens no network connection.

A finding is about a ship or an area, not a single report: an episode is one ship from its last good position to its first good one after; an event is several unrelated ships displaced together.

Run it

anopticon-run run positions.csv --out findings/ --alpha 1e-4

Each argument before the options is a feed: a file or a folder. The findings go to the folder --out names (out/ if you leave it out). --alpha sets the alarm rate (Alarm rate).

The command, its calibration and its maps come as one folder. Run it from there.

Files

Files need not be in time order. MarineCadastre and Danish Maritime Authority exports read as they are. NMEA files and live feeds are not read yet.

Columns

MMSI, time, latitude and longitude are required. Every other column lets more checks run. CSV headers are matched without regard to case, with spaces and hyphens read as underscores.

Times: seconds, milliseconds or microseconds since 1970, ISO 8601, or day/month/year as the Danish Maritime Authority writes it. A time with no zone is read as UTC, and summary.json says so under assumed. AIS “not available” values (heading 511, course 360, speed 102.3) read as missing. Rows without an MMSI or a readable time are skipped.

Several feeds

anopticon-run run terrestrial.csv satellite.parquet --out findings/

Name several files to judge them as one picture. Each file is a feed, named after the file; a table with a source, feed or provider column becomes one feed per value. One transmission heard on two feeds is judged once, and each finding names the feeds it rests on.

Ship data

Ship type, length, beam, draught and IMO sharpen the hull checks. Put them in the position file’s columns, or pass a Parquet file with any of mmsi, ship_type, length_m, beam_m, max_draught, imo_number:

anopticon-run run positions.csv --static ships.parquet --out findings/

What a run writes

Each line is one JSON object with "schema": "ananke/1". A finding is written again when it changes: keep the line with the highest revision for each id.

How sure

Reports with nothing found make no output. Reports that cannot be judged are set aside before any check and counted in summary.json (Set aside).

Episodes

{
  "schema": "ananke/1",
  "kind": "episode",
  "id": "ep_231",
  "revision": 1,
  "state": "closed",
  "engine": "0.1.0",
  "calibration": "cal-2026.11.0",
  "mmsi": 273000000,
  "imo": null,
  "status": "proven",
  "basis": "physics",
  "urgency": "immediate",
  "category": "position_falsified",
  "cause": "self_spoofing",
  "event_id": null,
  "since": "2026-10-20T09:31:25Z",
  "until": "2026-10-20T09:43:25Z",
  "last_good_fix": {
    "time": "2026-10-20T09:22:23Z",
    "lat": 61.09597,
    "lon": 28.94465
  },
  "first_good_fix_after": {
    "time": "2026-10-20T10:13:22Z",
    "lat": 60.00923,
    "lon": 28.47036
  },
  "false_positions": {
    "count": 3,
    "area": {
      "lat": 60.3716,
      "lon": 28.6286,
      "radius_km": 82.4
    }
  },
  "proof": [
    {
      "producer": "simultaneous_presence",
      "basis": "physics",
      "kind": "unreachable_step",
      "metres": 123572.6,
      "seconds": 541.6,
      "knots": 443.5,
      "limit_knots": 50.0
    }
  ],
  "evidence": [
    {
      "check": "dr_envelope",
      "reports": 2
    }
  ],
  "min_p": 0.0000584,
  "feeds": [
    "digitraffic"
  ],
  "coverage": {
    "reports": 8,
    "flagged": 3,
    "proven": 1
  },
  "persistent_offender": false,
  "summary": "Reported positions no hull could reach (3 of 8 reports), around 60.372, 28.629, 82 km from its last good fix, reached at 444 kn against a limit of 50 kn, from 09:31 UTC to 09:43 UTC."
}

Proofs

Each proof carries the numbers to check it by hand: metres, seconds, knots (the speed the reports imply), limit_knots (the fastest the hull can go) and inland_m (distance from any water), whichever apply. producer names the check that made it.

Causes

An episode first sent with one cause can be sent again with another as more reports arrive: a number later found shared is re-sent as shared_mmsi.

Events

{
  "schema": "ananke/1",
  "kind": "event",
  "id": "ev_577",
  "revision": 12,
  "state": "open",
  "engine": "0.1.0",
  "calibration": "cal-2026.11.0",
  "status": "proven",
  "basis": "physics",
  "urgency": "immediate",
  "category": "position_falsified",
  "cause": "area_spoofing",
  "since": "2026-10-20T10:45:57Z",
  "until": null,
  "moved_to": {
    "lat": 54.0946,
    "lon": 38.2307,
    "radius_km": 0.6
  },
  "ships_were": {
    "lat": 55.9963,
    "lon": 34.9552,
    "radius_km": 576.4
  },
  "displacement_km_median": 0.6,
  "shared_speed_knots": 54.0,
  "ships": {
    "heard_in_area": 16,
    "in_event": 3,
    "proven": 3
  },
  "members": [
    273000001,
    273000002,
    273000003
  ],
  "summary": "3 ships (3 proven) reported positions within 1 km of 54.095, 38.231, reporting one speed no hull of theirs can make (54 kn), between 10:45 and 22:23 UTC; 16 ships were heard in the area."
}

Persistent offenders

A few ships break the ordinary motion line far more often than ships do: an odd transmitter or installation. Once a ship has shown this over enough reports it is a persistent offender. From then on its unusual motion raises no alert, since it is its normal; its proofs still stand. Its episodes say "persistent_offender": true.

{
  "schema": "ananke/1",
  "kind": "persistent_offender",
  "mmsi": 230000000,
  "since": "2026-10-20T07:14:02Z",
  "steps": 412,
  "breaches_99": 61,
  "breach_share": 0.148,
  "meaning": "this ship's own track breaks the 99 % motion line far more often than ships do; its envelope and CUSUM findings are not alerts, its proofs are"
}

steps is how many of its reports were judged, breaches_99 how many broke the line, and breach_share the share. Join the list to your own vessel records.

Set aside

Reports set aside are never judged and never prove anything. summary.json counts them by reason under stats.set_aside:

Acting on findings

Route on urgency, category and status; they are a short fixed list. Read a value you do not recognise as routine.

Alarm rate

--alpha sets how unusual a report must be to be anomalous: the chance that ordinary traffic looks at least this unusual on one judged report. Smaller is stricter: fewer alerts, fewer catches. proven ignores it.

anopticon-run run positions.csv --alpha 1e-4 --also-alpha 1e-3,1e-6 --out findings/

--also-alpha adds a row per setting to dial in summary.json: episodes, proven, anomalous, and episodes per 1,000 ship-days. To be stricter after a run, keep the anomalous episodes whose min_p is at or below the new setting. To be looser, run again.

Command line

Calibration and maps

Ananke judges with one calibration, the same for every customer; nothing you feed it changes it. Every output names it in calibration, with the engine version in engine.

Land comes from Natural Earth. Inland water, docks and harbour basins come from OpenStreetMap (© OpenStreetMap contributors, ODbL).

Status

Pre-beta. It reads CSV, TSV and Parquet files. NMEA files and live feeds are not read yet. A changed output field is a new schema version.

• Ask for a pilot