From 8291088085f92317c605af7621c315a78f3b3c9f Mon Sep 17 00:00:00 2001 From: Sky Rose Date: Fri, 20 Sep 2024 17:31:03 -0400 Subject: [PATCH 01/10] rough rosters and employee assignment spec --- docs/spec/examples.md | 17 ++++++++++ docs/spec/index.md | 72 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+) diff --git a/docs/spec/examples.md b/docs/spec/examples.md index d20a6f2..4e6bf40 100644 --- a/docs/spec/examples.md +++ b/docs/spec/examples.md @@ -168,3 +168,20 @@ weekday,10000,20,BLOCK-A,deadhead ,,garage,08:50:00,stop-1,09:00:00 weekday,10000,30,BLOCK-A,run-as-directed,,stop-1,09:00:00,stop-1,12:00:00 weekday,10000,30,BLOCK-A,deadhead ,,stop-1,12:00:00,garage,12:10:00 ``` + +## Crew/Roster + +TODO I haven't written examples yet, but here are ones I think would be good: + +- UK scheduling (employees rotate per week) +- North American scheduling (pick one roster for the whole rating. I don't think there'll be a big difference between roster-style and cafeteria-style in the data? ) +- A holiday +- Scheduled track work one day, times/service_id are slightly changed, but substantially the same. + - `roster_dates.txt`: `roster_id,date,old_service_id,2;...new_service_id,1` +- Vacation that's part of the roster. + - `roster_dates.txt`: remove old one. assign spare_roster_id (which has no regular assignment) to it on that date. Maybe `spare_roster_id` still needs to be in `rosters.txt` for comprehensive listing reasons, for start/end date, and for (doesn't exist yet) metadata like label +- Vacation that's not part of the roster, and done by assigning a different employee to that run that date. + - `employee_dates`, remove the employee from the roster, add the spare employee. +- Producer that doesn't use rosters, just uses `employee_dates` for everything. + +(There's enough of them that they should be on a separate page.) diff --git a/docs/spec/index.md b/docs/spec/index.md index b9fef7f..fae156b 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -22,6 +22,8 @@ There are two types of files used in the TODS standard: | routes_supplement.txt | Supplement | Supplements and modifies GTFS [routes.txt](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#routestxt) with internal route identifiers and other non-public route identification. | | run_events.txt | TODS-Specific | Lists all trips and other scheduled activities to be performed by a member of personnel during a run. | +TODO add new roster files to this list + _The use of the Supplement standard to modify other GTFS files is not yet formally adopted into the specification and remains subject to change. Other files may be formally adopted in the future._ ## Supplement Files @@ -139,3 +141,73 @@ Because some events may overlap in time, it may not be possible to choose a sing - Events may have gaps between the end time of one event and the start time of the next. e.g. if an operator's layovers aren't represented by an event. - `start_time` may equal `end_time` for an event that's a single point in time (such as a report time) without any duration. - Recommended sort order: `service_id`, `run_id`, `event_sequence`. + +### `rosters.txt` + +TODO text description of how all 4 files fit together. + +Primary Key: `roster_id` + +| **Field Name** | **Type** | **Required** | **Description** | +| --- | --- | --- | --- | +| `roster_id` | Unique ID | Required | Unique within dataset | +| `start_date` | Date | Required | | +| `end_date` | Date | Required | | +| `monday_service_id` | ID referencing `run_events.txt` | Conditionally Required | Identifies the run this roster does on Mondays. Runs are identified by the pair `(service_id, run_id)`. Required if and only if `monday_run_id` is present. | +| `monday_run_id` | ID referencing `run_events.txt` | Conditionally Required | Identifies the run this roster does on Mondays. If blank, this roster does not work on Mondays. Required if and only if `monday_service_id` is present. | +| `tuesday_service_id` | ID referencing `run_events.txt` | Conditionally Required | Identifies the run this roster does on Mondays. Runs are identified by the pair `(service_id, run_id)`. Required if and only if `monday_run_id` is present. | +| `tuesday_service_id` | | | | +| `tuesday_run_id` | | | | +| `wednesday_service_id` | | | | +| `wednesday_run_id` | | | | +| `thursday_service_id` | | | | +| `thursday_run_id` | | | | +| `friday_service_id` | | | | +| `friday_run_id` | | | | +| `saturday_service_id` | | | | +| `saturday_run_id` | | | | +| `sunday_service_id` | | | | +| `sunday_run_id` | | | | + +### `roster_dates.txt` + +Primary Key: `(roster_id, date, exception_type)` + +| **Field Name** | **Type** | **Required** | **Description** | +| --- | --- | --- | --- | +| `roster_id` | ID referencing `rosters.txt` | Required | (note: should `roster_id` have to be in `rosters.txt` (potentially on 0 days per week), or can you define new rosters in this file, like `calendar_dates.txt` does with service IDs?) | +| `date` | Date | Required | Date when exception occurs. | +| `exception_type` | Enum | Required | `1` - The run is added to this roster for the specified date.
`2` - The roster will not work its regular run on this date. | +| `service_id` | ID referencing `run_events.txt` | Conditionally Required | Part of the Run ID, which is refered to as `(service_id, run_id)`. Required if `run_id` is present. | +| `run_id` | ID referencing `run_events.txt` | Conditionally Required | The run that's either added or removed from this roster. Required if `exception_type` is `1`. Optional if `exception_type` is `2`. If `exception_type` is `2` and `run_id` is not blank, then it must match the Run ID that the roster was scheduled to do on this date according to `rosters.txt` | + +### `employee_rosters.txt` + +Describes which employees are scheduled to which rosters on which dates. + +Primary Key: `(roster_id,start_date)` + +| **Field Name** | **Type** | **Required** | **Description** | +| --- | --- | --- | --- | +| `employee_id` | ID | Required | | +| `roster_id` | ID referencing `rosters.txt` | Required | | +| `start_date` | Date | Required | | +| `end_date` | Date | Required | | + +Each roster can only be assigned to one employee on each date. Employees may be scheduled to more than one roster on the same date. + +### `employee_run_dates.txt` + +Describes which employees are scheduled to which runs on which dates. If `employee_rosters.txt` is used, then describes exceptions to that schedule. + +Primary Key: `*` + +| **Field Name** | **Type** | **Required** | **Description** | +| --- | --- | --- | --- | +| `employee_id` | ID | Required | | +| `date` | Date | Required | | +| `service_id` | ID referencing `run_events.txt` | Required | Part of the Run ID, which is refered to as `(service_id, run_id)`. | +| `run_id` | ID referencing `run_events.txt` | Required | The run that's either added or removed from this employee's schedule. If `exception_type` is `2` and `run_id` is not blank, then it must match a Run ID that the employee was scheduled to do on this date according to `employee_rosters.txt`, `rosters.txt` and `roster_dates.txt`. | +| `exception_type` | Enum | Required | `1` - The run is assigned to this employee on the specified date.
`2` - The employee will not work this run on this date. | + +Each run can only be assigned to one employee on each date. Employees may be scheduled to more than one run on the same date. From f393e8427c316bd61a0d0ac2d6ad03cb266d0484 Mon Sep 17 00:00:00 2001 From: Sky Rose Date: Fri, 20 Sep 2024 18:20:12 -0400 Subject: [PATCH 02/10] employee_run_dates.txt:exception_type can be omitted --- docs/spec/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/spec/index.md b/docs/spec/index.md index fae156b..dee4c6c 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -177,7 +177,7 @@ Primary Key: `(roster_id, date, exception_type)` | --- | --- | --- | --- | | `roster_id` | ID referencing `rosters.txt` | Required | (note: should `roster_id` have to be in `rosters.txt` (potentially on 0 days per week), or can you define new rosters in this file, like `calendar_dates.txt` does with service IDs?) | | `date` | Date | Required | Date when exception occurs. | -| `exception_type` | Enum | Required | `1` - The run is added to this roster for the specified date.
`2` - The roster will not work its regular run on this date. | +| `exception_type` | Enum | Required | `1` - The run is added to this roster for the specified date.
`2` - The roster will not work its regular run on this date. | | `service_id` | ID referencing `run_events.txt` | Conditionally Required | Part of the Run ID, which is refered to as `(service_id, run_id)`. Required if `run_id` is present. | | `run_id` | ID referencing `run_events.txt` | Conditionally Required | The run that's either added or removed from this roster. Required if `exception_type` is `1`. Optional if `exception_type` is `2`. If `exception_type` is `2` and `run_id` is not blank, then it must match the Run ID that the roster was scheduled to do on this date according to `rosters.txt` | @@ -208,6 +208,8 @@ Primary Key: `*` | `date` | Date | Required | | | `service_id` | ID referencing `run_events.txt` | Required | Part of the Run ID, which is refered to as `(service_id, run_id)`. | | `run_id` | ID referencing `run_events.txt` | Required | The run that's either added or removed from this employee's schedule. If `exception_type` is `2` and `run_id` is not blank, then it must match a Run ID that the employee was scheduled to do on this date according to `employee_rosters.txt`, `rosters.txt` and `roster_dates.txt`. | -| `exception_type` | Enum | Required | `1` - The run is assigned to this employee on the specified date.
`2` - The employee will not work this run on this date. | +| `exception_type` | Enum | Optional | `1` (or blank) - The run is assigned to this employee on the specified date.
`2` - The employee will not work this run on this date. | + +If a feed doesn't represent rosters, it can still assign employees to runs by putting every run for every date in this file. In that case, the `exception_type` column can be omitted because every row would be adding a date, which is the default when the column is blank. Each run can only be assigned to one employee on each date. Employees may be scheduled to more than one run on the same date. From 4fadf35201f369c41bd2a9ddbecd9b944e53de4c Mon Sep 17 00:00:00 2001 From: Aaron Antrim Date: Fri, 6 Dec 2024 11:24:42 -0800 Subject: [PATCH 03/10] Add vehicle_assignments.txt, vehicles files Working off of @skyqrose 's outline of vehicle_assignments.txt, https://github.com/cal-itp/operational-data-standard/issues/28#issuecomment-2292345857. Attempted alignment with GTFS-Vehicles proposal. --- docs/spec/index.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/spec/index.md b/docs/spec/index.md index dee4c6c..b4e4715 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -213,3 +213,45 @@ Primary Key: `*` If a feed doesn't represent rosters, it can still assign employees to runs by putting every run for every date in this file. In that case, the `exception_type` column can be omitted because every row would be adding a date, which is the default when the column is blank. Each run can only be assigned to one employee on each date. Employees may be scheduled to more than one run on the same date. + +### `vehicle_assignments.txt` + +Primary Key: `*` + +| Field Name | Type | Required | Description | +|---|---|---|---| +| `date` | Date | Required | | +| `service_id` | ID referencing `calendar.service_id` or `calendar_dates.service_id` | Optional | Identifies a set of dates when the run is scheduled to take place. Required if `block_id`s are repeated between different `service_id`s. | +| `block_id` | ID referencing `trips.block_id` | Conditionally required | Identifies the block. Either `trip_id` or `block_id` must be specified. | +| `trip_id` | ID referencing `trips.trip_id` | Conditionally required | Either `trip_id` or `block_id` must be specified. In the case where both are supplied, `trip_id` overrides `block_id`. Note: multiple vehicles are allowed on the same block+date, but this is not recommended. | +| `vehicle_id` | ID referencing `vehicles.vehicle_id` | Conditionally required | Refers to a specific vehicle in the transit fleet. Either `vehicle_id` or `vehicle_category_id` MUST be supplied. | +| `vehicle_category_id` | ID referencing `vehicle_categories.vehicle_category_id` | Conditionally required | Refers to a category of vehicle in the transit fleet if there is no specific vehicle assignment. Either `vehicle_id` or `vehicle_category_id` MUST be supplied. | + +Not every trip or block and date combo needs to have a vehicle specified. + +### `vehicle_categories.txt` + +Primary Key: `vehicle_category_id` + +| Field Name | Type | Required | Description | +|---|---|---|---| +| `vehicle_category_id` | ID, primary key | Required | Defines an ID for a vehicle category. | +| `vehicle_category_name` | Text | Optional | The vehicle_category_name field defines the name of the vehicle category. E.g. “MR73” in Montréal, “TGV Duplex” in France or “8-car Waratah Train” in Sydney. | +| `fuel_type` | Enum | Optional | 0 or empty - unknown propulsion
1 - Gasoline
2 - Diesel
3 - LPG auto
4 - Mixture
5 - Biodiesel
6 - Electricity
7 - Hybrid
8 - Natural Gas
9 - Other | +| `wheelchair_accessible` | Enum | Optional | Wheelchair accessible.
0 or empty - no
1 - yes | +| `seating_capacity` | Non-negative Integer | Optional | This number denotes the number of seats dedicated to riders, excluding folding seats. A seat is considered accommodating only one rider in a seated position. | +| `max_capacity` | Non-negative Integer | Optional | This number denotes the maximum number of riders that the vehicle can carry. | +| `wheelchair_capacity` | Non-negative Integer | Optional | This number denotes the maximum number of riders in a wheelchair that the vehicle can carry. | + +### `vehicles.txt` + +Primary Key: `vehicle_id` + +| Field Name | Type | Required | Description | +|---|---|---|---| +| `vehicle_id` | ID, primary key | Required | Defines an ID for a vehicle. | +| `vehicle_ category_id` | ID referencing `vehicle_categories.vehicle_category_id` | Optional | | +| `vehicle_description` | Text | Optional | | +| `registration_date` | Date | Optional | | +| `license_plate` | Text | Optional | License number of the vehicle for identification, e.g. “E898656” | +| `owner` | Text | Optional | Registered owner, e.g “City of Arcata” | \ No newline at end of file From 94e3146f9edc5555c12016447e57c4ff8e418ca5 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 13 Dec 2024 07:20:14 +0000 Subject: [PATCH 04/10] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/spec/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/index.md b/docs/spec/index.md index b4e4715..8c66758 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -254,4 +254,4 @@ Primary Key: `vehicle_id` | `vehicle_description` | Text | Optional | | | `registration_date` | Date | Optional | | | `license_plate` | Text | Optional | License number of the vehicle for identification, e.g. “E898656” | -| `owner` | Text | Optional | Registered owner, e.g “City of Arcata” | \ No newline at end of file +| `owner` | Text | Optional | Registered owner, e.g “City of Arcata” | From 405e1b3a9c5b71ca109a59965e6ae2c3b74ef60a Mon Sep 17 00:00:00 2001 From: Aaron Antrim Date: Fri, 13 Dec 2024 13:46:33 -0800 Subject: [PATCH 05/10] vehicle_category -> vehicle_type fixes https://github.com/cal-itp/operational-data-standard/pull/85#discussion_r1883521804 responds to https://github.com/cal-itp/operational-data-standard/pull/85#issuecomment-2540777506 --- docs/spec/index.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/spec/index.md b/docs/spec/index.md index b4e4715..afe2e7e 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -224,19 +224,22 @@ Primary Key: `*` | `service_id` | ID referencing `calendar.service_id` or `calendar_dates.service_id` | Optional | Identifies a set of dates when the run is scheduled to take place. Required if `block_id`s are repeated between different `service_id`s. | | `block_id` | ID referencing `trips.block_id` | Conditionally required | Identifies the block. Either `trip_id` or `block_id` must be specified. | | `trip_id` | ID referencing `trips.trip_id` | Conditionally required | Either `trip_id` or `block_id` must be specified. In the case where both are supplied, `trip_id` overrides `block_id`. Note: multiple vehicles are allowed on the same block+date, but this is not recommended. | -| `vehicle_id` | ID referencing `vehicles.vehicle_id` | Conditionally required | Refers to a specific vehicle in the transit fleet. Either `vehicle_id` or `vehicle_category_id` MUST be supplied. | -| `vehicle_category_id` | ID referencing `vehicle_categories.vehicle_category_id` | Conditionally required | Refers to a category of vehicle in the transit fleet if there is no specific vehicle assignment. Either `vehicle_id` or `vehicle_category_id` MUST be supplied. | +| `vehicle_id` | ID referencing `vehicles.vehicle_id` | Conditionally required | Refers to a specific vehicle in the transit fleet. Either `vehicle_id` or `vehicle_type_id` MUST be supplied. | +| `vehicle_type_id` | ID referencing `vehicle_types.vehicle_type_id` | Conditionally required | Refers to a type of vehicle in the transit fleet if there is no specific vehicle assignment. Either `vehicle_id` or `vehicle_type_id` MUST be supplied. | Not every trip or block and date combo needs to have a vehicle specified. -### `vehicle_categories.txt` +### `vehicle_types.txt` + +Primary Key: `vehicle_type_id` + +_Note:_ Fields to describe vehicle and vehicle type attributes are under discussion during this draft and will likely change significantly. -Primary Key: `vehicle_category_id` | Field Name | Type | Required | Description | |---|---|---|---| -| `vehicle_category_id` | ID, primary key | Required | Defines an ID for a vehicle category. | -| `vehicle_category_name` | Text | Optional | The vehicle_category_name field defines the name of the vehicle category. E.g. “MR73” in Montréal, “TGV Duplex” in France or “8-car Waratah Train” in Sydney. | +| `vehicle_type_id` | ID, primary key | Required | Defines an ID for a vehicle type. | +| `vehicle_type_name` | Text | Optional | Brief plain-language description of the vehicle. E.g. “MR73” in Montréal, “TGV Duplex” in France or “8-car Waratah Train” in Sydney. | | `fuel_type` | Enum | Optional | 0 or empty - unknown propulsion
1 - Gasoline
2 - Diesel
3 - LPG auto
4 - Mixture
5 - Biodiesel
6 - Electricity
7 - Hybrid
8 - Natural Gas
9 - Other | | `wheelchair_accessible` | Enum | Optional | Wheelchair accessible.
0 or empty - no
1 - yes | | `seating_capacity` | Non-negative Integer | Optional | This number denotes the number of seats dedicated to riders, excluding folding seats. A seat is considered accommodating only one rider in a seated position. | @@ -250,7 +253,7 @@ Primary Key: `vehicle_id` | Field Name | Type | Required | Description | |---|---|---|---| | `vehicle_id` | ID, primary key | Required | Defines an ID for a vehicle. | -| `vehicle_ category_id` | ID referencing `vehicle_categories.vehicle_category_id` | Optional | | +| `vehicle_type_id` | ID referencing `vehicle_types.vehicle_type_id` | Optional | | | `vehicle_description` | Text | Optional | | | `registration_date` | Date | Optional | | | `license_plate` | Text | Optional | License number of the vehicle for identification, e.g. “E898656” | From 85f67e58a8a68ed06d1b0e1ee4ffbd55d3e294ba Mon Sep 17 00:00:00 2001 From: Aaron Antrim Date: Sun, 15 Dec 2024 12:27:01 -0800 Subject: [PATCH 06/10] primary key for vehicle assignments fixes https://github.com/cal-itp/operational-data-standard/pull/85#discussion_r1884605925 --- docs/spec/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/index.md b/docs/spec/index.md index fb1e070..859874d 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -216,7 +216,7 @@ Each run can only be assigned to one employee on each date. Employees may be sch ### `vehicle_assignments.txt` -Primary Key: `*` +Primary Key: `(date, block_id, service_id)` | Field Name | Type | Required | Description | |---|---|---|---| From aee1524c8342aa3dfe226922c998d8ef85199b45 Mon Sep 17 00:00:00 2001 From: Aaron Antrim Date: Sun, 15 Dec 2024 12:28:36 -0800 Subject: [PATCH 07/10] "run" -> "trip" https://github.com/cal-itp/operational-data-standard/pull/85#discussion_r1884598122 --- docs/spec/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/index.md b/docs/spec/index.md index 859874d..81dab50 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -221,7 +221,7 @@ Primary Key: `(date, block_id, service_id)` | Field Name | Type | Required | Description | |---|---|---|---| | `date` | Date | Required | | -| `service_id` | ID referencing `calendar.service_id` or `calendar_dates.service_id` | Optional | Identifies a set of dates when the run is scheduled to take place. Required if `block_id`s are repeated between different `service_id`s. | +| `service_id` | ID referencing `calendar.service_id` or `calendar_dates.service_id` | Optional | Identifies a set of dates when the trip is scheduled to take place. Required if `block_id`s are repeated between different `service_id`s. | | `block_id` | ID referencing `trips.block_id` | Conditionally required | Identifies the block. Either `trip_id` or `block_id` must be specified. | | `trip_id` | ID referencing `trips.trip_id` | Conditionally required | Either `trip_id` or `block_id` must be specified. In the case where both are supplied, `trip_id` overrides `block_id`. Note: multiple vehicles are allowed on the same block+date, but this is not recommended. | | `vehicle_id` | ID referencing `vehicles.vehicle_id` | Conditionally required | Refers to a specific vehicle in the transit fleet. Either `vehicle_id` or `vehicle_type_id` MUST be supplied. | From f3281fe536c40490a0fb9a221c7cfd1f41b64e15 Mon Sep 17 00:00:00 2001 From: Aaron Antrim Date: Sun, 15 Dec 2024 12:32:05 -0800 Subject: [PATCH 08/10] remove vehicle_assignments.trip_id https://github.com/cal-itp/operational-data-standard/pull/85#discussion_r1884600035 --- docs/spec/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/spec/index.md b/docs/spec/index.md index 81dab50..3703a1e 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -222,8 +222,7 @@ Primary Key: `(date, block_id, service_id)` |---|---|---|---| | `date` | Date | Required | | | `service_id` | ID referencing `calendar.service_id` or `calendar_dates.service_id` | Optional | Identifies a set of dates when the trip is scheduled to take place. Required if `block_id`s are repeated between different `service_id`s. | -| `block_id` | ID referencing `trips.block_id` | Conditionally required | Identifies the block. Either `trip_id` or `block_id` must be specified. | -| `trip_id` | ID referencing `trips.trip_id` | Conditionally required | Either `trip_id` or `block_id` must be specified. In the case where both are supplied, `trip_id` overrides `block_id`. Note: multiple vehicles are allowed on the same block+date, but this is not recommended. | +| `block_id` | ID referencing `trips.block_id` | Required | Identifies the block. | | `vehicle_id` | ID referencing `vehicles.vehicle_id` | Conditionally required | Refers to a specific vehicle in the transit fleet. Either `vehicle_id` or `vehicle_type_id` MUST be supplied. | | `vehicle_type_id` | ID referencing `vehicle_types.vehicle_type_id` | Conditionally required | Refers to a type of vehicle in the transit fleet if there is no specific vehicle assignment. Either `vehicle_id` or `vehicle_type_id` MUST be supplied. | From b4c4be1b5db76ee46ae15b57f401c3289a644a57 Mon Sep 17 00:00:00 2001 From: Aaron Antrim Date: Sun, 15 Dec 2024 12:35:21 -0800 Subject: [PATCH 09/10] vehicle_id and vehicle_type_id must agree https://github.com/cal-itp/operational-data-standard/pull/85#discussion_r1884604281 --- docs/spec/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/index.md b/docs/spec/index.md index 3703a1e..750073d 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -224,7 +224,7 @@ Primary Key: `(date, block_id, service_id)` | `service_id` | ID referencing `calendar.service_id` or `calendar_dates.service_id` | Optional | Identifies a set of dates when the trip is scheduled to take place. Required if `block_id`s are repeated between different `service_id`s. | | `block_id` | ID referencing `trips.block_id` | Required | Identifies the block. | | `vehicle_id` | ID referencing `vehicles.vehicle_id` | Conditionally required | Refers to a specific vehicle in the transit fleet. Either `vehicle_id` or `vehicle_type_id` MUST be supplied. | -| `vehicle_type_id` | ID referencing `vehicle_types.vehicle_type_id` | Conditionally required | Refers to a type of vehicle in the transit fleet if there is no specific vehicle assignment. Either `vehicle_id` or `vehicle_type_id` MUST be supplied. | +| `vehicle_type_id` | ID referencing `vehicle_types.vehicle_type_id` | Conditionally required | Refers to a type of vehicle in the transit fleet if there is no specific vehicle assignment. Either `vehicle_id` or `vehicle_type_id` MUST be supplied. If both are supplied, then the supplied `vehicle_type_id` must match the row referenced in `vehicles.txt`. | Not every trip or block and date combo needs to have a vehicle specified. From 82bc797c2842f77cda47e4456a0f4c08cb28f113 Mon Sep 17 00:00:00 2001 From: Aaron Antrim Date: Sun, 15 Dec 2024 12:46:41 -0800 Subject: [PATCH 10/10] remove crew/rostering crew/rostering is in #81 https://github.com/cal-itp/operational-data-standard/pull/85#pullrequestreview-2503280290 --- docs/spec/examples.md | 17 ---------- docs/spec/index.md | 74 ------------------------------------------- 2 files changed, 91 deletions(-) diff --git a/docs/spec/examples.md b/docs/spec/examples.md index 4e6bf40..d20a6f2 100644 --- a/docs/spec/examples.md +++ b/docs/spec/examples.md @@ -168,20 +168,3 @@ weekday,10000,20,BLOCK-A,deadhead ,,garage,08:50:00,stop-1,09:00:00 weekday,10000,30,BLOCK-A,run-as-directed,,stop-1,09:00:00,stop-1,12:00:00 weekday,10000,30,BLOCK-A,deadhead ,,stop-1,12:00:00,garage,12:10:00 ``` - -## Crew/Roster - -TODO I haven't written examples yet, but here are ones I think would be good: - -- UK scheduling (employees rotate per week) -- North American scheduling (pick one roster for the whole rating. I don't think there'll be a big difference between roster-style and cafeteria-style in the data? ) -- A holiday -- Scheduled track work one day, times/service_id are slightly changed, but substantially the same. - - `roster_dates.txt`: `roster_id,date,old_service_id,2;...new_service_id,1` -- Vacation that's part of the roster. - - `roster_dates.txt`: remove old one. assign spare_roster_id (which has no regular assignment) to it on that date. Maybe `spare_roster_id` still needs to be in `rosters.txt` for comprehensive listing reasons, for start/end date, and for (doesn't exist yet) metadata like label -- Vacation that's not part of the roster, and done by assigning a different employee to that run that date. - - `employee_dates`, remove the employee from the roster, add the spare employee. -- Producer that doesn't use rosters, just uses `employee_dates` for everything. - -(There's enough of them that they should be on a separate page.) diff --git a/docs/spec/index.md b/docs/spec/index.md index 750073d..6d4bc5a 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -22,8 +22,6 @@ There are two types of files used in the TODS standard: | routes_supplement.txt | Supplement | Supplements and modifies GTFS [routes.txt](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#routestxt) with internal route identifiers and other non-public route identification. | | run_events.txt | TODS-Specific | Lists all trips and other scheduled activities to be performed by a member of personnel during a run. | -TODO add new roster files to this list - _The use of the Supplement standard to modify other GTFS files is not yet formally adopted into the specification and remains subject to change. Other files may be formally adopted in the future._ ## Supplement Files @@ -142,78 +140,6 @@ Because some events may overlap in time, it may not be possible to choose a sing - `start_time` may equal `end_time` for an event that's a single point in time (such as a report time) without any duration. - Recommended sort order: `service_id`, `run_id`, `event_sequence`. -### `rosters.txt` - -TODO text description of how all 4 files fit together. - -Primary Key: `roster_id` - -| **Field Name** | **Type** | **Required** | **Description** | -| --- | --- | --- | --- | -| `roster_id` | Unique ID | Required | Unique within dataset | -| `start_date` | Date | Required | | -| `end_date` | Date | Required | | -| `monday_service_id` | ID referencing `run_events.txt` | Conditionally Required | Identifies the run this roster does on Mondays. Runs are identified by the pair `(service_id, run_id)`. Required if and only if `monday_run_id` is present. | -| `monday_run_id` | ID referencing `run_events.txt` | Conditionally Required | Identifies the run this roster does on Mondays. If blank, this roster does not work on Mondays. Required if and only if `monday_service_id` is present. | -| `tuesday_service_id` | ID referencing `run_events.txt` | Conditionally Required | Identifies the run this roster does on Mondays. Runs are identified by the pair `(service_id, run_id)`. Required if and only if `monday_run_id` is present. | -| `tuesday_service_id` | | | | -| `tuesday_run_id` | | | | -| `wednesday_service_id` | | | | -| `wednesday_run_id` | | | | -| `thursday_service_id` | | | | -| `thursday_run_id` | | | | -| `friday_service_id` | | | | -| `friday_run_id` | | | | -| `saturday_service_id` | | | | -| `saturday_run_id` | | | | -| `sunday_service_id` | | | | -| `sunday_run_id` | | | | - -### `roster_dates.txt` - -Primary Key: `(roster_id, date, exception_type)` - -| **Field Name** | **Type** | **Required** | **Description** | -| --- | --- | --- | --- | -| `roster_id` | ID referencing `rosters.txt` | Required | (note: should `roster_id` have to be in `rosters.txt` (potentially on 0 days per week), or can you define new rosters in this file, like `calendar_dates.txt` does with service IDs?) | -| `date` | Date | Required | Date when exception occurs. | -| `exception_type` | Enum | Required | `1` - The run is added to this roster for the specified date.
`2` - The roster will not work its regular run on this date. | -| `service_id` | ID referencing `run_events.txt` | Conditionally Required | Part of the Run ID, which is refered to as `(service_id, run_id)`. Required if `run_id` is present. | -| `run_id` | ID referencing `run_events.txt` | Conditionally Required | The run that's either added or removed from this roster. Required if `exception_type` is `1`. Optional if `exception_type` is `2`. If `exception_type` is `2` and `run_id` is not blank, then it must match the Run ID that the roster was scheduled to do on this date according to `rosters.txt` | - -### `employee_rosters.txt` - -Describes which employees are scheduled to which rosters on which dates. - -Primary Key: `(roster_id,start_date)` - -| **Field Name** | **Type** | **Required** | **Description** | -| --- | --- | --- | --- | -| `employee_id` | ID | Required | | -| `roster_id` | ID referencing `rosters.txt` | Required | | -| `start_date` | Date | Required | | -| `end_date` | Date | Required | | - -Each roster can only be assigned to one employee on each date. Employees may be scheduled to more than one roster on the same date. - -### `employee_run_dates.txt` - -Describes which employees are scheduled to which runs on which dates. If `employee_rosters.txt` is used, then describes exceptions to that schedule. - -Primary Key: `*` - -| **Field Name** | **Type** | **Required** | **Description** | -| --- | --- | --- | --- | -| `employee_id` | ID | Required | | -| `date` | Date | Required | | -| `service_id` | ID referencing `run_events.txt` | Required | Part of the Run ID, which is refered to as `(service_id, run_id)`. | -| `run_id` | ID referencing `run_events.txt` | Required | The run that's either added or removed from this employee's schedule. If `exception_type` is `2` and `run_id` is not blank, then it must match a Run ID that the employee was scheduled to do on this date according to `employee_rosters.txt`, `rosters.txt` and `roster_dates.txt`. | -| `exception_type` | Enum | Optional | `1` (or blank) - The run is assigned to this employee on the specified date.
`2` - The employee will not work this run on this date. | - -If a feed doesn't represent rosters, it can still assign employees to runs by putting every run for every date in this file. In that case, the `exception_type` column can be omitted because every row would be adding a date, which is the default when the column is blank. - -Each run can only be assigned to one employee on each date. Employees may be scheduled to more than one run on the same date. - ### `vehicle_assignments.txt` Primary Key: `(date, block_id, service_id)`