From be8a380cacd76281c040fdb8a6fdc4fd99922e65 Mon Sep 17 00:00:00 2001 From: scmccallum Date: Wed, 5 Aug 2020 09:30:31 -0400 Subject: [PATCH 01/19] Add GTFS-MeanOccupancies Adds the files of MobilityData's GTFS-MeanOccupancies proposal to the GTFS Static reference. --- gtfs/spec/en/reference.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 04a7904e1..35c8359a7 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -28,6 +28,9 @@ This document defines the format and structure of the files that comprise a GTFS - [translations.txt](#translationstxt) - [feed\_info.txt](#feed_infotxt) - [attributions.txt](#attributionstxt) + - [occupancies.txt](#occupanciestxt) + - [occupancy_patterns.txt](#occupancy_patternstxt) + - [vehicle_couplings.txt](#vehicle_couplingstxt) ## Term Definitions @@ -85,6 +88,9 @@ This specification defines the following files: | [translations.txt](#translationstxt) | Optional | Translations of customer-facing dataset values. | | [feed_info.txt](#feed_infotxt) | Optional | Dataset metadata, including publisher, version, and expiration information. | | [attributions.txt](#attributionstxt) | Optional | Dataset attributions. | +| [occupancies.txt](#occupanciestxt) | Optional | Mean occupancy profiles at boarding time. | +| [occupancy_patterns.txt](#occupancy_patternstxt) | Optional | Patterns of mean occupancy profiles at boarding time for different days of the week and child vehicles. | +| [vehicle_couplings.txt](#vehicle_couplingstxt) | Optional | Defines the arrangement of child vehicles in composed parent vehicles. | ## File Requirements @@ -420,3 +426,35 @@ The file defines the attributions applied to the dataset. | `attribution_url` | URL | Optional | URL of the organization. | | `attribution_email` | Email | Optional | Email of the organization. | | `attribution_phone` | Phone number | Optional | Phone number of the organization. | + +### occupancies.txt + +File: **Optional** + +| Field Name | Type | Required | Description | +| ----- | ----- | ----- | ----- | +| `occupancy_id` | ID | **Required** | Identifies an occupancy profile. | +| `mean_occupancy_percentage` | Integer | **Required** | Mean percentage of the `occupancy_type` that is occupied in the vehicle at boarding time.

Valid percentage values are greater than or equal to `0`. The value `100` should represent the total maximum occupancy the vehicle was designed for, according to the `occupancy_type`, and current operating regulations allow.

It is possible that the value goes over `100` if the occupancy is greater than what the vehicle was designed for. The degree of precision should be low enough that you can't track a single rider boarding and alighting for privacy reasons.

A value of `-1` indicates that the vehicle is likely not accepting riders for this `occupancy_type`. | +| `occupancy_type` | Enum | Optional | Describes the type of occupancy. Valid options are:

`0` or empty - seating and standing occupancy
`1` - riders in a wheelchair
`2` - bikes
`3` - cars

Multiple `occupancy_type` can be defined for the same `occupancy_id`. | +| `mean_occupancy_status` | Enum | Conditionally Required | The nominal degree of passenger occupancy for the vehicle. Occupancy status enums as seen in GTFS Realtime for [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus).

`0` - **_EMPTY_**
The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.

`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.

`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.

`3` - **_STANDING_ROOM_ONLY_**
The vehicle can currently accommodate only standing passengers.

`4` - **_CRUSHED_STANDING_ROOM_ONLY_**
The vehicle can currently accommodate only standing passengers and has limited space for them.

`5` - **_FULL_**
The vehicle is considered full by most measures, but may still be allowing passengers to board.

`6` - **_NOT_ACCEPTING_PASSENGERS_**
The vehicle can not accept passengers.

Conditionally Required:
- **Required** if `occupancy_type=0` or empty
- Forbidden otherwise | + +### occupancy_patterns.txt + +File: **Optional** + +| Field Name | Type | Required | Description | +| ----- | ----- | ----- | ----- | +| `occupancy_pattern_id` | ID | **Required** | Identifies an occupancy pattern. | +| `occupancy_id` | ID referencing `occupancies.occupancy_id` | **Required** | Identifies the occupancy profile for the `occupancy_pattern_id`.

Multiple `occupancy_id` can share the same `occupancy_pattern_id`. | +| `service_id` | ID referencing `calendars.service_id` | Optional | Identifies the day(s) of the week that the occupancy pattern applies. | +| `parent_id` | ID referencing `vehicle_couplings.parent_id` | Optional | Identifies a parent vehicle that has 2 or more child vehicles. | +| `child_sequence` | Non-negative Integer referencing `vehicle_couplings.child_sequence` | Conditionally Required | Denotes the location of the child vehicle from the beginning of the parent vehicle for which the `occupancy_pattern_id` is being described.

Many `child_sequence` may be defined for the same `occupancy_pattern_id`.

The `occupancy_pattern_id` applies to subsequent `child_sequence` for omitted entries.

Conditionally Required if `parent_id` is defined. | + +### vehicle_couplings.txt + +File: **Optional** + +| Field Name | Type | Required | Description | +| ----- | ----- | ----- | ----- | +| `parent_id` | ID | **Required** | Identifies a parent vehicle with 2 or more child vehicles. | +| `child_sequence` | Non-negative Integer | **Required** | Denotes the location of the child vehicle from the beginning of the parent vehicle. The order number must be a non-negative integer increasing along the vehicle. | \ No newline at end of file From 8b99ddf86bdda684e80ecee1f0f9d2b85e763c5b Mon Sep 17 00:00:00 2001 From: scmccallum Date: Wed, 5 Aug 2020 11:51:19 -0400 Subject: [PATCH 02/19] Edits [1] Added back calendars.service_type and specified parent and child ID for vehicles --- gtfs/spec/en/reference.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 35c8359a7..4427f906f 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -237,6 +237,7 @@ File: **Conditionally required** | `sunday` | Enum | **Required** | Functions in the same way as `monday` except applies to Sundays. | | `start_date` | Date | **Required** | Start service day for the service interval. | | `end_date` | Date | **Required** | End service day for the service interval. This service day is included in the interval. | +| `service_type` | Enum | Optional | Indicates the type of service that the `service_id` is describing. Valid options are:

`0` or empty - The `service_id` is used for describing the days that a trip is in service.
`1` - the `service_id` is used for describing occupancies on different days. ### calendar_dates.txt @@ -446,9 +447,9 @@ File: **Optional** | ----- | ----- | ----- | ----- | | `occupancy_pattern_id` | ID | **Required** | Identifies an occupancy pattern. | | `occupancy_id` | ID referencing `occupancies.occupancy_id` | **Required** | Identifies the occupancy profile for the `occupancy_pattern_id`.

Multiple `occupancy_id` can share the same `occupancy_pattern_id`. | -| `service_id` | ID referencing `calendars.service_id` | Optional | Identifies the day(s) of the week that the occupancy pattern applies. | -| `parent_id` | ID referencing `vehicle_couplings.parent_id` | Optional | Identifies a parent vehicle that has 2 or more child vehicles. | -| `child_sequence` | Non-negative Integer referencing `vehicle_couplings.child_sequence` | Conditionally Required | Denotes the location of the child vehicle from the beginning of the parent vehicle for which the `occupancy_pattern_id` is being described.

Many `child_sequence` may be defined for the same `occupancy_pattern_id`.

The `occupancy_pattern_id` applies to subsequent `child_sequence` for omitted entries.

Conditionally Required if `parent_id` is defined. | +| `service_id` | ID referencing `calendars.service_id` | Optional | Identifies the day(s) of the week that the occupancy pattern applies. Valid for `service_id` where `calendars.service_type=1`. | +| `parent_vehicle_id` | ID referencing `vehicle_couplings.parent_id` | Optional | Identifies a parent vehicle that has 2 or more child vehicles. | +| `child_vehicle_sequence` | Non-negative Integer referencing `vehicle_couplings.child_sequence` | Conditionally Required | Denotes the location of the child vehicle from the beginning of the parent vehicle for which the `occupancy_pattern_id` is being described.

Many `child_sequence` may be defined for the same `occupancy_pattern_id`.

The `occupancy_pattern_id` applies to subsequent `child_sequence` for omitted entries.

Conditionally Required if `parent_id` is defined. | ### vehicle_couplings.txt @@ -456,5 +457,5 @@ File: **Optional** | Field Name | Type | Required | Description | | ----- | ----- | ----- | ----- | -| `parent_id` | ID | **Required** | Identifies a parent vehicle with 2 or more child vehicles. | -| `child_sequence` | Non-negative Integer | **Required** | Denotes the location of the child vehicle from the beginning of the parent vehicle. The order number must be a non-negative integer increasing along the vehicle. | \ No newline at end of file +| `parent_vehicle_id` | ID | **Required** | Identifies a parent vehicle with 2 or more child vehicles. | +| `child_vehicle_sequence` | Non-negative Integer | **Required** | Denotes the location of the child vehicle from the beginning of the parent vehicle. The order number must be a non-negative integer increasing along the vehicle. | \ No newline at end of file From 720d8977aad2dbf3b4ecbcfea043134c6e87be6d Mon Sep 17 00:00:00 2001 From: scmccallum Date: Wed, 5 Aug 2020 15:27:56 -0400 Subject: [PATCH 03/19] Editorial change to description of mean_occupancy_percentage --- gtfs/spec/en/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 4427f906f..ff0f0a231 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -435,7 +435,7 @@ File: **Optional** | Field Name | Type | Required | Description | | ----- | ----- | ----- | ----- | | `occupancy_id` | ID | **Required** | Identifies an occupancy profile. | -| `mean_occupancy_percentage` | Integer | **Required** | Mean percentage of the `occupancy_type` that is occupied in the vehicle at boarding time.

Valid percentage values are greater than or equal to `0`. The value `100` should represent the total maximum occupancy the vehicle was designed for, according to the `occupancy_type`, and current operating regulations allow.

It is possible that the value goes over `100` if the occupancy is greater than what the vehicle was designed for. The degree of precision should be low enough that you can't track a single rider boarding and alighting for privacy reasons.

A value of `-1` indicates that the vehicle is likely not accepting riders for this `occupancy_type`. | +| `mean_occupancy_percentage` | Integer | **Required** | Mean occupancy percentage of the vehicle at boarding time.

Valid percentage values are greater than or equal to `0`. The value `100` should represent the total maximum occupancy the vehicle was designed for, according to the `occupancy_type`, and current operating regulations allow.

It is possible that the value goes over `100` if the occupancy is greater than what the vehicle was designed for. The degree of precision should be low enough that you can't track a single rider boarding and alighting for privacy reasons.

A value of `-1` indicates that the vehicle is likely not accepting riders for this `occupancy_type`. | | `occupancy_type` | Enum | Optional | Describes the type of occupancy. Valid options are:

`0` or empty - seating and standing occupancy
`1` - riders in a wheelchair
`2` - bikes
`3` - cars

Multiple `occupancy_type` can be defined for the same `occupancy_id`. | | `mean_occupancy_status` | Enum | Conditionally Required | The nominal degree of passenger occupancy for the vehicle. Occupancy status enums as seen in GTFS Realtime for [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus).

`0` - **_EMPTY_**
The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.

`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.

`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.

`3` - **_STANDING_ROOM_ONLY_**
The vehicle can currently accommodate only standing passengers.

`4` - **_CRUSHED_STANDING_ROOM_ONLY_**
The vehicle can currently accommodate only standing passengers and has limited space for them.

`5` - **_FULL_**
The vehicle is considered full by most measures, but may still be allowing passengers to board.

`6` - **_NOT_ACCEPTING_PASSENGERS_**
The vehicle can not accept passengers.

Conditionally Required:
- **Required** if `occupancy_type=0` or empty
- Forbidden otherwise | @@ -447,7 +447,7 @@ File: **Optional** | ----- | ----- | ----- | ----- | | `occupancy_pattern_id` | ID | **Required** | Identifies an occupancy pattern. | | `occupancy_id` | ID referencing `occupancies.occupancy_id` | **Required** | Identifies the occupancy profile for the `occupancy_pattern_id`.

Multiple `occupancy_id` can share the same `occupancy_pattern_id`. | -| `service_id` | ID referencing `calendars.service_id` | Optional | Identifies the day(s) of the week that the occupancy pattern applies. Valid for `service_id` where `calendars.service_type=1`. | +| `service_id` | ID referencing `calendars.service_id` | Optional | Identifies the day(s) of the week that the occupancy pattern applies. Valid for `calendars.service_id` where `calendars.service_type=1`. | | `parent_vehicle_id` | ID referencing `vehicle_couplings.parent_id` | Optional | Identifies a parent vehicle that has 2 or more child vehicles. | | `child_vehicle_sequence` | Non-negative Integer referencing `vehicle_couplings.child_sequence` | Conditionally Required | Denotes the location of the child vehicle from the beginning of the parent vehicle for which the `occupancy_pattern_id` is being described.

Many `child_sequence` may be defined for the same `occupancy_pattern_id`.

The `occupancy_pattern_id` applies to subsequent `child_sequence` for omitted entries.

Conditionally Required if `parent_id` is defined. | From d816fe94a926ce5e3a6f47405e456cba32e130f3 Mon Sep 17 00:00:00 2001 From: Tim Millet Date: Thu, 6 Aug 2020 20:21:04 -0400 Subject: [PATCH 04/19] General edit --- gtfs/spec/en/reference.md | 80 +++++++++++++++++++-------------------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index ff0f0a231..21b518bcc 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -25,12 +25,12 @@ This document defines the format and structure of the files that comprise a GTFS - [transfers.txt](#transferstxt) - [pathways.txt](#pathwaystxt) - [levels.txt](#levelstxt) - - [translations.txt](#translationstxt) - - [feed\_info.txt](#feed_infotxt) - - [attributions.txt](#attributionstxt) - [occupancies.txt](#occupanciestxt) - [occupancy_patterns.txt](#occupancy_patternstxt) - [vehicle_couplings.txt](#vehicle_couplingstxt) + - [translations.txt](#translationstxt) + - [feed\_info.txt](#feed_infotxt) + - [attributions.txt](#attributionstxt) ## Term Definitions @@ -85,12 +85,12 @@ This specification defines the following files: | [transfers.txt](#transferstxt) | Optional | Rules for making connections at transfer points between routes. | | [pathways.txt](#pathwaystxt) | Optional | Pathways linking together locations within stations. | | [levels.txt](#levelstxt) | Optional | Levels within stations. | -| [translations.txt](#translationstxt) | Optional | Translations of customer-facing dataset values. | -| [feed_info.txt](#feed_infotxt) | Optional | Dataset metadata, including publisher, version, and expiration information. | -| [attributions.txt](#attributionstxt) | Optional | Dataset attributions. | | [occupancies.txt](#occupanciestxt) | Optional | Mean occupancy profiles at boarding time. | | [occupancy_patterns.txt](#occupancy_patternstxt) | Optional | Patterns of mean occupancy profiles at boarding time for different days of the week and child vehicles. | | [vehicle_couplings.txt](#vehicle_couplingstxt) | Optional | Defines the arrangement of child vehicles in composed parent vehicles. | +| [translations.txt](#translationstxt) | Optional | Translations of customer-facing dataset values. | +| [feed_info.txt](#feed_infotxt) | Optional | Dataset metadata, including publisher, version, and expiration information. | +| [attributions.txt](#attributionstxt) | Optional | Dataset attributions. | ## File Requirements @@ -220,6 +220,8 @@ File: **Required** | `continuous_drop_off` | Enum | Optional | Indicates that the rider can alight from the transit vehicle at any point along the vehicle’s travel path as described by `shapes.txt`, from this `stop_time` to the next `stop_time` in the trip’s `stop_sequence`. Valid options are:

`0` - Continuous stopping drop off.
`1` or empty - No continuous stopping drop off.
`2` - Must phone agency to arrange continuous stopping drop off.
`3` - Must coordinate with driver to arrange continuous stopping drop off.

If this field is populated, it overrides any continuous drop-off behavior defined in `routes.txt`. If this field is empty, the `stop_time` inherits any continuous drop-off behavior defined in `routes.txt`. | | `shape_dist_traveled` | Non-negative float | Optional | Actual distance traveled along the associated shape, from the first stop to the stop specified in this record. This field specifies how much of the shape to draw between any two stops during a trip. Must be in the same units used in [shapes.txt](#shapestxt). Values used for `shape_dist_traveled` must increase along with `stop_sequence`; they cannot be used to show reverse travel along a route.
*Example: If a bus travels a distance of 5.25 kilometers from the start of the shape to the stop,`shape_dist_traveled`=`5.25`.*| | `timepoint` | Enum | Optional | Indicates if arrival and departure times for a stop are strictly adhered to by the vehicle or if they are instead approximate and/or interpolated times. This field allows a GTFS producer to provide interpolated stop-times, while indicating that the times are approximate. Valid options are:

`0` - Times are considered approximate.
`1` or empty - Times are considered exact. | +| `occupancy_id` | ID referencing `occupancies.occupancy_id` | Optional | Defines the occupancy profile that applies for this `stop_time`. The defined `occupancy_id` will apply to the subsequent `stop_time`s entries if they are undefined.

Either `occupancy_id` or `occupancy_pattern_id` can be specified, but not both. | +| `occupancy_pattern_id` | ID referencing `occupancy_patterns.occupancy_pattern_id` | Optional | Defines the occupancy pattern that applies for this `stop_time`. The defined `occupancy_pattern_id` will apply to the subsequent `stop_time`s entries if they are undefined.

Either `occupancy_id` or `occupancy_pattern_id` can be specified, but not both. | ### calendar.txt @@ -237,7 +239,6 @@ File: **Conditionally required** | `sunday` | Enum | **Required** | Functions in the same way as `monday` except applies to Sundays. | | `start_date` | Date | **Required** | Start service day for the service interval. | | `end_date` | Date | **Required** | End service day for the service interval. This service day is included in the interval. | -| `service_type` | Enum | Optional | Indicates the type of service that the `service_id` is describing. Valid options are:

`0` or empty - The `service_id` is used for describing the days that a trip is in service.
`1` - the `service_id` is used for describing occupancies on different days. ### calendar_dates.txt @@ -373,6 +374,37 @@ Describe the different levels of a station. Is mostly useful when used in conjun | `level_index` | Float | **Required** | Numeric index of the level that indicates relative position of this level in relation to other levels (levels with higher indices are assumed to be located above levels with lower indices).

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 | Optional name of the level (that matches level lettering/numbering used inside the building or the station). Is useful for elevator routing (e.g. “take the elevator to level “Mezzanine” or “Platforms” or “-1”).| +### occupancies.txt + +File: **Optional** + +| Field Name | Type | Required | Description | +| ----- | ----- | ----- | ----- | +| `occupancy_id` | ID | **Required** | Identifies an occupancy profile. | +| `mean_occupancy_percentage` | Integer | **Required** | Describes the mean occupancy percentage of the vehicle at boarding time.

Valid percentage values are greater than or equal to `0`. The value `100` should represent the total maximum occupancy the vehicle was designed for, according to the `occupancy_type`, and current operating regulations allow.

It is possible that the value goes over `100` if the occupancy is greater than what the vehicle was designed for. The degree of precision should be low enough that you can't track a single rider boarding and alighting for privacy reasons.

A value of `-1` indicates that the vehicle is likely not accepting riders for this `occupancy_type`. | +| `mean_occupancy_status` | Enum | **Conditionally Required** | Describes the nominal degree of passenger occupancy for the vehicle. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums.

`0` - Empty. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - Standing room only. The vehicle can currently accommodate only standing passengers.
`4` - Crushed standing room only. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - Full. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - Not accepting passengers. The vehicle can not accept passengers.

Conditionally Required:
- **Required** if `occupancy_type=0`, or if `occupancy_type` is empty or not provided.
- Forbidden otherwise. | +| `occupancy_type` | Enum | Optional | Describes the type of occupancy. Valid options are:

`0` or empty - Seating and standing.
`1` - Riders in a wheelchair.
`2` - Bikes.
`3` - Cars.

Multiple `occupancy_type` can be defined for the same `occupancy_id`.

If this field is not provided, it is assumed the occupancy profile refers to the seating and standing occupancy. | + +### occupancy_patterns.txt + +File: **Optional** + +| Field Name | Type | Required | Description | +| ----- | ----- | ----- | ----- | +| `occupancy_pattern_id` | ID | **Required** | Identifies an occupancy pattern. | +| `occupancy_id` | ID referencing `occupancies.occupancy_id` | **Required** | Identifies the occupancy profile for the `occupancy_pattern_id`.

Multiple `occupancy_id`s can share the same `occupancy_pattern_id`. | +| `service_id` | ID referencing `calendar.service_id` or `calendar_dates.service_id` | Optional | Identifies the date(s) that the occupancy pattern applies. | +| `parent_id` | ID referencing `vehicle_couplings.parent_id` | **Conditionally Required** | Identifies the parent vehicle from which the `child_sequence` refers to.

Conditionally Required:
- **Required** if `child_sequence` is defined.
- Forbidden otherwise. | +| `child_sequence` | Non-negative Integer referencing `vehicle_couplings.child_sequence` | **Conditionally Required** | Identifies the child vehicle for which the `occupancy_pattern_id` is being described.

Many `child_sequence`s may be defined for the same `occupancy_pattern_id`.

Conditionally Required:
- **Required** if `parent_id` is defined.
- Forbidden otherwise. | + +### vehicle_couplings.txt + +File: **Optional** + +| Field Name | Type | Required | Description | +| ----- | ----- | ----- | ----- | +| `parent_id` | ID | **Required** | Identifies the parent vehicle. | +| `child_sequence` | Non-negative Integer | **Required** | Defines the location of the child vehicle in respect to the other child vehicles composing the parent vehicle. The order number must increase along the parent vehicle, from its head to its tail.
_Example: a train composed of 7 carriages can have the following order numbers:
(←Head) 1, 2, 3, 4, 5, 6, 7 (Tail)
(←Head) 4, 10, 105, 206, 333, 806, 1028 (Tail)_ | ### translations.txt @@ -426,36 +458,4 @@ The file defines the attributions applied to the dataset. | `is_authority` | Enum | Optional | Functions in the same way as `is_producer` except the role of the organization is authority. | | `attribution_url` | URL | Optional | URL of the organization. | | `attribution_email` | Email | Optional | Email of the organization. | -| `attribution_phone` | Phone number | Optional | Phone number of the organization. | - -### occupancies.txt - -File: **Optional** - -| Field Name | Type | Required | Description | -| ----- | ----- | ----- | ----- | -| `occupancy_id` | ID | **Required** | Identifies an occupancy profile. | -| `mean_occupancy_percentage` | Integer | **Required** | Mean occupancy percentage of the vehicle at boarding time.

Valid percentage values are greater than or equal to `0`. The value `100` should represent the total maximum occupancy the vehicle was designed for, according to the `occupancy_type`, and current operating regulations allow.

It is possible that the value goes over `100` if the occupancy is greater than what the vehicle was designed for. The degree of precision should be low enough that you can't track a single rider boarding and alighting for privacy reasons.

A value of `-1` indicates that the vehicle is likely not accepting riders for this `occupancy_type`. | -| `occupancy_type` | Enum | Optional | Describes the type of occupancy. Valid options are:

`0` or empty - seating and standing occupancy
`1` - riders in a wheelchair
`2` - bikes
`3` - cars

Multiple `occupancy_type` can be defined for the same `occupancy_id`. | -| `mean_occupancy_status` | Enum | Conditionally Required | The nominal degree of passenger occupancy for the vehicle. Occupancy status enums as seen in GTFS Realtime for [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus).

`0` - **_EMPTY_**
The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.

`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.

`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.

`3` - **_STANDING_ROOM_ONLY_**
The vehicle can currently accommodate only standing passengers.

`4` - **_CRUSHED_STANDING_ROOM_ONLY_**
The vehicle can currently accommodate only standing passengers and has limited space for them.

`5` - **_FULL_**
The vehicle is considered full by most measures, but may still be allowing passengers to board.

`6` - **_NOT_ACCEPTING_PASSENGERS_**
The vehicle can not accept passengers.

Conditionally Required:
- **Required** if `occupancy_type=0` or empty
- Forbidden otherwise | - -### occupancy_patterns.txt - -File: **Optional** - -| Field Name | Type | Required | Description | -| ----- | ----- | ----- | ----- | -| `occupancy_pattern_id` | ID | **Required** | Identifies an occupancy pattern. | -| `occupancy_id` | ID referencing `occupancies.occupancy_id` | **Required** | Identifies the occupancy profile for the `occupancy_pattern_id`.

Multiple `occupancy_id` can share the same `occupancy_pattern_id`. | -| `service_id` | ID referencing `calendars.service_id` | Optional | Identifies the day(s) of the week that the occupancy pattern applies. Valid for `calendars.service_id` where `calendars.service_type=1`. | -| `parent_vehicle_id` | ID referencing `vehicle_couplings.parent_id` | Optional | Identifies a parent vehicle that has 2 or more child vehicles. | -| `child_vehicle_sequence` | Non-negative Integer referencing `vehicle_couplings.child_sequence` | Conditionally Required | Denotes the location of the child vehicle from the beginning of the parent vehicle for which the `occupancy_pattern_id` is being described.

Many `child_sequence` may be defined for the same `occupancy_pattern_id`.

The `occupancy_pattern_id` applies to subsequent `child_sequence` for omitted entries.

Conditionally Required if `parent_id` is defined. | - -### vehicle_couplings.txt - -File: **Optional** - -| Field Name | Type | Required | Description | -| ----- | ----- | ----- | ----- | -| `parent_vehicle_id` | ID | **Required** | Identifies a parent vehicle with 2 or more child vehicles. | -| `child_vehicle_sequence` | Non-negative Integer | **Required** | Denotes the location of the child vehicle from the beginning of the parent vehicle. The order number must be a non-negative integer increasing along the vehicle. | \ No newline at end of file +| `attribution_phone` | Phone number | Optional | Phone number of the organization. | \ No newline at end of file From 12e66920baae5fe94b9a98fe6f39b36f34ef0a62 Mon Sep 17 00:00:00 2001 From: Tim Millet Date: Thu, 6 Aug 2020 20:35:32 -0400 Subject: [PATCH 05/19] Add file descriptions + add precision in mean_occupancy_status --- gtfs/spec/en/reference.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 21b518bcc..57a7723c2 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -378,17 +378,21 @@ Describe the different levels of a station. Is mostly useful when used in conjun File: **Optional** +The file describes mean occupancy profiles of vehicles at boarding time. + | Field Name | Type | Required | Description | | ----- | ----- | ----- | ----- | | `occupancy_id` | ID | **Required** | Identifies an occupancy profile. | | `mean_occupancy_percentage` | Integer | **Required** | Describes the mean occupancy percentage of the vehicle at boarding time.

Valid percentage values are greater than or equal to `0`. The value `100` should represent the total maximum occupancy the vehicle was designed for, according to the `occupancy_type`, and current operating regulations allow.

It is possible that the value goes over `100` if the occupancy is greater than what the vehicle was designed for. The degree of precision should be low enough that you can't track a single rider boarding and alighting for privacy reasons.

A value of `-1` indicates that the vehicle is likely not accepting riders for this `occupancy_type`. | -| `mean_occupancy_status` | Enum | **Conditionally Required** | Describes the nominal degree of passenger occupancy for the vehicle. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums.

`0` - Empty. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - Standing room only. The vehicle can currently accommodate only standing passengers.
`4` - Crushed standing room only. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - Full. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - Not accepting passengers. The vehicle can not accept passengers.

Conditionally Required:
- **Required** if `occupancy_type=0`, or if `occupancy_type` is empty or not provided.
- Forbidden otherwise. | +| `mean_occupancy_status` | Enum | **Conditionally Required** | Describes the nominal degree of rider occupancy for the vehicle at boarding time. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums.

`0` - Empty. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - Standing room only. The vehicle can currently accommodate only standing passengers.
`4` - Crushed standing room only. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - Full. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - Not accepting passengers. The vehicle can not accept passengers.

Conditionally Required:
- **Required** if `occupancy_type=0`, or if `occupancy_type` is empty or not provided.
- Forbidden otherwise. | | `occupancy_type` | Enum | Optional | Describes the type of occupancy. Valid options are:

`0` or empty - Seating and standing.
`1` - Riders in a wheelchair.
`2` - Bikes.
`3` - Cars.

Multiple `occupancy_type` can be defined for the same `occupancy_id`.

If this field is not provided, it is assumed the occupancy profile refers to the seating and standing occupancy. | ### occupancy_patterns.txt File: **Optional** +The file describes patterns of mean occupancy per date and/or per child vehicle. + | Field Name | Type | Required | Description | | ----- | ----- | ----- | ----- | | `occupancy_pattern_id` | ID | **Required** | Identifies an occupancy pattern. | @@ -401,6 +405,8 @@ File: **Optional** File: **Optional** +The file describes the arrangement of child vehicles in composed parent vehicles. + | Field Name | Type | Required | Description | | ----- | ----- | ----- | ----- | | `parent_id` | ID | **Required** | Identifies the parent vehicle. | From 54ec83e067ac5a61ecfa09ba7fdaa9e4c138ae87 Mon Sep 17 00:00:00 2001 From: scmccallum Date: Fri, 20 Nov 2020 10:27:37 -0500 Subject: [PATCH 06/19] PR update to Option C PR update to Option C as appears in the GTFS-Occupancies proposal working document, replacing Option A. --- gtfs/spec/en/reference.md | 51 ++++++++++++++------------------------- 1 file changed, 18 insertions(+), 33 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 57a7723c2..19987ff19 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -26,8 +26,6 @@ This document defines the format and structure of the files that comprise a GTFS - [pathways.txt](#pathwaystxt) - [levels.txt](#levelstxt) - [occupancies.txt](#occupanciestxt) - - [occupancy_patterns.txt](#occupancy_patternstxt) - - [vehicle_couplings.txt](#vehicle_couplingstxt) - [translations.txt](#translationstxt) - [feed\_info.txt](#feed_infotxt) - [attributions.txt](#attributionstxt) @@ -85,9 +83,7 @@ This specification defines the following files: | [transfers.txt](#transferstxt) | Optional | Rules for making connections at transfer points between routes. | | [pathways.txt](#pathwaystxt) | Optional | Pathways linking together locations within stations. | | [levels.txt](#levelstxt) | Optional | Levels within stations. | -| [occupancies.txt](#occupanciestxt) | Optional | Mean occupancy profiles at boarding time. | -| [occupancy_patterns.txt](#occupancy_patternstxt) | Optional | Patterns of mean occupancy profiles at boarding time for different days of the week and child vehicles. | -| [vehicle_couplings.txt](#vehicle_couplingstxt) | Optional | Defines the arrangement of child vehicles in composed parent vehicles. | +| [occupancies.txt](#occupanciestxt) | Optional | Expected or usual in-vehicle occupancy levels. | | [translations.txt](#translationstxt) | Optional | Translations of customer-facing dataset values. | | [feed_info.txt](#feed_infotxt) | Optional | Dataset metadata, including publisher, version, and expiration information. | | [attributions.txt](#attributionstxt) | Optional | Dataset attributions. | @@ -378,39 +374,28 @@ Describe the different levels of a station. Is mostly useful when used in conjun File: **Optional** -The file describes mean occupancy profiles of vehicles at boarding time. +Expected or usual in-vehicle occupancy levels. -| Field Name | Type | Required | Description | -| ----- | ----- | ----- | ----- | -| `occupancy_id` | ID | **Required** | Identifies an occupancy profile. | -| `mean_occupancy_percentage` | Integer | **Required** | Describes the mean occupancy percentage of the vehicle at boarding time.

Valid percentage values are greater than or equal to `0`. The value `100` should represent the total maximum occupancy the vehicle was designed for, according to the `occupancy_type`, and current operating regulations allow.

It is possible that the value goes over `100` if the occupancy is greater than what the vehicle was designed for. The degree of precision should be low enough that you can't track a single rider boarding and alighting for privacy reasons.

A value of `-1` indicates that the vehicle is likely not accepting riders for this `occupancy_type`. | -| `mean_occupancy_status` | Enum | **Conditionally Required** | Describes the nominal degree of rider occupancy for the vehicle at boarding time. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums.

`0` - Empty. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - Standing room only. The vehicle can currently accommodate only standing passengers.
`4` - Crushed standing room only. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - Full. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - Not accepting passengers. The vehicle can not accept passengers.

Conditionally Required:
- **Required** if `occupancy_type=0`, or if `occupancy_type` is empty or not provided.
- Forbidden otherwise. | -| `occupancy_type` | Enum | Optional | Describes the type of occupancy. Valid options are:

`0` or empty - Seating and standing.
`1` - Riders in a wheelchair.
`2` - Bikes.
`3` - Cars.

Multiple `occupancy_type` can be defined for the same `occupancy_id`.

If this field is not provided, it is assumed the occupancy profile refers to the seating and standing occupancy. | - -### occupancy_patterns.txt - -File: **Optional** - -The file describes patterns of mean occupancy per date and/or per child vehicle. - -| Field Name | Type | Required | Description | -| ----- | ----- | ----- | ----- | -| `occupancy_pattern_id` | ID | **Required** | Identifies an occupancy pattern. | -| `occupancy_id` | ID referencing `occupancies.occupancy_id` | **Required** | Identifies the occupancy profile for the `occupancy_pattern_id`.

Multiple `occupancy_id`s can share the same `occupancy_pattern_id`. | -| `service_id` | ID referencing `calendar.service_id` or `calendar_dates.service_id` | Optional | Identifies the date(s) that the occupancy pattern applies. | -| `parent_id` | ID referencing `vehicle_couplings.parent_id` | **Conditionally Required** | Identifies the parent vehicle from which the `child_sequence` refers to.

Conditionally Required:
- **Required** if `child_sequence` is defined.
- Forbidden otherwise. | -| `child_sequence` | Non-negative Integer referencing `vehicle_couplings.child_sequence` | **Conditionally Required** | Identifies the child vehicle for which the `occupancy_pattern_id` is being described.

Many `child_sequence`s may be defined for the same `occupancy_pattern_id`.

Conditionally Required:
- **Required** if `parent_id` is defined.
- Forbidden otherwise. | - -### vehicle_couplings.txt - -File: **Optional** +For describing historical average occupancies (`occupancies.date_source=0`), at least 4 weeks is suggested to average occupancy data across each unique day of the week, valid for up to 2 weeks thereafter in `occupancies.txt`. -The file describes the arrangement of child vehicles in composed parent vehicles. +Methods of occupancy forecasting as input into `occupancies.txt` are not strictly specified. Beyond the guidelines given above, it is the responsibility of data producers to ensure that the data provided are meaningful to riders. | Field Name | Type | Required | Description | | ----- | ----- | ----- | ----- | -| `parent_id` | ID | **Required** | Identifies the parent vehicle. | -| `child_sequence` | Non-negative Integer | **Required** | Defines the location of the child vehicle in respect to the other child vehicles composing the parent vehicle. The order number must increase along the parent vehicle, from its head to its tail.
_Example: a train composed of 7 carriages can have the following order numbers:
(←Head) 1, 2, 3, 4, 5, 6, 7 (Tail)
(←Head) 4, 10, 105, 206, 333, 806, 1028 (Tail)_ | +| `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` | **Conditionally Required** | Identifies a `stop_sequence` along `occupancies.trip_id` for which an occupancy level is described.

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`.

Conditionally Required:
- **Forbidden** if `occupancies.trip_id` is empty. | +| `occupancy_status` | Enum | **Required** | Indicates the nominal degree of in-vehicle occupancy. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums. Valid options are:

`0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - **Standing room only**. The vehicle can currently accommodate only standing passengers.
`4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - **Not accepting passengers**. The vehicle can not accept passengers. | +| `occupancy_percentage` | Integer | Optional | Indicates in-vehicle occupancy as a percentage.

Valid percentage values are greater than or equal to `0`. The value `100` should represent the maximum occupancy the vehicle was designed for, and current operating regulations allow. It is possible that the value goes over `100` if the occupancy is greater than what the vehicle was designed for.

The degree of precision should be low enough such that you cannot track where a single rider is boarding or alighting.

A value of `-1` indicates that the vehicle is full and likely not accepting riders. | +| `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:

`1` - The occupancy level applies for all Mondays in the date range.
`0` - 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. | +| `end_date` | Date | **Required** | End date of the date interval that the occupancy level is valid. | +| `data_source` | Enum | **Required** | Indicates the source of the data that were used to populate `occupancies.occupancy_status` or `occupancies.occupancy_percentage`.

If necessary, further methodological details can be communicated directly between data producers and data consumers. Valid options are:

`0` - Historical average.
`1` - Modeled predictions. | ### translations.txt From 1ea4b35ecc7c1bdec306c4319f1752833622351d Mon Sep 17 00:00:00 2001 From: scmccallum Date: Fri, 20 Nov 2020 10:39:51 -0500 Subject: [PATCH 07/19] Minor editorial corrections Minor editorial corrections to syntax of some text. --- gtfs/spec/en/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 19987ff19..34ea813d7 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -376,14 +376,14 @@ File: **Optional** Expected or usual in-vehicle occupancy levels. -For describing historical average occupancies (`occupancies.date_source=0`), at least 4 weeks is suggested to average occupancy data across each unique day of the week, valid for up to 2 weeks thereafter in `occupancies.txt`. +For describing historical average occupancies (`occupancies.date_source=0`) at least 4 weeks of occupancy data are suggested to be averaged across each unique day of the week, valid for up to 2 weeks thereafter in `occupancies.txt`. Methods of occupancy forecasting as input into `occupancies.txt` are not strictly specified. Beyond the guidelines given above, it is the responsibility of data producers to ensure that the data provided are meaningful to riders. | 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` | **Conditionally Required** | Identifies a `stop_sequence` along `occupancies.trip_id` for which an occupancy level is described.

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`.

Conditionally Required:
- **Forbidden** if `occupancies.trip_id` is empty. | +| `stop_sequence` | ID referencing `stop_times.stop_sequence` | **Conditionally Required** | Identifies a `stop_sequence` along `occupancies.trip_id` for which an occupancy level is described.

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`.

Conditionally Required:
- **Forbidden** if `occupancies.trip_id` is empty. | | `occupancy_status` | Enum | **Required** | Indicates the nominal degree of in-vehicle occupancy. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums. Valid options are:

`0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - **Standing room only**. The vehicle can currently accommodate only standing passengers.
`4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - **Not accepting passengers**. The vehicle can not accept passengers. | | `occupancy_percentage` | Integer | Optional | Indicates in-vehicle occupancy as a percentage.

Valid percentage values are greater than or equal to `0`. The value `100` should represent the maximum occupancy the vehicle was designed for, and current operating regulations allow. It is possible that the value goes over `100` if the occupancy is greater than what the vehicle was designed for.

The degree of precision should be low enough such that you cannot track where a single rider is boarding or alighting.

A value of `-1` indicates that the vehicle is full and likely not accepting riders. | | `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:

`1` - The occupancy level applies for all Mondays in the date range.
`0` - The occupancy level does not apply for all Mondays in the date range. | From 716d19224a9209bb728ed6c8be9de10617ff279e Mon Sep 17 00:00:00 2001 From: scmccallum Date: Fri, 20 Nov 2020 16:53:30 -0500 Subject: [PATCH 08/19] Remove Option A leftover Removal of fields that were apart of the Option A proposal, but are no longer relevant for Option C. --- gtfs/spec/en/reference.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 34ea813d7..d90219174 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -216,8 +216,6 @@ File: **Required** | `continuous_drop_off` | Enum | Optional | Indicates that the rider can alight from the transit vehicle at any point along the vehicle’s travel path as described by `shapes.txt`, from this `stop_time` to the next `stop_time` in the trip’s `stop_sequence`. Valid options are:

`0` - Continuous stopping drop off.
`1` or empty - No continuous stopping drop off.
`2` - Must phone agency to arrange continuous stopping drop off.
`3` - Must coordinate with driver to arrange continuous stopping drop off.

If this field is populated, it overrides any continuous drop-off behavior defined in `routes.txt`. If this field is empty, the `stop_time` inherits any continuous drop-off behavior defined in `routes.txt`. | | `shape_dist_traveled` | Non-negative float | Optional | Actual distance traveled along the associated shape, from the first stop to the stop specified in this record. This field specifies how much of the shape to draw between any two stops during a trip. Must be in the same units used in [shapes.txt](#shapestxt). Values used for `shape_dist_traveled` must increase along with `stop_sequence`; they cannot be used to show reverse travel along a route.
*Example: If a bus travels a distance of 5.25 kilometers from the start of the shape to the stop,`shape_dist_traveled`=`5.25`.*| | `timepoint` | Enum | Optional | Indicates if arrival and departure times for a stop are strictly adhered to by the vehicle or if they are instead approximate and/or interpolated times. This field allows a GTFS producer to provide interpolated stop-times, while indicating that the times are approximate. Valid options are:

`0` - Times are considered approximate.
`1` or empty - Times are considered exact. | -| `occupancy_id` | ID referencing `occupancies.occupancy_id` | Optional | Defines the occupancy profile that applies for this `stop_time`. The defined `occupancy_id` will apply to the subsequent `stop_time`s entries if they are undefined.

Either `occupancy_id` or `occupancy_pattern_id` can be specified, but not both. | -| `occupancy_pattern_id` | ID referencing `occupancy_patterns.occupancy_pattern_id` | Optional | Defines the occupancy pattern that applies for this `stop_time`. The defined `occupancy_pattern_id` will apply to the subsequent `stop_time`s entries if they are undefined.

Either `occupancy_id` or `occupancy_pattern_id` can be specified, but not both. | ### calendar.txt From cb183e77fcfdebb97204d10e81a6d0b1cdfd06ac Mon Sep 17 00:00:00 2001 From: scmccallum Date: Thu, 26 Nov 2020 12:22:31 -0500 Subject: [PATCH 09/19] Single-date occupancy predictions (Option B) (1) Removed weekly pattern structure (Option C) in favor of individual date structure (Option B). (2) Edit of `occupancy_percentage` to bring it in technical conformity with the GTFS Realtime description. --- gtfs/spec/en/reference.md | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index d90219174..43c26c599 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -372,27 +372,19 @@ Describe the different levels of a station. Is mostly useful when used in conjun File: **Optional** -Expected or usual in-vehicle occupancy levels. +Usual or expected in-vehicle occupancy levels. For describing historical average occupancies (`occupancies.date_source=0`) at least 4 weeks of occupancy data are suggested to be averaged across each unique day of the week, valid for up to 2 weeks thereafter in `occupancies.txt`. -Methods of occupancy forecasting as input into `occupancies.txt` are not strictly specified. Beyond the guidelines given above, it is the responsibility of data producers to ensure that the data provided are meaningful to riders. +Methods of occupancy forecasting used to populated `occupancies.txt` are not strictly specified. Beyond the guidelines given above, it is the responsibility of data producers to ensure that the data provided are meaningful. | 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` | **Conditionally Required** | Identifies a `stop_sequence` along `occupancies.trip_id` for which an occupancy level is described.

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`.

Conditionally Required:
- **Forbidden** if `occupancies.trip_id` is empty. | | `occupancy_status` | Enum | **Required** | Indicates the nominal degree of in-vehicle occupancy. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums. Valid options are:

`0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - **Standing room only**. The vehicle can currently accommodate only standing passengers.
`4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - **Not accepting passengers**. The vehicle can not accept passengers. | -| `occupancy_percentage` | Integer | Optional | Indicates in-vehicle occupancy as a percentage.

Valid percentage values are greater than or equal to `0`. The value `100` should represent the maximum occupancy the vehicle was designed for, and current operating regulations allow. It is possible that the value goes over `100` if the occupancy is greater than what the vehicle was designed for.

The degree of precision should be low enough such that you cannot track where a single rider is boarding or alighting.

A value of `-1` indicates that the vehicle is full and likely not accepting riders. | -| `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:

`1` - The occupancy level applies for all Mondays in the date range.
`0` - 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. | -| `end_date` | Date | **Required** | End date of the date interval that the occupancy level is valid. | +| `occupancy_percentage` | Integer | Optional | Indicates in-vehicle occupancy as a percentage.

Valid percentage values are greater than or equal to `0`. The value `100` should represent the maximum occupancy the vehicle was designed for, and current operating regulations allow. It is possible that the value goes over `100` if the occupancy is greater than what the vehicle was designed for.

The degree of precision should be low enough such that you cannot track where a single rider is boarding or alighting. | +| `date` | Date | **Required** | Date of the usual or expected in-vehicle occupancy level. | | `data_source` | Enum | **Required** | Indicates the source of the data that were used to populate `occupancies.occupancy_status` or `occupancies.occupancy_percentage`.

If necessary, further methodological details can be communicated directly between data producers and data consumers. Valid options are:

`0` - Historical average.
`1` - Modeled predictions. | ### translations.txt From 6dcb9eabf8af6335dbd30d657c8a4f028c6711db Mon Sep 17 00:00:00 2001 From: scmccallum Date: Thu, 26 Nov 2020 12:29:43 -0500 Subject: [PATCH 10/19] Clarification to `date` field --- gtfs/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 43c26c599..49c7bc892 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -384,7 +384,7 @@ Methods of occupancy forecasting used to populated `occupancies.txt` are not str | `stop_sequence` | ID referencing `stop_times.stop_sequence` | **Conditionally Required** | Identifies a `stop_sequence` along `occupancies.trip_id` for which an occupancy level is described.

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`.

Conditionally Required:
- **Forbidden** if `occupancies.trip_id` is empty. | | `occupancy_status` | Enum | **Required** | Indicates the nominal degree of in-vehicle occupancy. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums. Valid options are:

`0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - **Standing room only**. The vehicle can currently accommodate only standing passengers.
`4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - **Not accepting passengers**. The vehicle can not accept passengers. | | `occupancy_percentage` | Integer | Optional | Indicates in-vehicle occupancy as a percentage.

Valid percentage values are greater than or equal to `0`. The value `100` should represent the maximum occupancy the vehicle was designed for, and current operating regulations allow. It is possible that the value goes over `100` if the occupancy is greater than what the vehicle was designed for.

The degree of precision should be low enough such that you cannot track where a single rider is boarding or alighting. | -| `date` | Date | **Required** | Date of the usual or expected in-vehicle occupancy level. | +| `date` | Date | **Required** | Date that the usual or expected in-vehicle occupancy level is projected. | | `data_source` | Enum | **Required** | Indicates the source of the data that were used to populate `occupancies.occupancy_status` or `occupancies.occupancy_percentage`.

If necessary, further methodological details can be communicated directly between data producers and data consumers. Valid options are:

`0` - Historical average.
`1` - Modeled predictions. | ### translations.txt From 455790221d918e4e2a7da671cb3a8d42bf15c036 Mon Sep 17 00:00:00 2001 From: scmccallum Date: Tue, 8 Dec 2020 11:51:06 -0500 Subject: [PATCH 11/19] Option D - Occupancy descriptions at individual date or weekly pattern level that accomodates either approach efficiently. - Removal of `occupancy_percentage` until further needs are expressed. - Removal of `data_source`. - Added `occupancies.exception` to be able to describe occupancy exceptions to weekly pattern. - Added "Conditionally Forbidden" Term Definition. - Updated wording to "Conditionally Required" for semantic clarity. --- gtfs/spec/en/reference.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 49c7bc892..789e5fbfe 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -40,7 +40,8 @@ This section defines terms that are used throughout this document. * **Field Value** - An individual entry in a field. Represented, in a table, as a single cell. * **Required** - The field must be included in the dataset, and a value must be provided in that field for each record. Some required fields permit an empty string as a value (denoted in this specification as empty). To enter an empty string, just omit any text between the commas for that field. * **Optional** - The field may be omitted from the dataset. If an optional column is included, some of the entries in that field may be empty strings. To enter an empty string, just omit any text between the commas for that field. Note that an omitted field is equivalent to a field that is entirely empty. -* **Conditionally required** - The field or file is required under certain conditions, which are outlined in the field or file description. Outside of these conditions, this field or file is optional. +* **Conditionally required** - The field or file is required under conditions that are outlined in the field or file description. Outside of these conditions, this field or file is optional. +* **Conditionally forbidden** - The field or file is forbidden under conditions that are outlined in the field or file description. Outside of these conditions, the field or file is optional. * **Service day** - A service day is a time period used to indicate route scheduling. The exact definition of service day varies from agency to agency but service days often do not correspond with calendar days. A service day may exceed 24:00:00 if service begins on one day and ends on a following day. For example, service that runs from 08:00:00 on Friday to 02:00:00 on Saturday, could be denoted as running from 08:00:00 to 26:00:00 on a single service day. * **Text-to-speech field** - The field should contain the same information than its parent field (on which it falls back if it is empty). It is aimed to be read as text-to-speech, therefore, abbreviation should be either removed ("St" should be either read as "Street" or "Saint"; "Elizabeth I" should be "Elizabeth the first") or kept to be read as it ("JFK Airport" is said abbreviated). @@ -381,12 +382,18 @@ Methods of occupancy forecasting used to populated `occupancies.txt` are not str | 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` | **Conditionally Required** | Identifies a `stop_sequence` along `occupancies.trip_id` for which an occupancy level is described.

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`.

Conditionally Required:
- **Forbidden** if `occupancies.trip_id` is empty. | +| `stop_sequence` | ID referencing `stop_times.stop_sequence` | Optional | Identifies a `stop_sequence` along `occupancies.trip_id` for which an occupancy level is described.

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 nominal degree of in-vehicle occupancy. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums. Valid options are:

`0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - **Standing room only**. The vehicle can currently accommodate only standing passengers.
`4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - **Not accepting passengers**. The vehicle can not accept passengers. | -| `occupancy_percentage` | Integer | Optional | Indicates in-vehicle occupancy as a percentage.

Valid percentage values are greater than or equal to `0`. The value `100` should represent the maximum occupancy the vehicle was designed for, and current operating regulations allow. It is possible that the value goes over `100` if the occupancy is greater than what the vehicle was designed for.

The degree of precision should be low enough such that you cannot track where a single rider is boarding or alighting. | -| `date` | Date | **Required** | Date that the usual or expected in-vehicle occupancy level is projected. | -| `data_source` | Enum | **Required** | Indicates the source of the data that were used to populate `occupancies.occupancy_status` or `occupancies.occupancy_percentage`.

If necessary, further methodological details can be communicated directly between data producers and data consumers. Valid options are:

`0` - Historical average.
`1` - Modeled predictions. | - +| `monday` | Enum | **Conditionally Forbidden** | 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:

`1` - The occupancy level applies for all Mondays in the date range.
`0` - The occupancy level does not apply for all Mondays in the date range.

**Conditionally Forbidden**:
- **Forbidden** if `occupancies.end_date` is empty.
- Optional otherwise. | +| `tuesday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Tuesdays. | +| `wednesday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Wednesdays. | +| `thursday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Thursdays. | +| `friday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Fridays. | +| `saturday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Saturdays. | +| `sunday` | Enum| **Conditionally Forbidden** | 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. | +| `end_date` | Date | Optional | End date of the date interval that the occupancy level is valid.

If defined, `occupancies.end_date` must be greater than `occupancies.start_date`.

If empty, the occupancy level will apply only for the date specified in `occupancies.start_date`. | +| `exception` | Enum | Optional | Indicates if an occupancy exception should override an existing occupancy description for the same trip or stop time for overlapping dates. Valid options are:

`0` or empty - Does not override an occupancy description.
`1` - Overrides an occupancy description. ### translations.txt File: **Optional** From d99a6276344fe09d3e650f04cb6c766c8cded9ad Mon Sep 17 00:00:00 2001 From: scmccallum Date: Tue, 8 Dec 2020 15:53:49 -0500 Subject: [PATCH 12/19] Added 0 "or empty" to days Added "or empty" to date descriptions --- gtfs/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 789e5fbfe..a46c61118 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -384,7 +384,7 @@ Methods of occupancy forecasting used to populated `occupancies.txt` are not str | `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.

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 nominal degree of in-vehicle occupancy. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums. Valid options are:

`0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - **Standing room only**. The vehicle can currently accommodate only standing passengers.
`4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - **Not accepting passengers**. The vehicle can not accept passengers. | -| `monday` | Enum | **Conditionally Forbidden** | 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:

`1` - The occupancy level applies for all Mondays in the date range.
`0` - The occupancy level does not apply for all Mondays in the date range.

**Conditionally Forbidden**:
- **Forbidden** if `occupancies.end_date` is empty.
- Optional otherwise. | +| `monday` | Enum | **Conditionally Forbidden** | 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:

`1` - The occupancy level applies for all Mondays in the date range.
`0` or empty - The occupancy level does not apply for all Mondays in the date range.

**Conditionally Forbidden**:
- **Forbidden** if `occupancies.end_date` is empty.
- Optional otherwise. | | `tuesday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Tuesdays. | | `wednesday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Wednesdays. | | `thursday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Thursdays. | From 92a8b02f96e32f6d7a8dc21b433c1791921ec309 Mon Sep 17 00:00:00 2001 From: scmcca Date: Mon, 1 Feb 2021 12:58:46 -0500 Subject: [PATCH 13/19] Update reference.md --- gtfs/spec/en/reference.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index a46c61118..91f205de2 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -375,9 +375,9 @@ File: **Optional** Usual or expected in-vehicle occupancy levels. -For describing historical average occupancies (`occupancies.date_source=0`) at least 4 weeks of occupancy data are suggested to be averaged across each unique day of the week, valid for up to 2 weeks thereafter in `occupancies.txt`. +For describing historical average occupancies at least 4 weeks of occupancy data are suggested to be averaged across each unique day of the week, valid for up to 2 weeks thereafter in `occupancies.txt`. -Methods of occupancy forecasting used to populated `occupancies.txt` are not strictly specified. Beyond the guidelines given above, it is the responsibility of data producers to ensure that the data provided are meaningful. +Methods for occupancy forecasting used to populated `occupancies.txt` are not strictly specified. Beyond the guidelines given above, it is the responsibility of data producers to ensure that the data provided are meaningful. | Field Name | Type | Required | Description | | ----- | ----- | ----- | ----- | @@ -446,4 +446,4 @@ The file defines the attributions applied to the dataset. | `is_authority` | Enum | Optional | Functions in the same way as `is_producer` except the role of the organization is authority. | | `attribution_url` | URL | Optional | URL of the organization. | | `attribution_email` | Email | Optional | Email of the organization. | -| `attribution_phone` | Phone number | Optional | Phone number of the organization. | \ No newline at end of file +| `attribution_phone` | Phone number | Optional | Phone number of the organization. | From 8eba8b933ecd398760535d5f3c63aac038858057 Mon Sep 17 00:00:00 2001 From: scmcca Date: Mon, 1 Feb 2021 13:10:36 -0500 Subject: [PATCH 14/19] Update reference.md --- gtfs/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 91f205de2..60510023d 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -382,7 +382,7 @@ Methods for occupancy forecasting used to populated `occupancies.txt` are not st | 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.

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`. | +| `stop_sequence` | ID referencing `stop_times.stop_sequence` | **Conditionally Forbidden** | Identifies a `stop_sequence` along `occupancies.trip_id` for which an occupancy level is described.

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`.

**Conditionally Forbidden**
- **Forbidden** if `occupancies.trip_id` is empty.
- Optional otherwise. | | `occupancy_status` | Enum | **Required** | Indicates the nominal degree of in-vehicle occupancy. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums. Valid options are:

`0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - **Standing room only**. The vehicle can currently accommodate only standing passengers.
`4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - **Not accepting passengers**. The vehicle can not accept passengers. | | `monday` | Enum | **Conditionally Forbidden** | 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:

`1` - The occupancy level applies for all Mondays in the date range.
`0` or empty - The occupancy level does not apply for all Mondays in the date range.

**Conditionally Forbidden**:
- **Forbidden** if `occupancies.end_date` is empty.
- Optional otherwise. | | `tuesday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Tuesdays. | From 51d273ebc15a73722b0a9af4b4ff687bbb65a5f8 Mon Sep 17 00:00:00 2001 From: scmcca Date: Fri, 17 Sep 2021 11:10:00 -0400 Subject: [PATCH 15/19] modeling updates - require `end_date` - patch `stop_sequence` to optional - remove `exception` --- gtfs/spec/en/reference.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 60510023d..3101fd714 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -41,7 +41,6 @@ This section defines terms that are used throughout this document. * **Required** - The field must be included in the dataset, and a value must be provided in that field for each record. Some required fields permit an empty string as a value (denoted in this specification as empty). To enter an empty string, just omit any text between the commas for that field. * **Optional** - The field may be omitted from the dataset. If an optional column is included, some of the entries in that field may be empty strings. To enter an empty string, just omit any text between the commas for that field. Note that an omitted field is equivalent to a field that is entirely empty. * **Conditionally required** - The field or file is required under conditions that are outlined in the field or file description. Outside of these conditions, this field or file is optional. -* **Conditionally forbidden** - The field or file is forbidden under conditions that are outlined in the field or file description. Outside of these conditions, the field or file is optional. * **Service day** - A service day is a time period used to indicate route scheduling. The exact definition of service day varies from agency to agency but service days often do not correspond with calendar days. A service day may exceed 24:00:00 if service begins on one day and ends on a following day. For example, service that runs from 08:00:00 on Friday to 02:00:00 on Saturday, could be denoted as running from 08:00:00 to 26:00:00 on a single service day. * **Text-to-speech field** - The field should contain the same information than its parent field (on which it falls back if it is empty). It is aimed to be read as text-to-speech, therefore, abbreviation should be either removed ("St" should be either read as "Street" or "Saint"; "Elizabeth I" should be "Elizabeth the first") or kept to be read as it ("JFK Airport" is said abbreviated). @@ -375,25 +374,25 @@ File: **Optional** Usual or expected in-vehicle occupancy levels. -For describing historical average occupancies at least 4 weeks of occupancy data are suggested to be averaged across each unique day of the week, valid for up to 2 weeks thereafter in `occupancies.txt`. +For describing historical average occupancies at least 4 weeks of occupancy data should be averaged across each unique day of the week, valid for up to 2 weeks thereafter in `occupancies.txt`. Methods for occupancy forecasting used to populated `occupancies.txt` are not strictly specified. Beyond the guidelines given above, it is the responsibility of data producers to ensure that the data provided are meaningful. | 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` | **Conditionally Forbidden** | Identifies a `stop_sequence` along `occupancies.trip_id` for which an occupancy level is described.

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`.

**Conditionally Forbidden**
- **Forbidden** if `occupancies.trip_id` is empty.
- Optional otherwise. | -| `occupancy_status` | Enum | **Required** | Indicates the nominal degree of in-vehicle occupancy. This field refers to the GTFS Realtime [`OccupancyStatus`](http://gtfs.org/reference/realtime/v2/#enum-occupancystatus) enums. Valid options are:

`0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - **Standing room only**. The vehicle can currently accommodate only standing passengers.
`4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - **Not accepting passengers**. The vehicle can not accept passengers. | -| `monday` | Enum | **Conditionally Forbidden** | 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:

`1` - The occupancy level applies for all Mondays in the date range.
`0` or empty - The occupancy level does not apply for all Mondays in the date range.

**Conditionally Forbidden**:
- **Forbidden** if `occupancies.end_date` is empty.
- Optional otherwise. | -| `tuesday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Tuesdays. | -| `wednesday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Wednesdays. | -| `thursday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Thursdays. | -| `friday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Fridays. | -| `saturday` | Enum| **Conditionally Forbidden** | Functions in the same way as `occupancies.monday` except applies to Saturdays. | -| `sunday` | Enum| **Conditionally Forbidden** | 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. | -| `end_date` | Date | Optional | End date of the date interval that the occupancy level is valid.

If defined, `occupancies.end_date` must be greater than `occupancies.start_date`.

If empty, the occupancy level will apply only for the date specified in `occupancies.start_date`. | -| `exception` | Enum | Optional | Indicates if an occupancy exception should override an existing occupancy description for the same trip or stop time for overlapping dates. Valid options are:

`0` or empty - Does not override an occupancy description.
`1` - Overrides an occupancy description. +| `stop_sequence` | ID referencing `stop_times.stop_sequence` | Optional | Identifies a `stop_sequence` along `occupancies.trip_id` for which an occupancy level is described.

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:

`0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - **Standing room only**. The vehicle can currently accommodate only standing passengers.
`4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - **Not accepting passengers**. The vehicle can not accept passengers. | +| `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:

`1` - The occupancy level applies for all Mondays in the date range.
`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.

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.

To define single dates, `start_date` and `end_date` may be the same. | + ### translations.txt File: **Optional** From b23784cdb9dcb1001eb70bd55dd9b2aa296bf056 Mon Sep 17 00:00:00 2001 From: scott christian mccallum Date: Mon, 20 Sep 2021 10:13:33 -0400 Subject: [PATCH 16/19] fix trip referencing --- gtfs/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index d8a6b48b0..002c31fb3 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -394,7 +394,7 @@ Methods for occupancy forecasting used to populated `occupancies.txt` are not st | 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. | +| `trip_id` | ID referencing `trips.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.

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:

`0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - **Standing room only**. The vehicle can currently accommodate only standing passengers.
`4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - **Not accepting passengers**. The vehicle can not accept passengers. | | `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:

`1` - The occupancy level applies for all Mondays in the date range.
`0` or empty - The occupancy level does not apply for all Mondays in the date range. | From 9e3200b9d2112548d239c3ecf7550fa1e73fc291 Mon Sep 17 00:00:00 2001 From: scmcca Date: Mon, 20 Sep 2021 14:52:51 -0400 Subject: [PATCH 17/19] Revert "fix trip referencing" This reverts commit b23784cdb9dcb1001eb70bd55dd9b2aa296bf056. --- gtfs/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 002c31fb3..d8a6b48b0 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -394,7 +394,7 @@ Methods for occupancy forecasting used to populated `occupancies.txt` are not st | Field Name | Type | Required | Description | | ----- | ----- | ----- | ----- | -| `trip_id` | ID referencing `trips.trip_id` | **Required** | Identifies a `trip_id` for which an occupancy level is described. | +| `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.

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:

`0` - **Empty**. The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers.
`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.
`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.
`3` - **Standing room only**. The vehicle can currently accommodate only standing passengers.
`4` - **Crushed standing room only**. The vehicle can currently accommodate only standing passengers and has limited space for them.
`5` - **Full**. The vehicle is considered full by most measures, but may still be allowing passengers to board.
`6` - **Not accepting passengers**. The vehicle can not accept passengers. | | `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:

`1` - The occupancy level applies for all Mondays in the date range.
`0` or empty - The occupancy level does not apply for all Mondays in the date range. | From d28afc3ce8b3439485818b0d37ea6501c5a75181 Mon Sep 17 00:00:00 2001 From: scmcca Date: Tue, 21 Sep 2021 12:39:26 -0400 Subject: [PATCH 18/19] frequency-based trips --- gtfs/spec/en/reference.md | 1 + 1 file changed, 1 insertion(+) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index d8a6b48b0..f6bf1a9af 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -406,6 +406,7 @@ Methods for occupancy forecasting used to populated `occupancies.txt` are not st | `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.

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.

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`.

Must be some multiple (including zero) of `frequencies.headway_secs` plus `frequencies.start_time` for the corresponding time period.

Conditionally Required:
- **Required** for trips using `frequencies.txt`.
- **Forbidden** otherwise. | ### translations.txt From f2ea4cfa03dea0eae3f01eb7bb1172f17cba67b1 Mon Sep 17 00:00:00 2001 From: scott christian mccallum Date: Tue, 21 Sep 2021 21:09:32 -0400 Subject: [PATCH 19/19] Update guidelines Co-authored-by: Jeff Kessler <31969870+jeffkessler-keolis@users.noreply.github.com> --- gtfs/spec/en/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index f6bf1a9af..881885494 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -388,9 +388,9 @@ File: **Optional** Usual or expected in-vehicle occupancy levels. -For describing historical average occupancies at least 4 weeks of occupancy data should be averaged across each unique day of the week, valid for up to 2 weeks thereafter in `occupancies.txt`. +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. -Methods for occupancy forecasting used to populated `occupancies.txt` are not strictly specified. Beyond the guidelines given above, 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 | | ----- | ----- | ----- | ----- |