Tracking an Outbreak — Aboard a Moving Vessel

The Challenge

A vessel outbreak presents a unique epidemiological problem. Unlike a fixed-location cluster, the exposure environment itself is mobile. The index case introduces the pathogen, infects co-passengers and crew, then dies — but the ship continues its scheduled voyage, carrying an actively-spreading population from port to port. People embark and disembark at each stop, creating an ever-widening dispersal network that is both geographically scattered and temporally staggered.

The core modelling challenge is that the vessel is simultaneously an exposure environment, a movement route, and a dispersal mechanism — none of which maps cleanly to a single record type. This guide describes how to compose the workbench's data types to represent all three.

ℹ️ Assumed starting point: You already have the index case and one or more secondary cases created with their travel histories (case-movement waypoints) and clinical events (onset, death). This guide picks up from there and describes how to extend the record as the vessel continues beyond the deaths of your identified cases.

Why the vessel is not modelled as a case

It is tempting to create a "vessel" case record to serve as a persistent route tracker, but this conflates an environment with a patient. Once the vessel has no confirmed living case aboard (between the deaths of known cases and the identification of new ones), the ship is best understood as a chain of exposure events — each port call, each embarkation, each disembarkation is a discrete event with a location, time, and population at risk. This model maps cleanly to the Exposure Event system.

Data Model Approach

A shipboard outbreak decomposes into four record types working in concert:

• Health Cases — One record per identified patient. Tracks status, onset, movement waypoints, and clinical events. Does not represent the vessel itself.

• Exposure Events — Represent the vessel as a gathering, each port call as a port_stop, and each disembarkation occasion as a single vessel_disembarkation — one event covers all passengers who left at that port on that date. Set contact_count to the number of people who disembarked. Cases are then linked to this shared event as they are identified. These events anchor the vessel's journey to the map even when no individual case is actively tracked.

• Case Movements — Waypoints attached to individual cases. The vessel's route is represented indirectly by the co-located waypoints shared across all onboard cases.

• Transmission Links — Directed arcs from the index case to secondaries, and from secondaries to tertiaries where identifiable. Community cases are linked back to the relevant disembarkation event.

The vessel timeline in records

The diagram below shows how the different record types correspond to stages of a typical voyage outbreak. The vessel exposure event serves as the persistent spine — everything else is linked to it.

─── Voyage timeline ───────────────────────────────────────────────────────────

PORT A → At sea → PORT B → At sea → PORT C → At sea → PORT D

↑ ↑ ↑ ↑ Index case Index death Case 3 identified Port authority boards / onset Case 2 death via port screening notified

─── Exposure event spine ──────────────────────────────────────────────────────

[gathering] MV Vessel Name ← all onboard cases link here; contact_count = total souls

[port_stop] Port A embarkation ← index case's origin; coords = port coordinates [port_stop] Port B ← vessel position at time of index death [vessel_disembarkation] Port B dispersal ← passengers who left at Port B; contact_count [port_stop] Port C ← Case 3 identified here; anchor for route gap [vessel_disembarkation] Port C dispersal ← potential community spread [port_stop] Port D (quarantine) ← outbreak officially declared

─── Cases linked to vessel gathering ──────────────────────────────────────────

Case 1 (deceased) linked → MV Vessel + Port A port_stop Case 2 (deceased) linked → MV Vessel Case 3 linked → MV Vessel + Port C port_stop Cases 4–N linked → MV Vessel Community A linked → Port B dispersal Community B linked → Port C dispersal

Phase 1 — Model the Vessel

Before adding any cases, establish the vessel as a persistent record. This becomes the anchor that all cases, port stops, and dispersal events are linked to.

1. Create a gathering Exposure Event for the vessel — Open the Exposure Events panel (📍 in the health workbench rail) and create a new event with type Gathering. Name it after the vessel — e.g. "MV Aurora (Voyage 47)". Set the coordinates to the vessel's departure port (you can update the position as the voyage progresses, but the initial port is a useful anchor). Set Contact Count to the total souls aboard (passengers + crew) — this drives the dispersal fan proportions on the map.

2. Add a port_stop event for each port of call — For each port the vessel has visited or is scheduled to visit, create a separate Port Stop exposure event. Name it consistently — e.g. "MV Aurora — Port B (2024-03-12)". Set the coordinates to the port's lat/lon and the date to the vessel's arrival date. You do not need to link cases to port stops immediately; they are primarily positional anchors used to reconstruct the vessel's route on the map.

3. Record departure and arrival dates in the Description field — The Description field on each port stop event is the right place to record port entry/exit times, berthing location, and any port health authority notes. This information is not structured but is preserved in the full record and included in case reports.

💡 Tip: Create all the port stop events upfront, even ports where no cases have yet been identified. They serve as the vessel's route on the map — the dispersal fan layer and the timeline slider will use them to show the outbreak's geographic progression day by day.

Phase 2 — Index & Early Cases

With the vessel and port infrastructure in place, link your existing index and secondary cases to it and complete their movement histories.

Linking cases to the vessel

Open the Case Inspector for each identified case and navigate to the Exposure Events tab. Link the case to the vessel gathering event. If the case boarded at a specific port, also link them to that port's port_stop event — this establishes their origin on the voyage and gives the auto-detection engine another proximity signal for transmission link suggestions.

Movement waypoints

Use the Travel History tab in the Case Inspector to add case-movement waypoints for each case. For onboard cases, the waypoints represent the vessel's position at key dates rather than independent travel. Recommended waypoints to add:

Waypoint scoping: where to start the route history

Route waypoints model the case's movements as an infectious individual — not their complete travel biography. The system uses them for two things: contact tracing (who else was at this location during this window?) and auto-detection of transmission links (proximity scoring between cases and exposure events). Both are only meaningful from the point the case was actually shedding pathogen.

⚠️ Incubation period ≠ non-infectious period. These are two distinct concepts that are easy to conflate but epidemiologically separate: Incubation period — time from exposure to symptom onset. The person does not yet know they are infected. Pre-symptomatic infectious window — a sub-period at the end of incubation during which the person is already shedding pathogen despite having no symptoms yet. Many pathogens have this window; it is the mechanism behind silent community spread. Route waypoints must cover the pre-symptomatic infectious window even though symptoms have not yet appeared. Movements during this window are live contact tracing scope. Only the non-infectious portion of the incubation period (before shedding begins) is safe to exclude from the route.

To find the start of the infectious window, back-calculate from the confirmed onset date using the pathogen's known pre-symptomatic shedding range. For a pathogen infectious 3–4 days before symptoms, all movements from (onset date − 4 days) onward are in scope. Use the conservative end of the range (4 days rather than 3) when the exact shedding onset is unknown.

The practical scoping rule by period:

💡 Land tours during pre-symptomatic port stops are community exposure events. If the index case was on a guided tour or group excursion during their pre-symptomatic infectious window, the other participants on that tour are a potential community exposure cohort — they have since dispersed to their home countries. Model each tour as a gathering exposure event at the island coordinates, with contact_count set to the approximate tour group size. This creates the same dispersal fan and traceability infrastructure as a vessel disembarkation, and gives public health authorities a named event to reference if community cases surface later.

Presumptive exposure events

When a probable exposure can be inferred from the timeline but is not confirmed — for example, an index case who hiked in a region known for a pathogen a few days before onset — it is still worth creating the Exposure Event. Record the probable location and date as the event coordinates, and document the uncertainty explicitly in the event's description.

💡 Documenting uncertainty in a presumptive exposure event: Set the type to gathering (or the most appropriate type for the setting). In the Description field, write something like: "Presumptive exposure — inferred from incubation period back-calculation. Index case completed a hiking tour in [region] on [dates], approximately [N] days before onset. Not confirmed; timeline consistent with [pathogen] incubation range of [X–Y] days." Link the case with role Exposed. This preserves the analytical reasoning in the record without overstating certainty, and the incubation period calculation (exposure event date → onset date) is anchored in the system for later review.

The case's route begins at the start of their infectious window — calculated by subtracting the pathogen's pre-symptomatic shedding period from the onset date. Any movements before that date, including the probable source exposure itself (if it falls within the non-infectious incubation period), go in the case Notes only. Prior movements before the infectious window are present for forensic completeness but invisible to the route layer and auto-detection engine.

Clinical events

Record the full clinical timeline for each case in the Clinical Events tab: onset, any test results, hospitalisation, and death. These events are used by the route polyline colouring in the map layer — the segment between onset and death will appear in the confirmed case colour, providing immediate visual context when reviewing the outbreak map.

Transmission links

Open the Transmission Chain panel (🔗) and create directed links from the index case to identified secondary cases. Set link type to Confirmed where there is direct epidemiological evidence, or Probable where proximity and timing make direct transmission highly likely. The auto-detect job will propose additional links based on shared exposure events and geographic proximity — review these in the Transmission Chain panel and accept or rule out each suggestion.

Phase 3 — After Index Deaths

When your identified cases die, the vessel's journey does not end — the pathogen remains active in the population aboard. This is the most important phase to model carefully, because there is a period where you may have no identified living case but you know transmission is ongoing.

⚠️ Do not create a "vessel proxy" case. Creating a dummy patient record to represent the vessel's ongoing journey conflates environment with patient and will corrupt your transmission chain graph. The vessel gathering event and the port stop sequence are the correct tools for this gap.

Bridging the gap between deaths and new identifications

The port stop exposure events you created in Phase 1 serve as the vessel's positional record during periods with no identified case. They appear on the map with their own pins and are included in the dispersal fan layer, so the vessel's route remains visible even when no active case waypoints cover that period. You do not need to do anything extra here — the infrastructure already exists.

As new cases are identified through port health screening, onboard testing, or passenger reports, create new Health Case records and link them immediately to the vessel gathering event. The onset date on the new case will typically predate the identification date — set it to the best epidemiological estimate (e.g. symptom onset from the patient's own account) so the timeline slider correctly positions the case in the outbreak arc.

Adjusting status on existing cases

Ensure deceased cases are set to Deceased status, not left as Confirmed. This keeps them visible on the map (grey pins) but signals to the transmission chain engine that they are historical nodes rather than active spreaders when recalculating link weights.

            No live cases

                Vessel route visible via port stop events
                The chain of port_stop events on the map shows where the vessel has been. The dispersal fan layer renders fan lines from each port stop outward. No new records needed.

            New case found

                Create case → link to vessel gathering → set onset
                Create the new case with the best available onset date. Link it to the vessel gathering event and the nearest port stop. Add movement waypoints for the period between their onset and identification. Link back to the index case or a secondary case as the transmission source if the chain is known.

            Port screening positive

                Multiple cases found simultaneously
                Create one case per positive screen. Link all to the vessel gathering event. If you cannot establish individual transmission chains, link each new case with link type **Possible** back to the nearest prior confirmed case. Use the bulk-create approach: create each case, then use the Transmission Chain panel's auto-detect to build the initial link graph.

Phase 4 — Port Dispersal Events

Every port where passengers or crew disembark is a potential dispersal point. Even if no community cases have yet been identified, creating a dispersal event at each departure gives you a ready anchor when cases appear later, and populates the dispersal fan layer on the map immediately.

Creating a vessel_disembarkation event

One event per disembarkation occasion, not per person. All passengers and crew who left the vessel at a given port on a given date are represented by a single vessel_disembarkation event. The Contact Count field records how many people dispersed. As individuals are later identified as cases, each case is linked to this shared event — the 🌊 ratio badge (n/contact_count) then shows how many contacts you have traced. You would only create a second disembarkation event at the same port if the vessel made a return call on a different date.

1. Create the event in the Exposure Events panel — Type: Vessel Disembarkation. Name: "MV Aurora — Port B disembarkation (2024-03-12)". Coordinates: the port's lat/lon. Date: the actual disembarkation date.

2. Set Contact Count to the total number of persons who disembarked — Enter the combined total of all passengers and crew who left the vessel at this port on this date — in your island example, that is 6. If exact numbers are unavailable, use a conservative estimate. The map's dispersal fan scales the fan lines by this figure, making high-risk disembarkations visually prominent relative to smaller ones. The crew member who embarked at this stop is not included in this count — they are a new exposure risk aboard the vessel and should be linked to the corresponding port_stop event instead.

3. Link cases who disembarked at this port to this single event — As each disembarked person is identified as a case — whether immediately at the port or weeks later in the community — link them to this shared vessel_disembarkation event. You do not create a new disembarkation event for each case. One event, many case-links.

4. Add dispersal notes — Use the Dispersal Notes field to record the destination distribution of disembarking passengers if known — e.g. "approx. 60 passengers to domestic flights, 40 to port hotels, remainder local residents." This narrative context is preserved in case reports and retrospective analyses.

💡 Toggle the dispersal fan layer (🌊 button in the map top-right) to see how the fan lines radiate from each disembarkation point. The fan density corresponds to the contact count relative to the vessel's total population. This is particularly useful when briefing port health authorities about the geographic scope of the risk.

Linking the disembarkation to the port stop

A vessel_disembarkation event represents the departure of people from the vessel, while the port_stop represents the vessel's presence at that location. They are distinct events at the same coordinates. You do not need to formally link them in the system — the shared coordinates mean the map places them at the same geographic point, and the date proximity is sufficient context.

Edge case: Medical evacuation (MEDEVAC)

⚠️ Do not use vessel_disembarkation for a MEDEVAC. A disembarkation event models community dispersal risk — the dispersal fan it generates implies people spreading into an uncontrolled population. A helicopter evacuation takes a single critically ill patient to a controlled medical environment. Using a vessel_disembarkation here would draw misleading fan lines over the ocean and inflate your apparent community spread risk.

Model a MEDEVAC entirely on the case record itself using two records:

1. Add a route waypoint at the evacuation position — In the Case Inspector → Route tab, add a waypoint at the interpolated mid-ocean coordinates. Interpolation from departure time + vessel speed + elapsed time to the next port is standard practice for maritime incident reconstruction — document the method in the waypoint's Notes field (e.g. "Position estimated: midpoint between Port A departure 08:00 and Port B arrival 14:30 on [date]"). Set Departed to the evacuation date/time.

2. Add a clinical event (Hospitalized) at the same position — In the Route tab, add a Clinical Event with type Hospitalized at the same interpolated coordinates and the evacuation date. This anchors the clinical timeline — the map will render a coloured marker at the evacuation point that analysts can click to see the date and result.

3. Add a final waypoint at the receiving hospital (optional) — If the receiving facility is known, add a second waypoint at its coordinates with the arrival date. This creates a visible route arc from the mid-ocean evac point to shore, making the transfer visible in the route layer without implying community dispersal risk.

💡 If the evacuee later becomes a community exposure risk — for example, they recovered, were discharged before the outbreak was officially identified, and then travelled home — then create a vessel_disembarkation (or dispersal if they connected through a hub) anchored at the discharge location with the discharge date. The hospital is the new origin of potential community spread, not the mid-ocean evac point.

Edge case: Onboard death and body repatriation

A case's route history ends at death. Route waypoints model where an active case was moving through a population for contact tracing and transmission chain purposes. Post-mortem movement of a body is not epidemiologically significant for ongoing transmission risk and should not be recorded as route waypoints — doing so would make the map appear to show an active case travelling to the mainland when no such risk exists.

1. Record a deceased clinical event at the death location — This is the terminal point of the case's active infection timeline. Use the vessel's position at the time of death for coordinates (interpolate if at sea between port calls, as with MEDEVAC). Set the date to the confirmed date of death. This marker will appear on the map in the clinical events layer.

2. Document repatriation in the case Notes field — Record the repatriation chain in plain text — e.g. "Body held in ship's morgue (refrigerated) from [date]. Transferred ashore at [Port] on [date] for repatriation to [country/location]." This preserves the forensic record without adding waypoints that imply active movement.

3. Check for pre-mortem contacts who handled the body — If any crew or mortuary staff handled the body without PPE before it was properly sealed — during the period the case was still infectious — those individuals are potential contacts within the active infection window and should be captured as transmission links on this case.

💡 Body bag + refrigeration closes the infection risk for most pathogens. The notable exception is haemorrhagic fever viruses (e.g. Ebola), where viral load in a cadaver can be higher than during life and post-mortem handling is a documented transmission route. For those pathogens, any mortuary workers who handled the body should be linked to a healthcare exposure event at the receiving mortuary. For the respiratory and gastrointestinal pathogens responsible for the vast majority of shipboard outbreaks, a properly sealed and refrigerated body represents no further tracking obligation in this system.

Phase 5 — Community Spread

When a disembarked passenger or crew member is identified as a case in the community — either at their destination or back at their home address — they are modelled as a full Health Case linked to the disembarkation event that put them ashore.

Creating community cases

Create the case normally in the Patient Cases panel. The key differences from onboard cases are:

Visualising the spread

With community cases in place, the map will show:

• Route polylines (🛤) — arcs from each community case's disembarkation port to their home location
• Transmission vectors — colour-coded lines from the last known shipboard contact to community cases
• Dispersal fans (🌊) — fan lines radiating from each disembarkation event, scaled by contact count
• Cluster halos (⭕) — auto-detected geographic groupings of cases that may indicate secondary community clusters

ℹ️ Use the Outbreak Timeline slider (⏱ in the map top-right) to step through the outbreak day by day. Watching the case pins and transmission vectors appear in sequence is often the most effective way to reconstruct the transmission sequence and identify when and where community spread most likely began.

Exposure Event Types Reference

The following exposure event types are relevant to vessel outbreak tracking:

Map Layer Guide

The toggle bar in the top-right of the map controls which health workbench layers are visible. For a vessel outbreak, the recommended configuration at each stage is:

Naming Conventions

Consistent naming makes it much easier to search, filter, and report across a complex vessel outbreak. The following conventions are recommended:

Known Limitations & Workarounds

The workbench was not designed exclusively for mobile-environment outbreaks. The following limitations are relevant and noted here with recommended workarounds.

🔴 Do not use the outbreak for both vessel and community cases if Rt metrics are being used for public health decision-making. The effective Rt aboard a confined vessel (where contact rates are very high and population is fixed) will significantly overestimate Rt in the open community. Maintain separate outbreak records if metric precision is required.