Recommended practice for populating various fields for arrival/departure estimates?

[barbeau]

Summary:

This is a good candidate for a GTFS-realtime best practice.

From discussion in #41 (comment).

Given a producer that can provide any or all of TripUpdate.delay, StopTimeEvent.time, and StopTimeEvent.delay, it seems like it's best to only provide StopTimeEvent time to give the most relevant data and avoid ambiguity. Does that sound right?

What is the recommended practice for populating or not populating these fields?

Some advantages/disadvantages are discussed in the above thread.

[barbeau]

So it seems that TripUpdate.delay may have been intended to represent "schedule deviation", i.e., the observed past value for how ahead/behind schedule the vehicle is, although this isn't very clear in the spec wording and I don't think it matches current use of the field.

The first line says:

The current schedule deviation for the trip.

...but then it's followed by some text that appears to be copied from StopTimeEvent.delay, that indicates it's a prediction:

Delay should only be specified when the prediction is given relative to some existing schedule in GTFS.

...which isn't correct if this is actually schedule deviation.

[minhhpham]

From an analysis through transitfeeds.com. There are 24 agencies that use StopTimeUpdate.delay and none use TripUpdate.delay. Here are the 24 agencies:

FEED

TriMet TripUpdates
VRE Trip Updates
OCTA Trip Updates
COTA Trip Updates
HART Trip Updates
OVapi Train Trip Updates
OVapi Trip Updates
Big Blue Bus Trip Updates
AC Transit Trip Updates
BURT Trip Updates
LTD Trip Updates
RIPTA Trip Updates
People Mover Trip Updates
Metro Transit Trip Updates
BART Trip Updates
Capital Metro Trip Updates
Barrie Transit Trip Updates
VIA Trip Updates
ETS Trip Updates
CapMetro Trip Updates
MetroTransit Trip Updates
Votran Trip Updates
MST Trip Updates
BART Trip Updates

The code for this analysis is at trip_and_stop_delay branch

[barbeau]

@minhhpham Thanks! And how many feeds total? I assume the remainder use at least StopTimeUpdate time fields.

[barbeau]

As mentioned in opentripplanner/OpenTripPlanner#2733 (comment), the spec currently states:

At least one stop_time_update must be provided for the trip unless the trip.schedule_relationship is CANCELED - if the trip is canceled, no stop_time_updates need to be provided.

This is wrong after the addition of TripUpdate.delay - the documentation should say:

At least one stop_time_update must be provided for the trip unless the trip.schedule_relationship is CANCELED or TripUpdate.delay is provided - if the trip is canceled or TripUpdate.delay is provided, no stop_time_updates need to be provided

[kurtraschke]

Before TripUpdate.delay existed, there was a field in the OBA GTFS-realtime extension for TripUpdate-level delay. The intention was (as far as I'm aware) to make it more straightforward to produce GTFS-realtime from source systems which only provide trip-level schedule deviation, and have no concept of stop-level predictions. At some point this was adopted as an experimental field in the official spec, and then the field in the OBA extension was marked as deprecated.

Concerning the conversation in #41, I agree that (and the spec should reflect that) it's an either-or situation - it is an error to populate TripUpdate.delay if one or more StopTimeUpdates have been added to a TripUpdate.

As to the spec language quoted above, ("Delay should only be specified when the prediction is given relative to some existing schedule in GTFS."), I understand this to mean simply that the TripUpdate.delay field is not relevant on ADDED trips, although I agree the wording could be clarified if that is the intended meaning.

If the community prefers to remove TripUpdate.delay, then I would recommend that the spec (or community best practices) should provide explicit guidance for producers who do not have stop-level data.

[barbeau]

As to the spec language quoted above, ("Delay should only be specified when the prediction is given relative to some existing schedule in GTFS."), I understand this to mean simply that the TripUpdate.delay field is not relevant on ADDED trips, although I agree the wording could be clarified if that is the intended meaning.

@kurtraschke This same language appears in the StopTimeEvent description ("delay should be used when the prediction is given relative to some existing schedule in GTFS"), so it's not specific to TripUpdate.delay.

There are three situations I can think of that this applies to where prediction time must be provided, and not delay:

1. If the stop record in stop_times.txt isn't a timepoint and no arrival_time and departure_time are provided
2. If the trip is frequencies.txt exact_times=0 or exact_times column is missing (i.e., true frequency-based trip)
3. ADDED trips

I agree that we should specifically call out these situations here in the docs.