estimateDrift

Legs, dwell, cut-offs and punctuality, shared by road, rail, sea and air.

Signature

estimateDrift(events: TimestampEvent[], options?: EstimateDriftOptions): DriftReport | null

Measure how far an estimate moved between its first and last revision.

Schedule-reliability reporting asks how much an estimated arrival slid while it was being revised, and a revision far enough from the first estimate means something must be redone: rebooked, re-planned, renotified. The threshold is the caller’s; the consequence is the consumer’s.
Only EST records are read, in the order they were recorded (recordedAt). Two records at the same instant are ordered by their place in the array, the later one last — the same tie rule as bestAvailable. PLN, REQ and ACT records are validated and otherwise ignored.
revisions is the number of EST records, the first included.
drift is the last EST’s at minus the first’s, in exact elapsed time with hours as the largest unit: positive when the estimate moved later, negative when earlier. Across a fall-back night, 01:30 EDT to 01:30 EST is PT1H.
With tolerance, exceedsTolerance is true when the drift, in either direction, is greater than the tolerance; exactly the tolerance is false. Without it, null.
first and last echo at exactly as written; both are instants (Z/offset) or zoned strings compared as instants, read as scheduleDeviation reads them: the offset fixes the instant, and an offset written to the minute that is the bracketed zone’s sub-minute offset rounded (-00:45[Africa/Monrovia], for −00:44:30) names the instant the zone gives. Otherwise the bracket is not checked.
Returns null with fewer than two EST records — there is no drift from one sample — and on invalid input: any invalid event, of any class, or an invalid, negative or calendar-unit tolerance.

Parameters

Parameter	Type	Description
`events`	`TimestampEvent[]`	the event’s timestamp records, in any order

Options

options

The threshold the absolute drift is compared with

Options for estimateDrift.

import type { EstimateDriftOptions } from "@northguild/gmt";

Option	Type	Default	Description
`tolerance?`	`string`	None. `exceedsTolerance` is `null`.	The drift allowed, as an ISO 8601 duration of exact time (a day is 24 hours; years, months and weeks are refused; not negative). With it, `exceedsTolerance` says whether the drift is greater than it.

Returns

the first and last estimates, the drift, the revision count and the tolerance check (null with fewer than two EST records), or null on invalid input

Types

DriftReport

What estimateDrift returns.

import type { DriftReport } from "@northguild/gmt";

Member	Type	Description
`first`	`string`	The earliest-recorded EST’s `at`, exactly as written.
`last`	`string`	The latest-recorded EST’s `at`, exactly as written.
`drift`	`string`	The drift: `last` minus `first` in exact time, hours as the largest unit; negative when it moved earlier.
`revisions`	`number`	The number of EST records, the first included.
`exceedsTolerance`	`boolean` \| `null`	Whether the absolute drift is greater than `tolerance`; `null` without a tolerance.

Examples

import { estimateDrift } from "@northguild/gmt/transport/calculate";

estimateDrift([{ classifier: "EST", at: "2024-06-20T08:00:00Z", recordedAt: "2024-06-01T00:00:00Z" }, { classifier: "EST", at: "2024-06-20T12:00:00Z", recordedAt: "2024-06-05T00:00:00Z" }, { classifier: "EST", at: "2024-06-20T17:00:00Z", recordedAt: "2024-06-10T00:00:00Z" }]) // { first: "2024-06-20T08:00:00Z", last: "2024-06-20T17:00:00Z", drift: "PT9H", revisions: 3, exceedsTolerance: null }

Source

transport/calculate/estimateDrift.ts