exact_times in frequencies.txt

[Tom Brown]

-- Motivation

Some agencies in small US towns have routes with a fixed and regular schedule. Instead of creating a very repetitive stop_times table they have asked if they can provide the times for one trip and use frequencies.txt to specify how often it runs. This makes creating stop_times manually much easier.


-- Proposed change

Add a column exact_times to frequencies.txt that may contain 0 or 1. If the column is absent or value is empty it is treated as 0, the same as today. exact_times must be the same for all frequencies rows with the same trip_id. If exact_times is 1 than the original trip is removed and replaced with one or more trips for each frequencies.txt row starting at trip_start = start_time + x * headway_secs for all x in (0, 1, 2, ...) where trip_start < end_time. A trip with trip_start = end_time must not be generated, see example. In English: headway_secs is the time between trips, start_time is the time of the first trip, end_time should be a little (much less than headway_secs) after the start of the last trip and for convenience the times in stop_times.txt should be for the first trip.


-- Example

trips.txt
trip_id,...
AWE1,...

frequencies.txt
trip_id,start_time,end_time,headway_secs,exact_times
AWE1,05:30:00,07:30:00,1800,1
AWE1,07:30:00,18:30:00,900,1
AWE1,18:30:00,22:00:00,1800,1

trips with trip_start = end_time are not generated to prevent duplicate trips at 7:30 and 18:30. In other words the set of times included is closed at start_time and open at end_time.

-- Trade offs

Supporting exact_times is good because it makes producing data easier. "Feeds should be easy to create and edit" is the first goal for GTFS listed in the welcome message http://groups.google.com/group/gtfs-changes/msg/d4f99230d44d2c93 . Alternately we could maintain a tool that does the expansion from a trip + frequencies to a list of trips but people who manually generate feeds probably aren't keen to use more tools.

The downside of exact_times is that it complicates all software that wants to use these feeds. Also, we've avoided specifying exactly how frequencies.txt should be interpreted but for exact_times we need to be precise so all consumers act the same way. This makes it the most complex part of the specification which isn't great since this is meant to help less tech-savy producers. On the other hand our partners haven't had trouble using exact_times correctly.


-- Discussion

GTFS has a way for representing headway-based service, using the frequencies.txt table. The problem is that there are at least two ways to interpret this table:

1) The service does not operate on a fixed schedule. headways give riders a way to estimate expected wait times but say nothing about actual departure times. For service within a city this is a reasonable interpretation when trip-planning with headways less than 15 minutes. For example AirBART does not advertise a schedule and I think many automated trams (such as between airport terminals) don't have a schedule. TriMet is putting a lot of emphasis on routes with headway <= 15 min and is no longer posting exact times at the stops for these routes, though internally all trips have an exact schedule.

2) The service has a fixed and regular schedule. The agency is using frequencies.txt as a shortcut for a repetitive stop_times file. Exactly the same trips could be represented by creating a trip starting at trip_start = start_time + x * headway_secs for all x in (0, 1, 2, ...) where trip_start < end_time and discarding the template trip_id that is referenced by frequencies.txt. Often these headways are 30 or 60 minutes.
This type of schedule is fairly common at small US agencies, for example:
http://www.bristoltn.org/uploads/2004__BTT_map.pdf
http://www.lawrencetransit.org/routes/rt1northbound.shtml
http://www.ci.green-bay.wi.us/geninfo/metro/routes/1_east_mason.pdf

Google trip planner actually treats 1) as 2) because it is much simpler than using probabilistic expected wait times for 1) and works fairly well. We show "Service runs every x mins" instead of exact times. For example the Shuttle in http://maps.google.com/maps?q=sf+to+oak&dirflg=r

While getting data for Google's trip planner we've had lots of requests to support 2). I think most of these requests have come from people who are generating their GTFS feeds manually. We added a new column exact_times to frequencies.txt. When this is 1 we know interpretation 2) is intended and also display the exact times in the UI.
http://www.google.com/maps?f=d&source=s_d&saddr=Green+Bay,+WI&daddr=Greenleaf+Rd%2FWI-32%2FWI-57&geocode=%3BFYbupQId0S3A-g&mra=cc&dirflg=r&sll=44.446404,-88.078852&sspn=0.100491,0.070381&ie=UTF8&ll=44.446404,-88.078852&spn=0.401963,0.281525&z=12&start=2

For more discussion about interpreting frequencies.txt see
http://groups.google.com/group/googletransit/t/e65cd8caf3682e3c