Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Vehicle assignments #85

Draft
wants to merge 11 commits into
base: main
Choose a base branch
from
Draft

Vehicle assignments #85

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
8291088
rough rosters and employee assignment spec
skyqrose Sep 20, 2024
f393e84
employee_run_dates.txt:exception_type can be omitted
skyqrose Sep 20, 2024
4fadf35
Add vehicle_assignments.txt, vehicles files
antrim Dec 6, 2024
94e3146
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Dec 13, 2024
405e1b3
vehicle_category -> vehicle_type
antrim Dec 13, 2024
7102599
Merge branch 'vehicle_assignments' of https://github.com/antrim/opera…
antrim Dec 13, 2024
85f67e5
primary key for vehicle assignments
antrim Dec 15, 2024
aee1524
"run" -> "trip"
antrim Dec 15, 2024
f3281fe
remove vehicle_assignments.trip_id
antrim Dec 15, 2024
b4c4be1
vehicle_id and vehicle_type_id must agree
antrim Dec 15, 2024
82bc797
remove crew/rostering
antrim Dec 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/spec/examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.)
116 changes: 116 additions & 0 deletions docs/spec/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -139,3 +141,117 @@ 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.<br />`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.<br />`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: `*`
Copy link
Contributor

Choose a reason for hiding this comment

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

This key allows multiple vehicles/types to be assigned to the same block/trip. Is that intentional, as a way to allow any of the vehicles to run the trip? If so, then that should be mentioned in the docs. If not, then a primary key that would prevent that is (date, block_id, trip_id).

Copy link
Author

@antrim antrim Dec 15, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Hmm… I'll add a primary key. (date, block_id, service_id).
Allowing multiple assignments or planning for vehicle couplings seems like a complex case.

Copy link
Author

Choose a reason for hiding this comment

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

85f67e5


| 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. |
Copy link
Contributor

Choose a reason for hiding this comment

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

description mentions runs, probably a copy-paste error.

How do date and service_id interact? Why do you need service_id when you already have a date? Are block_ids unique within the service but not the date?

Copy link
Author

Choose a reason for hiding this comment

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

description mentions runs, probably a copy-paste error.

Oops, will fix.

Why do you need service_id when you already have a date?

Service periods defined by calendar.txt can overlap. E.g. Monday-Sunday with additional Monday-Friday only trips.

Copy link
Author

Choose a reason for hiding this comment

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

aee1524

Copy link
Contributor

Choose a reason for hiding this comment

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

Minor thing (assuming we're in agreement): we should probably clarify that it's service_date, not just the date of assignment or the trip's calendar date of operation.

| `block_id` | ID referencing `trips.block_id` | Conditionally required | Identifies the block. Either `trip_id` or `block_id` must be specified. |
Copy link
Contributor

Choose a reason for hiding this comment

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

Block could be always required if:

  • We say you can only use this feature if you use block IDs (they're optional in trips.txt)
  • Either:
    • You have to include the block, even if you include the trip. (And the block must be the same block as the trip's block.)
    • trip_id is removed (see previous comment).

Alternatively, it would also be possible to say that exactly one of block_id and trip_id is required, which might be less error-prone than allowing both and ignoring the block if the trip exists.

Copy link
Author

Choose a reason for hiding this comment

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

Let's explore removing vehicle_assignments.trip_id

Copy link
Author

Choose a reason for hiding this comment

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

f3281fe

| `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. |
Copy link
Contributor

Choose a reason for hiding this comment

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

Would an agency ever schedule multiple vehicles to the same block? Doesn't that go against the definition of block? I know that might happen as a realtime adjustment, but if it's scheduled to happen, shouldn't they change the schedule so it's multiple different blocks?

If we can make that assumption, then this field could be removed.

Copy link
Author

@antrim antrim Dec 15, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I included trip_id as an option for cases where block_id is not supplied in the GTFS. On 2nd thought I'd favor removing, unless we know this is a case to plan for out of the gate.

Copy link
Author

Choose a reason for hiding this comment

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

f3281fe

Copy link
Contributor

Choose a reason for hiding this comment

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

I'd recommend including it for specific trips. This works for agencies that don't publish blocks and may not wish to make specific trip-specific block assignments in TODS, and likewise works for agencies with interchangeable operations. (I could see us making these assignments on a trip-specific level to specify requirements by trip prior to building out cycles.)

Copy link

Choose a reason for hiding this comment

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

I'm in favour of keeping it as it is now, with the trip_id removed.

If we allow assignments of individual trips to vehicles it breaks the logic of blocks as @skyqrose pointed out.

If we allow assignments of individual trips to vehicle types/categories it overlaps content-wise with http://bit.ly/gtfs-vehicles (which already has a route-to-vehicle-category assignment modeling a "requirement"). The case that you pointed out last ("specify requirements by trip prior to building out cycles") should probably be modeled using http://bit.ly/gtfs-vehicles.

"agencies that don't publish blocks" can still wrap each trip in an artificial block and assign it this way and/or add their real blocks in the non-public trips_supplement.txt only.

So overall, it seems like we can transmit the operational plan (including which vehicles/types will really be running the trips) without allowing to include trip_id in the assignments.

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

Choose a reason for hiding this comment

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

Having the category here sounds good, but perhaps we should then stress that this is the operationally assigned category of vehicle, not the planned one.

The planned vehicle category/type would be more naturally placed in routes_supplement.txt or trips_supplement.txt. Usually, planned and real vehicle type should be identical, but there could be differences.

Copy link
Author

Choose a reason for hiding this comment

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

Yes. GTFS-Vehicles had proposed to add a routes.vehicle_category_id field that would define "a default vehicle category for all trips belonging to this route". This could be useful for rider-facing applications (i.e. accessibility & amenity information) and for planning, scheduling, and operational purposes as well, I imagine.


Not every trip or block and date combo needs to have a vehicle specified.

### `vehicle_categories.txt`
Copy link
Contributor

Choose a reason for hiding this comment

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

If vehicle_categories comes from the other extension, does it need to be part of TODS? Could you instead say that vehicle_category_id references the extension file, which should be in public GTFS, so that the spec isn't duplicated in the extension and in TODS?

Copy link
Author

Choose a reason for hiding this comment

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

It would make sense for vehicle_categories (now vehicle_types.txt) to live outside of TODS. However, I do not believe that it has been implemented yet. So, I think we should implement in TODS in a way that could become part of a "primary GTFS" dataset later.


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 <br />1 - Gasoline <br /> 2 - Diesel <br /> 3 - LPG auto <br /> 4 - Mixture <br /> 5 - Biodiesel <br /> 6 - Electricity <br /> 7 - Hybrid <br /> 8 - Natural Gas <br /> 9 - Other |
Copy link
Contributor

Choose a reason for hiding this comment

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

Does there need to be a distinction between battery buses that charge at a station, and trolley buses that charge under catenary? Does there need to be a Hydrogen category?

There are so many options here, I wonder if it'd be better to have an unrestricted string enum, or if the field should be removed and an agency should know (from some other non-TODS record) what fuel type each vehicle_type_name uses.

Copy link
Author

Choose a reason for hiding this comment

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

Also, this list is messy -- properties are mixed up. "Hybrid" isn't a fuel type. For now, I favor removing or replacing with a text string if it's necessary for an immediate use case. (But imagining that the vehicle_category_name could make useful distinctions, e.g. vehicle_category_name="40' LNG Bus".

| `wheelchair_accessible` | Enum | Optional | Wheelchair accessible. <br />0 or empty - no <br />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. |

Copy link
Contributor

Choose a reason for hiding this comment

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

There are so many fields that could be included here. (Height clearance, platform height, wheel gauge, length, make, model, ...)

What determines whether something should be included, vs something that should be looked up elsewhere based on vehicle_type_name? If it's referenced in GTFS? If it matters to riders?

Copy link
Author

Choose a reason for hiding this comment

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

At this point, I think we should implement only fields that will be consumed by some software either out-of-the-gate or soon. Any other fields discussed could be implemented when there is a use later.

Copy link
Contributor

Choose a reason for hiding this comment

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

Is there a reason to exclude folding seats from the seating_capacity field? (Is the idea that it is the max number of seats inclusive of wheelchairs in one vehicle?)

I know there are many agencies that almost exclusively use transverse folding seats, which could lead to artificially-lower seating_capacity values.

### `vehicles.txt`
Copy link
Contributor

Choose a reason for hiding this comment

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

How do consists of multiple cars work, both for trains made of all the same car, and trains made of multiple different cars? Would there be a type_id for each type of car, or for each unique way to assemble a train? And then a vehicle_id for each car, or a vehicle_id for the whole train? Is a 4-car train the same type as a 6-car train of the same cars? If a train reverses and now has its control car in front and locomotive in the back, is that the same vehicle_id?

Copy link
Author

Choose a reason for hiding this comment

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

So, this is one of the reasons that I have proposed to build off GTFS-Vehicles. The draft spec has something called GTFS-VehicleCouplings that answers this.


Primary Key: `vehicle_id`

| Field Name | Type | Required | Description |
|---|---|---|---|
| `vehicle_id` | ID, primary key | Required | Defines an ID for a vehicle. |
Copy link
Contributor

Choose a reason for hiding this comment

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

Is this the same ID as shows up in GTFS-RT? If so, that should probably be mentioned, though agencies might not have a consistent mapping of phsyical vehicle to GTFS-RT vehicle_id, which might make it impossible to use the same ID here.

Copy link
Author

Choose a reason for hiding this comment

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

There is theoretical usefulness of a consistent vehicle_id. So the spec might make a recommendation. How shall we assess this? Ask reps from Transit, Swiftly, GMV, transit agencies or others to say whether this makes sense, offers value?

| `vehicle_ category_id` | ID referencing `vehicle_categories.vehicle_category_id` | Optional | |
antrim marked this conversation as resolved.
Show resolved Hide resolved
| `vehicle_description` | Text | Optional | |
Copy link
Contributor

Choose a reason for hiding this comment

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

I think the description should be on the type, instead of the individual. Individuals within each type shouldn't be unique enough to require their own description, but a description field could be useful on the type.

Edit: I see the type is optional, so this could be useful to give details on a vehicle that doesn't have a type. But I feel like a better approach would be to add a type for the vehicle and describe it there. Denormalizing the data into the individual vehicles is only useful if agencies have many bespoke vehicles, which seems rare.

Copy link
Author

Choose a reason for hiding this comment

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

Was assuming that descriptive text strings can end up being useful for edge cases we can't anticipate.

Copy link
Contributor

Choose a reason for hiding this comment

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

I see this field being useful for vehicle-specific things, even more esoteric items like "Veterans-Wrapped Coach" or "Heritage Paint Scheme."

| `registration_date` | Date | Optional | |
Copy link
Contributor

Choose a reason for hiding this comment

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

What should be the reasoning for which fields belong in TODS?

registration_date doesn't seem that useful for assigning vehicles to trips.

| `license_plate` | Text | Optional | License number of the vehicle for identification, e.g. “E898656” |
Copy link
Contributor

Choose a reason for hiding this comment

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

There may need to be a label field in addition to license_plate, similar to GTFS-RT VehicleDescriptor.

| `owner` | Text | Optional | Registered owner, e.g “City of Arcata” |
Copy link
Contributor

Choose a reason for hiding this comment

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

Perhaps owner should be part of the vehicle type instead. If two owners own similar vehicles in the same feed, it's okay if they're represented as two types, cuz they're probably not interchangeable anyway.

Copy link
Contributor

Choose a reason for hiding this comment

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

@skyqrose Yes and no. In interstate rail, it's not uncommon for various identical pieces of equipment to be owned by different operators (e.g. 4/120 SEPTA SLV cars are owned by the State of Delaware, but are otherwise identical and interchangeable with the rest of the fleet; MNR's M8s are owned in a mix between MNR and ConnDOT, but the cars are likewise identical). From a planning perspective, we wouldn't necessarily care whose car was operated, just that one of those cars was operated along the trip.

Loading