Vehicle assignments

[antrim]

Proposed spec in response to issue #28 "Allocating drivers and vehicles in ODS".

What it does: Assign individual vehicles to blocks.

What it does NOT do:

• Introduce vehicle types, categories, groupings, or couplings. These could be added in a future version, looking towards drawing from the [http://bit.ly/gtfs-vehicles](GTFS-Vehicles proposal).
• Assign vehicles according to a regular weekly schedule (i.e. instead of individual service date)

Changes included:

• vehicles.txt: ID, text label, license plate. Only a few attribute fields are defined for a minimum viable proposal. TODS consumers may be able to look up additional attributes by vehicle_id. More attributes can be defined in future TODS versions.
• vehicle_assignments.txt: Assignments by service date, block_id, service_id

[github-actions]

Preview url: https://operational-data-standard-85--cal-itp-previews.netlify.app

[antrim]

Based on this #28 (comment) - what @skyqrose outlined in August

Notes:

• vehicles.txt and vehicle_categories.txt crib liberally from http://bit.ly/gtfs-vehicles. That proposal aligned with platform descriptions for GTFS-Pathways. I don't know the current status of that proposal. I included a baseline of fields; perhaps more should be included in this proposal.
• I considered whether to relate vehicle assignments to run_events.txt, but since mid-run events would never involve the change of a vehicle, this would have created more complexity.
• vehicle_assignments can map to trip_id or block_id. This is for cases where block_id is not universally supplied, perhaps because a GTFS feed follows the original usage of block_id - indicating allowed in-seat transfers.

[antrim]

Some internal discussion at Optibus:
Timon Kelter suggested that vehicle_categories sounds very abstract, but vehicle_types would be more natural and is descriptive. I agree. I had was cribbing from the GTFS-Vehicles proposal, but don't see a reason to keep this term. Will plan to change to vehicle_types.txt.
BTW, I have invited Optibus team to share more discussion here. So we'll expose a bit more deliberation that might otherwise have been internal :)

[antrim]

These are vehicle properties that Optibus currently exports in a non TODS format. Which properties should be included in TODS?

Vehicle properties example.xlsx

vehicle_id	ID	Identifies a vehicle.
agency_id	ID referencing agency.agency_id	Agency for the specified vehicle.
start_date	Date	Day when the vehicle begins to be part of the fleet.
license_plate	Text	License plate of the specified vehicle.
make	Text	Make of the specified vehicle.
model	Text	Model of the specified vehicle.
owner	Text	Vehicle owner entity.
registration_date	Date	Date of the first registration.
available_seats	Non-negative Integer	Number of seating places.
available_standing	Non-negative Integer	Number of standing places.
typology	Enum	Vehicle typology. 0 or empty = unknown typology 1 = Urban Mini 2 = Urban Midi 3 = Urban Standard 4 = Urban Articulated 5 = Inter-urban Standard 6 = Inter-urban Articulated 7 = Tourism
vclass	Enum	Vehicle class. 0 or empty = unknown class 1 = A (Urban Mini) 2 = I (Urban Midi, Urban Standard, Urban Articulated) 3 = II (Inter-urban Standard, Inter-urban Articulated) 4 = III (Tourism)
propulsion	Enum	Propulsion technology. 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
emission	Enum	Emissions class. 0 or empty = unkwon emissions class 1 = EURO I 2 = EURO II 3 = EURO III 4 = EURO IV 5 = EURO V 6 = EURO VI
new_seminew	Enum	New or Semi-New. 0 or empty = no 1 = yes
ecological	Enum	Non-polluting or energy-efficient vehicle. 0 or empty = no 1 = yes
climatization	Enum	Climatization. 0 or empty = no 1 = yes
wheelchair	Enum	Wheelchair accessible. 0 or empty = no 1 = yes
corridor	Enum	Passageway for wheelchairs / baby strollers. 0 or empty = no 1 = yes
lowered_floor	Enum	Lowered floor. 0 or empty = no 1 = yes
ramp	Enum	Ramp for people with reduced mobility. 0 or empty = no 1 = yes
folding_system	Enum	Folding system for boarding and exiting of people with reduced mobility. 0 or empty = no 1 = yes
kneeling	Enum	Vehicle "kneeling" to reduce entry height. 0 or empty = no 1 = yes
static_information	Enum	Posters and fixed signage. 0 or empty = no 1 = yes
onboard_monitor	Enum	On-board monitor. 0 or empty = no 1 = yes
front_display	Enum	External front destination display. 0 or empty = no 1 = yes
rear_display	Enum	External rear destination panel. 0 or empty = no 1 = yes
side_display	Enum	External right side destination panel. 0 or empty = no 1 = yes
internal_sound	Enum	Internal sound information (on-board Public Address). 0 or empty = no 1 = yes
external_sound	Enum	External sound information (external Public Address). 0 or empty = no 1 = yes
consumption_meter	Enum	Consumption measurement. 0 or empty = no 1 = yes
bicycles	Enum	Permission to transport non-folding bicycles (folding bicycles are always allowed). 0 or empty = no 1 = yes
passenger_counting	Enum	Vehicle has a passenger counting system. 0 or empty = no 1 = yes
video_surveillance	Enum	Vehicle has a video surveillance system. 0 or empty = no 1 = yes

[timon-k]

From the fields mentioned above, I would remove at least new_seminew, ecological, static_information, onboard_monitor, all *_display fields, all *_sound fields and consumption_meter.

To me, those look too undefined, covered by other attributes like emission already or just not needed for operational purposes.

I'm also very unsure about folding_system, ramp and kneeling. Given that we have wheelchair and lowered_floow already that looks like too many details on the same question.

[timon-k]

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.

[antrim]

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.

[antrim]

@skyqrose @safrazier17 Can you help guide process here? Since I worked off the #81 branch, this has the rosters and employee assignments spec draft. Should I remove those changes?

Will we vote on the two PRs separately or together? Merge separately?

[skyqrose]

I've left lots of line-by-line comments.

As for the process, I think this is completely independent from #81. We could split them into two separate PRs/votes.

[skyqrose]

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.

[antrim]

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.

[antrim]

f3281fe

[jeffkessler-keolis]

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

[timon-k]

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.

[antrim]

We've been discussing this internally at Optibus, including with some CAD/AVL partners. For the upcoming version, we propose a "least viable" approach:

• Remove vehicle_types.txt
• Scale vehicles.txt down to vehicle_id and license_plate

This removes speculative vehicle attributes. The CAD/AVL should be able to look up vehicle attributes stored in that system.

Thoughts/reactions?

[skyqrose]

That does remove the ability to assign a type of vehicle without assigning a specific vehicle, but that's probably fine if we're aiming for a least viable approach.

[antrim]

@skyqrose If we pass a version of this without vehicle types, I think the discussion was still useful, so thanks for the review and great comments. And if we do add in more vehicle attributes besides the ID and license plate, then bringing back in vehicle type seems useful.

[antrim]

Proposed changes (from discussion today):

• vehicle_id required
• Remove vehicle_type_id (and vehicle_types.txt file) with a note that this may be introduced in the future, in order to mitigate issues that would be caused by a later backwards-incompatibile change to add vehicle_type_id and make vehicle_id conditionally required.
• Also, in service of future spec evolution, mention GTFS-Vehicles and add note about train couplings
• Add a vehicle label field (e.g. like the name of a ferry)
• Recommend (do NOT require) vehicle_id should match GTFS-realtime vehicle_id
• Keep license_plate field since it matches GTFS-realtime, but note other global identifier may be supplied, particularly for non-road vehicle types, e.g. Maritime Mobile Service Identity (MMSI) for ferries

[safrazier17]

Pre-vote checklist (@antrim)

• Remove vehicle_types.txt
• Remove vehicles.vehicle_type_id
• Remove vehicles.vehicle_description
• Remove vehicles.registration_date
• Remove vehicles.owner
• Edit description of vehicles.license_plate to account for its use as a more generic unique vehicle identifier
• Add vehicles.vehicle_label
• Remove vehicle_assignments.vehicle_type_id
• Edit vehicle_assignments.vehicle_id description to include note about roadmap plan to allow assignments to be made to groups of vehicles (a la vehicle type) rather than just to individual vehicles
• Add vehicle assignments examples
• Edit the PR description so that it includes an overview of proposed changes as they currently stand and the goal of the changes

[safrazier17]

For this note, is there anything different that we would expect a rail producer to do in order to future proof their feed? Or is this just for general awareness?

[antrim]

General awareness. Not sure how else we could express this or if it makes sense to include.
I think that a rail producer would advocate for this function to be added.
This is also a heads up for any consumer: Future versions of TODS may have vehicle consists.

[skyqrose]

this is looking much better now