Comments (8)
There has been a discussion in the canonical GTFS schedule validator around this issue, and we noticed that existing data had implemented timepoint in two opposite ways:
- Considering that
stop_times.timepoint
= "" means times are exact. This is based onstop_times.timepoint
description.
1 or empty - Times are considered exact.
Sample from the Greater Glens Falls Transit (Mobility Database link), which doesn't contain any 1's in the timepoint column.
stop_sequence | arrival_time | departure_time | timepoint |
---|---|---|---|
0 | 13:15:00 | 13:15:00 | |
1 | 13:30:00 | 13:30:00 | 0 |
2 | 13:40:00 | 13:40:00 | 0 |
3 | 13:50:00 | 13:50:00 | |
4 | 14:00:00 | 14:00:00 | 0 |
- Considering that
stop_times.timepoint
= "" means times are approximate. This is based onstop_times.departure_time
andstop_times.arrival_time
description:
Conditionally Required: Required for timepoint=1. Optional otherwise.
Sample from the Squaxin Island Transit (Mobility Database link), which doesn't contain any 0's in the timepoint column.
stop_sequence | arrival_time | departure_time | timepoint |
---|---|---|---|
1 | 8:30:00 | 8:30:00 | 1 |
2 | 8:31:01 | 8:31:01 | 1 |
3 | |||
4 | |||
5 | |||
6 | |||
7 | |||
8 | |||
9 | |||
10 | 8:45:00 | 8:45:00 | 1 |
11 | 8:55:00 | 8:55:00 | 1 |
The GTFS validator won't interpret empty timepoint values as equivalent to 1 in order to avoid false positives, but it will flag:
- a record with
timepoint
= 1 and (departure_time
orarrival_time
) missing (referencing the specification), as an error. - a record with a missing value in
timepoint
(only if the column exists, referencing the specification although not said explicitly), as a warning. - a
stop_times.txt
file with no timepoint column (referencing the best practices), as a warning.
I think @barbeau's suggestion above would help a lot implement timepoint in a consistent way.
from transit.
The definition of "empty" within the GTFS spec hasn't been standardized, and generally speaking it should be - although this is a broader issue than just about the timepoint
field.
I'd still like to see the spec clarified to define what is allowed and what is not about this field. In retrospect, IMHO the way the definition is written it's hard to decipher the original intent.
This also needs some historical context of GTFS. Originally, prior to the timepoint field, GTFS spec said you should only provide arrival and departure times for stop_times.txt
records that are timepoints. So, if stops 1 and 4 were timepoints, but 2 and 3 were not, you'd have a valid GTFS that looks like this:
stop_sequence | arrival_time | departure_time |
---|---|---|
1 | 00:00:00 | 00:00:00 |
2 | ||
3 | ||
4 | 00:10:00 | 00:10:00 |
However, producers realized that for multiple consumers to show consistent scheduled arrival and departure times at each stop (i.e., so consumers didn't interpolate them and come up with their own values), they would need to share arrival/departure times for each stop in the trip. A large number of GTFS producers started doing the following, even though technically it was against the GTFS spec:
stop_sequence | arrival_time | departure_time |
---|---|---|
1 | 00:00:00 | 00:00:00 |
2 | 00:02:00 | 00:02:00 |
3 | 00:08:00 | 00:08:00 |
4 | 00:10:00 | 00:10:00 |
Now, to consumers, all the stops looked like timepoints, even though that wasn't the producer's intent.
The timepoint
field was added to give producers a legitimate way to share times for each stop in the trip, while still correctly indicating which stops are timepoints.
So if producers want to provide times for every stop, they shouldn't be doing the above, and instead should provide the timepoint
field:
stop_sequence | arrival_time | departure_time | timepoint |
---|---|---|---|
1 | 00:00:00 | 00:00:00 | 1 |
2 | 00:02:00 | 00:02:00 | 0 |
3 | 00:08:00 | 00:08:00 | 0 |
4 | 00:10:00 | 00:10:00 | 1 |
This means as of today, IMHO, there are two valid ways to share arrival and departure times in GTFS. The first is the original GTFS spec without the timepoint field, where times are omitted for stops that are not timepoints:
stop_sequence | arrival_time | departure_time |
---|---|---|
1 | 00:00:00 | 00:00:00 |
2 | ||
3 | ||
4 | 00:10:00 | 00:10:00 |
Or, if they want to provide times for every stop, they should provide timepoint values for the entire stop-times.txt.
stop_sequence | arrival_time | departure_time | timepoint |
---|---|---|---|
1 | 00:00:00 | 00:00:00 | 1 |
2 | 00:02:00 | 00:02:00 | 0 |
3 | 00:08:00 | 00:08:00 | 0 |
4 | 00:10:00 | 00:10:00 | 1 |
Here's a suggestion for clarifying the spec to try and capture the above intent:
Field Name | Required | Details | |
---|---|---|---|
timepoint | Optional | The timepoint field can be used to indicate if the specified arrival and departure times for a stop are strictly adhered to by the transit vehicle or if they are instead approximate and/or interpolated times. The field allows a GTFS producer to provide interpolated stop times that potentially incorporate local knowledge, but still indicate if the times are approximate. If a GTFS feed stop_times.txt file does not contain the timepoint field, feed producers must only provide arrival and departure times for stops that are timepoints - arrival and departure times should be left blank for stops that are not timepoints. In this case, consumers must interpolate all entries that do not have specified arrival and departure times. If a GTFS feed stop_times.txt file contains the timepoint field, every row in stop_times.txt should have a value for timepoint . Valid values for this field are: |
|
* 0 - Times are considered approximate. | |||
* 1 - Times are considered exact. | |||
If timepoint has a value of 0, arrival and departure times do not need to be provided for that stop. If timepoint has a value of 1, arrival and departure times must be provided for that stop. |
Alternate suggestions, or alternate interpretations of the spec, are welcome.
from transit.
Relevant thread from GTFS-changes here: https://groups.google.com/d/msg/transit-developers/dwd96EwJqIc/N5DJxP8VCQAJ
from transit.
My expectation for this feature when proposed/accepted was that there would be two types of feeds:
- Legacy feeds before the
timepoint
field existed, where the CSV headertimepoint
does not exist in stop_times.txt - New feeds going forward where
timepoint
field is added to stop_times.txt header, and all records in stop_times.txt have either a 0 or a 1
empty
as currently written means that stop_times.txt
is missing the CSV timepoint
header (at least that's how I always read it), and therefore there are no timepoint values for any records in stop_times.txt
- in other words, it's a legacy feed as described in 1) above. IMHO You shouldn't have a stop_times.txt file with a timepoint
CSV header that has some records with empty timepoint
values - this should be an error. I think some of the wording is a bit awkward as it was edited from the original text.
To clarify this, I suggest we remove * empty - Times are considered exact
as a valid value and update the text:
Field Name | Required | Details | |
---|---|---|---|
timepoint | Optional | The timepoint field can be used to indicate if the specified arrival and departure times for a stop are strictly adhered to by the transit vehicle or if they are instead approximate and/or interpolated times. The field allows a GTFS producer to provide interpolated stop times that potentially incorporate local knowledge, but still indicate if the times are approximate. If a GTFS feed stop_times.txt file does not contain the timepoint field, feed producers should only provide arrival and departure times for stops that are timepoints. In this case, consumers must interpolate all entries that do not have specified arrival and departure times. If a GTFS feed stop_times.txt file contains the timepoint field, every row in stop_times.txt should have a value for timepoint . Valid values for this field are: |
|
* 0 - Times are considered approximate. | |||
* 1 - Times are considered exact. | |||
If timepoint has a value of 0, arrival and departure times do not need to be provided for that stop. If timepoint has a value of 1, arrival and departure times must be provided for that stop. |
from transit.
The spec currently reads:
0
- Times are considered approximate.
1
or empty - Times are considered exact.
Other notes are provided in the arrival_time
and departure_time
field definitions.
Disallowing an empty value for timepoint would not technically be a backwards-compatible change (though it's a very minor breaking change).
Should we:
- Discuss a change to the spec?
- Discuss a change to the Best Practices and/or validation software?
- Do nothing and/or close this issue?
- Something else?
from transit.
As discussed in this thread:
MobilityData/gtfs-validator#887 (comment)
...how timepoint
works in conjunction with frequencies.txt exact_times=0 trips should also be clarified.
MobilityData/gtfs-validator#887 (comment) says:
A trip can be frequency-based, so the exact start of the trip is unknown. However, once the vehicle starts moving, it visits each stop in predictable time since the time difference between each stop is fixed (hence timepoint=1). This is a usual case for metro/subway/underground. So, frequency-based trips may have timepoint=1.
...but this isn't documented anywhere in the spec.
My comment here:
MobilityData/gtfs-validator#887 (comment)
...said:
I can't think of another way in the validator (based on the current spec at least) to differentiate the valid use case from agencies mistakenly assigning wall-clock timepoints to exact_times=0 trips. One approach that would require a spec change is for consumers to start exact_times=0 trips at midnight to clearly differentiate the use of stop_times.txt time records for time offsets rather than wall-clock times.
from transit.
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
from transit.
keep open
from transit.
Related Issues (20)
- GTFS-Fares v2: Improvement of filling with stops of a certain area HOT 2
- Move Dataset Publishing and General Practices from Best Practices to the spec HOT 10
- Add recommended presence: reconciling confusion between best practices and spec HOT 10
- Thoughts on forbidding "subfolder inside zip"? HOT 8
- TripDescriptor.start_date matching between GTFS-RT + GTFS-static HOT 2
- GTFS-Flex: Service Discovery HOT 11
- Add rule_priority field to fare_leg_rules.txt HOT 6
- Add fare_media_type=1 to fare_media.txt HOT 8
- GTFS-Fares v2: Add networks.txt & route_networks.txt HOT 13
- GeoJSON in GTFS? (Or the future of GTFS serialisation) HOT 20
- Phone number international format in GTFS HOT 2
- stop_times.shapes_dist_traveled shouldn't be defined if the trip doesn't have shapes associated HOT 7
- GTFS changes - voting agents HOT 12
- Moving Schedule Best Practices into the Spec: Phasing Plan HOT 5
- [GTFS-Flex] Remove referencing location.geojson ids in stop_areas.txt (formerly location_groups.txt)?
- [GTFS-Flex] Replace areas.txt/stop_areas.txt with locations.geojson MultiPoint feature to describe collections of stops? HOT 11
- GTFS-fares v2: Fare Leg Rule "Scope" Support
- [GTFS-Flex] Should pickup_type=3 remain forbidden for Flex zones/stop groups? HOT 2
- [Community Outreach] GTFS amendment process pain points - Your insights count! HOT 8
- Codes for stations and stop points / line codes / line pictograms HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from transit.