Skip to content

GTFS-Occupancies #240

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dbabramov merged 20 commits into from
Oct 25, 2021
Merged

GTFS-Occupancies #240

Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
be8a380
Add GTFS-MeanOccupancies
Aug 5, 2020
8b99ddf
Edits [1]
Aug 5, 2020
720d897
Editorial change to description of mean_occupancy_percentage
Aug 5, 2020
d816fe9
General edit
timMillet Aug 7, 2020
12e6692
Add file descriptions
timMillet Aug 7, 2020
54ec83e
PR update to Option C
Nov 20, 2020
1ea4b35
Minor editorial corrections
Nov 20, 2020
716d192
Remove Option A leftover
Nov 20, 2020
cb183e7
Single-date occupancy predictions (Option B)
Nov 26, 2020
6dcb9ea
Clarification to `date` field
Nov 26, 2020
4557902
Option D
Dec 8, 2020
d99a627
Added 0 "or empty" to days
Dec 8, 2020
92a8b02
Update reference.md
Feb 1, 2021
8eba8b9
Update reference.md
Feb 1, 2021
51d273e
modeling updates
Sep 17, 2021
0b35ec6
Merge branch 'master' into gtfs-mean-occupancies
Sep 17, 2021
b23784c
fix trip referencing
Sep 20, 2021
9e3200b
Revert "fix trip referencing"
Sep 20, 2021
d28afc3
frequency-based trips
Sep 21, 2021
f2ea4cf
Update guidelines
Sep 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions gtfs/spec/en/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ This document defines the format and structure of the files that comprise a GTFS
- [transfers.txt](#transferstxt)
- [pathways.txt](#pathwaystxt)
- [levels.txt](#levelstxt)
- [occupancies.txt](#occupanciestxt)
- [translations.txt](#translationstxt)
- [feed\_info.txt](#feed_infotxt)
- [attributions.txt](#attributionstxt)
Expand Down Expand Up @@ -95,6 +96,7 @@ This specification defines the following files:
| [frequencies.txt](#frequenciestxt) | Optional | Headway (time between trips) for headway-based service or a compressed representation of fixed-schedule service. |
| [transfers.txt](#transferstxt) | Optional | Rules for making connections at transfer points between routes. |
| [pathways.txt](#pathwaystxt) | Optional | Pathways linking together locations within stations. |
| [occupancies.txt](#occupanciestxt) | Optional | Expected or usual in-vehicle occupancy levels. |
| [levels.txt](#levelstxt) | **Conditionally Required** | Levels within stations.<br><br>Conditionally Required:<br>- **Required** when describing pathways with elevators (`pathway_mode=5`).<br>- Optional otherwise. |
| [translations.txt](#translationstxt) | Optional | Translations of customer-facing dataset values. |
| [feed_info.txt](#feed_infotxt) | Optional | Dataset metadata, including publisher, version, and expiration information. |
Expand Down Expand Up @@ -380,6 +382,31 @@ Describes levels in a station. Useful in conjunction with `pathways.txt`, and is
| `level_index` | Float | **Required** | Numeric index of the level that indicates its relative position. <br><br>Ground level should have index `0`, with levels above ground indicated by positive indices and levels below ground by negative indices.|
| `level_name` | Text | Optional | Name of the level as seen by the rider inside the building or station.<hr>_Example: Take the elevator to "Mezzanine" or "Platform" or "-1"._|

### occupancies.txt

File: **Optional**

Usual or expected in-vehicle occupancy levels.

Methods for occupancy forecasting used to populated `occupancies.txt` are not strictly specified. Beyond the guidelines given below, it is the responsibility of data producers to ensure that the data provided are meaningful.

For describing historical average occupancies, it is recommended that at least 4 weeks of occupancy data be averaged across each unique day of the week, and valid for up to 2 weeks thereafter in `occupancies.txt`.

| Field Name | Type | Required | Description |
| ----- | ----- | ----- | ----- |
| `trip_id` | ID referencing `stop_times.trip_id` | **Required** | Identifies a `trip_id` for which an occupancy level is described. |
| `stop_sequence` | ID referencing `stop_times.stop_sequence` | Optional | Identifies a `stop_sequence` along `occupancies.trip_id` for which an occupancy level is described.<br><br>Defined values in `occupancies.stop_sequence` will apply to subsequent `stop_times.stop_sequence` that are not defined in `occupancies.stop_sequence` for the same `trip_id`. |
| `occupancy_status` | Enum | **Required** | Indicates the state of in-vehicle occupancy. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums. Valid options are:<br><br> `0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers. <br> `1` - **Many seats available**. The vehicle has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer. <br> `2` - **Few seats available**. The vehicle has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer. <br> `3` - **Standing room only**. The vehicle can currently accommodate only standing passengers. <br> `4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them. <br> `5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board. <br> `6` - **Not accepting passengers**. The vehicle can not accept passengers. |
Copy link
Contributor

@jeffkessler-keolis jeffkessler-keolis Sep 21, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For those who wish to provide objective historical values without the subjective categorizations, could we make this conditionally required with an option to use occupancy_percentage instead?

Suggested change
| `occupancy_status` | Enum | **Required** | Indicates the state of in-vehicle occupancy. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums. Valid options are:<br><br> `0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers. <br> `1` - **Many seats available**. The vehicle has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer. <br> `2` - **Few seats available**. The vehicle has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer. <br> `3` - **Standing room only**. The vehicle can currently accommodate only standing passengers. <br> `4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them. <br> `5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board. <br> `6` - **Not accepting passengers**. The vehicle can not accept passengers. |
| `occupancy_status` | Enum | ** Conditionally Required** | Indicates the state of in-vehicle occupancy. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums. Valid options are:<br><br> `0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers. <br> `1` - **Many seats available**. The vehicle has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer. <br> `2` - **Few seats available**. The vehicle has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer. <br> `3` - **Standing room only**. The vehicle can currently accommodate only standing passengers. <br> `4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them. <br> `5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board. <br> `6` - **Not accepting passengers**. The vehicle can not accept passengers. <br><br>Conditionally Required:<br>- **Required** if `occupancies.occupancy_percentage` is empty.<br>- Optional|
| `occupancy_percentage` | Float | **Required** | Indicates the typical occupancy percentage. The value 100 should represent total the maximum occupancy the vehicle was designed for, including both seating and standing capacity, and current operating regulations allow. It's not impossible that the value goes over 100 if there are currently more passenger than the vehicle was designed for. The precision of precision should be low enough that you can't track a single person boarding and alighting for privacy reasons. <br><br>Conditionally Required:<br>- **Required** if `occupancies.occupancy_status` is empty.<br>- Optional|

Copy link
Contributor Author

@sccmcca sccmcca Sep 21, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

occupancies.txt is contingent on getting either occupancy_status or occupancy_percentage officially adopted in GTFS Realtime for consistency. Whichever method of describing occupancies (possibly both) that becomes official will be represented here.

Copy link
Contributor

@jeffkessler-keolis jeffkessler-keolis Sep 21, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Even if one is officially adopted, I'd still request that both options be available in the static version. (Or, at the very least, we may choose to release both with one being treated as an experimental field.)

| `monday` | Enum | **Required** | Indicates whether an occupancy level is valid for all Mondays in the date range specified by `occupancies.start_date` and `occupancies.end_date`. Valid options are: <br><br> `1` - The occupancy level applies for all Mondays in the date range.<br>`0` or empty - The occupancy level does not apply for all Mondays in the date range. |
| `tuesday` | Enum| **Required** | Functions in the same way as `occupancies.monday` except applies to Tuesdays. |
| `wednesday` | Enum| **Required** | Functions in the same way as `occupancies.monday` except applies to Wednesdays. |
| `thursday` | Enum| **Required** | Functions in the same way as `occupancies.monday` except applies to Thursdays. |
| `friday` | Enum| **Required** | Functions in the same way as `occupancies.monday` except applies to Fridays. |
| `saturday` | Enum| **Required** | Functions in the same way as `occupancies.monday` except applies to Saturdays. |
| `sunday` | Enum| **Required** | Functions in the same way as `occupancies.monday` except applies to Sundays. |
| `start_date` | Date | **Required** | Start date of the date interval that the occupancy level is valid.<br><br>To define single dates, `start_date` and `end_date` may be the same. |
| `end_date` | Date | **Required** | End date of the date interval that the occupancy level is valid.<br><br>To define single dates, `start_date` and `end_date` may be the same. |
| `start_time` | Time | **Conditionally Required** | First stop departure time for a given vehicle on a trip using `frequencies.txt`.<br><br>Must be some multiple (including zero) of `frequencies.headway_secs` plus `frequencies.start_time` for the corresponding time period.<br><br>Conditionally Required:<br>- **Required** for trips using `frequencies.txt`.<br>- **Forbidden** otherwise. |
Copy link
Contributor

@skinkie skinkie Sep 21, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will get very complex. But do we want to do something like start_time end_time so for frequency based trips a producer could do occupancy time bands? Self-note to my future self: I just shot myself in the foot.

Copy link
Contributor Author

@sccmcca sccmcca Sep 21, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe I am missing something, but isn't start_time enough to identify individual "vehicle journeys" on a frequency-based trip, and then define different occupancies per stop_sequence, per vehicle journey? This seems to accomplish "occupancy time bands".

Copy link
Contributor

@skinkie skinkie Sep 21, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@scmcca in frequency based operation only exact times will have some useful meaning for start_time.

Copy link
Contributor Author

@sccmcca sccmcca Sep 21, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could be what I am missing. At the risk of sounding misinformed, why would it not work for exact_times=0? Can't frequencies.start_time be used to estimate vehicle journeys?

Copy link
Contributor

@skinkie skinkie Sep 21, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that part is only possible heuristically, hence clamp to the nearest start_time. If that route is suggested that must be documented.

Copy link
Contributor

@barbeau barbeau Sep 21, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @skinkie that specifying a start and end time to define a window is a more natural solution for exact_times=0 trips.

For exact_times=1, you have specific trips instances that are defined in static GTFS where you can say "A bus is scheduled to arrive in 5 minutes", so start_time unambigously maps to a single trip instance.

For exact_times=0 trips, static GTFS is just defining an expected frequency (not trip instances at specific times), so (without real-time data) you can only say "Vehicles are expected to arrive every 15 minutes" during this time window. The exact time that these trip instances are expected to occur drifts throughout the day depending on the previous trip instances, so defining just a start_time may get ambiguous. We would need defined heuristics in the spec of how specific cases would be handled.


### translations.txt

Expand Down