Reference for new run_events.txt spec

[skyqrose]

Write up of #60 in a format that can be merged. I've gone with the event_sequence idea instead of run_event_id. Other than that there are minor text changes and some reformatting, but no semantic changes.

The changes to the spec are all in the one file index.md. Here's a link to the diff and the rendered version

I've also rewritten all of the examples (which is why there are so many deleted files). Here's a rendered version of examples.md

Status as of 2024-07-01: #61 was merged and I've updated this PR so it only contains new changes.

[github-actions[bot]]

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

[skyqrose]

Here's a link to just the changes that weren't already voted on in #61.

The changes to the spec are all in the one file index.md. Everything else is changes to examples (link to rendered preview of new examples).

Edit: Out of date, see updated description instead.

[safrazier17]

VOTING PERIOD OPEN

Voting is now open on this proposal through 11:59:59 UTC on 16 July 2024. This proposal is the second of two for the TODS 2.0.0 release. If adopted, this proposal will be released as TODS 2.0.0.

WHO IS ELIGIBLE TO VOTE

Any individual may vote as an ODS Contributor; in voting, Contributors are acknowledging and agreeing to the ODS Contributor Agreement and ODS Code of Conduct.

TODS Board Members are eligible to vote, provided that they are not also Issue Working Group members.

Issue Working Group members (@safrazier17, @jeffkessler-keolis, @jfabi, and @skyqrose) are not eligible to vote on this proposal.

HOW TO VOTE

• A vote of support for this PR, comment "+1 [Individual or Organization Name]"
• To support the proposal with a minor correction, add one comment to the PR including both the correction and "+1 [Individual or Organization Name]"
• To vote for a substantial revision to the proposal, comment "-1 [Individual or Organization Name]" along with a brief description of what you believe needs to be substantially revised before the proposal can be adopted. NOTE: TODS governance requires that voters requesting substantial revision commit to working with the Issue Working Group to develop their recommended revision.

OUTCOMES

• At the end of the voting period, if the proposal has received at least THREE (3) +1 votes from stakeholders outside of the Issue Working Group and no votes of "Support with Minor Correction" or "Substantial Revision," the proposal is immediately adopted.
• If the proposal receives one or more votes of "Support with Minor Correction," the Issue Working Group may decide whether to incorporate the recommended changes or to appeal to the Board for consideration of the necessity of the recommended changes.
  • If the issue working group or the Board determine that the minor changes should be incorporated into the proposal, the proposal shall be updated and the TODS community shall be notified of the updates. After a period of FOUR (4) business days, the proposal shall be adopted immediately unless valid objections to the minor changes are received. No new voting period is automatically initiated.
• If the proposal receives one or more votes of substantial changes, the author(s) of the recommended changes must commit to working with the issue working group to develop an alternative proposal that meets the need raised by the reviewer. The issue working group may appeal to the Board if they believe a recommended substantial change is without merit.
  • If a proposal is substantially changed, then a new voting period must be opened before the amended proposal can be adopted.
• If the proposal does not meet the minimum threshold for votes outside of the issue working group, the working group may appeal to the Board for a decision. The Board may vote to adopt the proposal or to require a new voting period.

[lemald]

Liking this proposal overall but I have one clarification question. For, start_time, it's stated:

If trip_id is set (and mid_trip_start is not 1), this should be the time of the first stop of the trip (after applying any trip supplement).

What about cases where the arrival_time and departure_time of the first stop_time on the trip differ? The analogous question applies for end_time.

One thought is that for start_time we could prefer arrival_time in the case of a discrepancy and then for end_time prefer departure_time, though I haven't thought about it long enough to know whether there are any obvious issues with that approach.

[skyqrose]

What about cases where the arrival_time and departure_time of the first stop_time on the trip differ?

Good catch, I hadn't considered that there might be two separate times.

The intent is to represent when the employee is working on that trip. If the first stop has different arrival_time and departure_time, then that probably means the vehicle is sitting berthed with the doors open. The operator isn't necessarily on board then, they could hop on just before the departure_time. So run_events.start_time should probably correspond with the stop_times.departure_time.

Similarly, for the last stop, the vehicle could arrive, the operator could open the doors, and hop off leaving the doors open for passengers, so they'd only be working on that trip until stop_times.arrival_time.

I'll update the text to make that a little clearer and give a recommendation, but producers could fill the field differently if they consider an employee to be working starting at arrival_time or ending at departure_time.

Edit: Clarified in 5ac73b7. I avoided recommending either field specifically, just said that either is fine.

[BTollison]

Does start_mid_trip or end_mid_trip matter if we have to indicate a start_time and end_time anyway? I guess, for me, it's not clear why we need it. Does start_time and end_time have to correspond with stop_times.start_time and stop_times.end_time?

[wmata-eajensen]

+1 from WMATA with minor corrections:

• Per @BTollison's comment, curious about start_mid_trip/`end_mid_trip. Willing to accept with or without the field so didn't want to vote against since the rest looks good.
• The "Run As Directed" example clarified things, but for block_id, the definition for run_events in index.md states it references trips.block_id. I think changing that to "references trips.block_id if available" would probably cover Strategic Buses/Extras where there is no trips.block_id available?

I also think the first sentence in the definition might be a little unclear, stating:

If block_id exists, trip_id exists, and that trip's entry in trips.txt has a block_id, then the two block_ids must match.

I think switching that around to:

If trip_id is set, and the associated trip in trips.txt has a block_id, then the two Block IDs must match.

might be clearer? Open to suggestions

[BTollison]

Reading the proposal over again a bit, I think the way it's setup currently doesn't allow for unattended reliefs?

My recommendation here is that start_time and end_time be the start and end time regardless of stops_times.txt. This way we don't need start_mid_trip or end_mid_trip. We already have trip_id, so it seems okay to do it this way?

If we can agree on this -- or some version of this I'm +1.

[skyqrose]

Bill (Edit: Bradley Sorry!):

start_mid_trip/end_mid_trip are useful to have because a mid-trip relief is a complex case that will be a lot easier to detect and handle if it's called out explicitly instead of needing to detect it by comparing run_events.txt to trips.txt and stop_times.txt. It makes producing a little harder in order to make consuming a lot easier and less error prone. If an agency never does mid-trip reliefs, then they can leave the whole column out. If an agency does do mid-trip reliefs, then the complexity has to go somewhere, and I think here is a good place for it.

run_events.start_time should correspond to stop_times.arrival_time or stop_times.departure_time, because presumably an employee will start working on the trip when the trip starts. (Unless it's a mid-trip relief, in which case it corresponds to the stop_time.arrival/departure_time of the stop where the employee starts working that trip.) It's SHOULD, not MUST, because maybe some agency has a reason to do something weird with it, but having the run event times correspond to the trip times is the intent. (If we wanted to skip the start/end_mid_trip fields, then producers would need to MUST exactly match stop_times.txt in order for consumers to detect mid-trip reliefs.)

What do you mean by "unattended reliefs"?

My recommendation here is that start_time and end_time be the start and end time regardless of stops_times.txt.

Can you clarify what you mean? start_time and end_time should be start and end time of what?

Erik:

👍 to the minor text changes, I'll add those (or something like them) tomorrow. (One minor change I'll make: It should be okay for trips.txt to have a block_id and run_events.txt to leave it blank. I just want to make sure they're not conflicting.)

Scott:

Is it okay to delay the end of voting for a bit so we can finish the discussions about start/end time?

[BTollison]

Sorry, I meant that start and end times I think should be the event start and end time.

An unattended relief is when a driver does not need to cover the vehicle when a relief is being made. So, driver A brings the vehicle, but no driver is waiting to take over. The vehicle may sit for minutes or hours, and driver B could show up any time before the next trip on the block. I think though this is actually okay in the way it's written now in the spec.. because a driver would not typically "cover" the vehicle until they must drive it somewhere or do something related to it (sign-on). What do you think?

I do wonder though, what about reliefs that are covered but happen in the middle of a layover? I think in this case we do have an issue because Driver A must cover the vehicle +x minutes after a stop_times.departure/arrival_time and Driver B can take over to cover the vehicle -x minutes before the next stop_times.departure/arrival_time?

Both styles of reliefs are pretty common from what I've seen.

[skyqrose]

Unattended reliefs should be fine to represent. Example, where the vehicle sits 3 hours unattended before another operator signs in and continues the block:

# stop_times.txt
trip_id,arrival_time,stop_id,stop_sequence
101,10:00:00,stop-1,10
101,10:05:00,stop-2,20
102,13:00:00,stop-2,10
102,13:05:00,stop-1,20

# run_events.txt
service_id,run_id,event_sequence,piece_id,block_id,job_type,event_type,trip_id,start_location,start_time,start_mid_trip,end_location,end_time,end_mid_trip
daily,run-1,10,,       ,Operator,sign-in ,   ,stop-1,09:55:00, ,stop-1,10:00:00, 
daily,run-1,20,,block-1,Operator,Operator,101,stop-1,10:00:00,0,stop-2,10:05:00,0
daily,run-2,10,,       ,Operator,sign-in ,   ,stop-2,12:55:00, ,stop-2,13:00:00, 
daily,run-2,20,,block-1,Operator,Operator,102,stop-2,13:00:00,0,stop-1,13:05:00,0

For the case where an Operator is responsible for a vehicle 1 minute before/after every trip, you're right that the descriptions are unclear about which time to use.

If the descriptions were changed to this:

start_location (unchanged): Identifies where the employee starts working this event.

If trip_id is set (and mid_trip_start is not 1), this should be the stop_id of the first stop of the trip in stop_times.txt (after applying any trip supplement). If start_mid_trip is 1, this should be the location where the employee starts, matching a stop_id in the middle of the supplemented trip.

start_time (changed): Identifies the time when the employee starts working this event.

If trip_id is set (and mid_trip_start is not 1), this corresponds to the time of the first stop of the trip in stop_times.txt (after applying any trip supplement). If start_mid_trip is 1, this time corresponds to a stop time in the middle of the supplemented trip, when the employee starts working on the trip. Note that this time may not exactly match stop_times.txt arrival_time or departure_time if the employee is considered to be working for a couple minutes before the trip departs. This field is about when the employee is working, and consumers who care about the the trip times should check stop_times.txt instead.

would that help? I explicitly allowed the time to be different from the trip time, and clarified that this file is about employee work times, and if a consumer wants trip times they should come from stop_times.txt. I left the location as "should match stop_times.txt" because anything complex enough to require movement should probably be a different event, and it'll make matching to stop_times.txt easier.

[safrazier17]

@skyqrose I can extend if we need to. I have asked @lemald to clarify whether or not he intended to vote yes with minor correction with his comment. If so, then we don't need to extend as we will have met the minimum vote threshold and can figure out the minor correction requested by Bradley. At that point, there will be a ~three day window for the voters to withdraw their votes.

[Matthias-Gruetzner]

Hey all, I have 2 comments:

1. Not a fan of the mid_trip flags - what is the use case/the upside? If that was described somewhere, just point me to it, but I didn't see it.
2. Not on board with "Events may overlap in time" - whose data model supports that? E.g., does anyone's dispatch software allow for assigning an operator to multiple runs/duties at the same time?

[lemald]

@skyqrose I can extend if we need to. I have asked @lemald to clarify whether or not he intended to vote yes with minor correction with his comment. If so, then we don't need to extend as we will have met the minimum vote threshold and can figure out the minor correction requested by Bradley. At that point, there will be a ~three day window for the voters to withdraw their votes.

Hi - yes, sorry, that was my intent.

+1 from me, Eddie Maldonado, at MBTA, with the minor corrections already under discussion.

[safrazier17]

Hey all, I have 2 comments:

1. Not a fan of the mid_trip flags - what is the use case/the upside? If that was described somewhere, just point me to it, but I didn't see it.

@skyqrose addressed mid-trip here: https://github.com/cal-itp/operational-data-standard/pull/66#issuecomment-2229530831 @Matthias-Gruetzner

2. Not on board with "Events may overlap in time" - whose data model supports that? E.g., does anyone's dispatch software allow for assigning an operator to multiple runs/duties at the same time?

Sky or @jeffkessler-keolis could you provide any specific examples you might have of what was meant by this language:

Events may overlap in time, if an employee has multiple simultaneous responsibilities.

[Matthias-Gruetzner]

Scott, I saw the explanation that mid_trip should be easier to calculate during the export than when it is needed on the fly, but I don't see how or when it would be needed on the fly. I can see it as a consistency check as in "yes, the relief is really meant to be in the middle of the trip, this is not an error", but that's a feature that a software should calculate when it needs it, and not a data item. I don't like redundant data, especially when I don't see a common use case.

[skyqrose]

Matthias:

1. The mid_trip flags are needed to represent mid-trip reliefs, where an operator gets off a vehicle and a new operator gets on in the middle of a trip, while passengers are on board.

MBTA does this all the time on bus and subway when a yard is in the middle of the line, so operators can have a shift change without taking a vehicle out of service. I believe it's common at other agencies, too, though not every agency does it.

The fields are needed because this is an important case to handle in our operational software, and without the fields it would be difficult/tedious for a consumer to detect this case just by comparing run_events.txt and stop_times.txt. In general, I think mid-trip reliefs are a complex case that's likely to cause problems for many consumers, so I think it's worth extra effort by the producers to make it more explicit and less error-prone for consumers.

This has come up a couple times, so I've added a note that "If an agency does not use any mid-trip relief, the whole column may be omitted."

2. The overlapping events is more hypothetical. Here's a couple of situations where it could be useful:
   • An agency wants to use events for labeling parts of the day. Like one event for "operating vehicles 16:00-22:00" and one for "operating vehicles at the overnight pay rate 22:00-25:00" and those events overlap with the run events for the trips being done at those times.
   • An employee has multiple responsibilities (maybe fare collection and door operation) that are represented as separate events for the same trip.

But the motivation is less that these are important features to support, and more that forcing events not to overlap would be a restriction that I don't see a reason to enforce. It's unlikely to make a significant difference to consumers, but it could make a difference to producers who want to use run_events to represent a bunch of different types of events.

I'm not too attached to overlapping events, and I think that the spec ended up a little more complicated than it should need to be to express the fact that there's not a restriction there. If you think restricting events to not overlap is important, or if you have an idea for how to redo the event_sequence field and description so that it's less complicated (maybe it should not even try to be a sequence, and should just be an id that's unique within the run?) then I'm open to suggestions.

[skyqrose]

Oh also, based on discussions above about how it's okay if the event times don't exactly line up with the trip times, and how to handle stop_times with different arrival_time and departure_times, that makes it even harder for a consumer to check if a given run_event covers the whole trip. The producer is better able to know how to handle these gotchas correctly for their data.

[Matthias-Gruetzner]

Sky,

1. I agree that mid-trip reliefs are not uncommon, but I still don't see what that flag would do. A relief is a relief, and a shift end is a shift end, so what would happen if a driver reliefs in the middle of the trip without such a flag being set? I'm just thinking about which field this could be imported into in INIT's data model, or in which view it could be displayed, or in which function it could be used to achieve a specific outcome, and I don't see any application for it.
2. The first example is not an overlapping event, it's just a duty split into 2 different tasks, which is no problem. As for the second example, there would be 2 distinct duties called fare collection and door operation, and a dispatching software would have to be able to assign a single operator to 2 duties at once. I don't know if any software can do this.

[safrazier17]

I think I would advocate that we adopt the restriction of no overlapping events, with the understanding that when/if a use case arises in the future, we could always take up the topic again and eliminate the restriction. That would be in line with how we have handled similar questions (e.g. Only creating four gtfs supplement files instead of speculatively providing for additional ones).

[BTollison]

Unattended reliefs should be fine to represent. Example, where the vehicle sits 3 hours unattended before another operator signs in and continues the block:

# stop_times.txt
trip_id,arrival_time,stop_id,stop_sequence
101,10:00:00,stop-1,10
101,10:05:00,stop-2,20
102,13:00:00,stop-2,10
102,13:05:00,stop-1,20

# run_events.txt
service_id,run_id,event_sequence,piece_id,block_id,job_type,event_type,trip_id,start_location,start_time,start_mid_trip,end_location,end_time,end_mid_trip
daily,run-1,10,,       ,Operator,sign-in ,   ,stop-1,09:55:00, ,stop-1,10:00:00, 
daily,run-1,20,,block-1,Operator,Operator,101,stop-1,10:00:00,0,stop-2,10:05:00,0
daily,run-2,10,,       ,Operator,sign-in ,   ,stop-2,12:55:00, ,stop-2,13:00:00, 
daily,run-2,20,,block-1,Operator,Operator,102,stop-2,13:00:00,0,stop-1,13:05:00,0

For the case where an Operator is responsible for a vehicle 1 minute before/after every trip, you're right that the descriptions are unclear about which time to use.

If the descriptions were changed to this:

start_location (unchanged): Identifies where the employee starts working this event. If trip_id is set (and mid_trip_start is not 1), this should be the stop_id of the first stop of the trip in stop_times.txt (after applying any trip supplement). If start_mid_trip is 1, this should be the location where the employee starts, matching a stop_id in the middle of the supplemented trip. start_time (changed): Identifies the time when the employee starts working this event. If trip_id is set (and mid_trip_start is not 1), this corresponds to the time of the first stop of the trip in stop_times.txt (after applying any trip supplement). If start_mid_trip is 1, this time corresponds to a stop time in the middle of the supplemented trip, when the employee starts working on the trip. Note that this time may not exactly match stop_times.txt arrival_time or departure_time if the employee is considered to be working for a couple minutes before the trip departs. This field is about when the employee is working, and consumers who care about the the trip times should check stop_times.txt instead.

would that help? I explicitly allowed the time to be different from the trip time, and clarified that this file is about employee work times, and if a consumer wants trip times they should come from stop_times.txt. I left the location as "should match stop_times.txt" because anything complex enough to require movement should probably be a different event, and it'll make matching to stop_times.txt easier.

Alright, I'm good with this.

I tend to agree with @Matthias-Gruetzner on the mid_triip field but it isn't a blocker for me.

+1 from Transdev Group.

[jeffkessler-keolis]

From my side:

• mid_trip Flags

  • I'm indifferent with the mid_trip flags being included or omitted.
  • I do think they provide value with respect to highlighting instances in which employees are re-crewing a trip en-route, but they could always be reverse-engineered from the underlying data as needed.
  • If people have qualms about this, perhaps this field is made optional and could be used at the producer's discretion?

• Arrival/Departure Correspondence in Mid-Trip Reliefs

  • @BTollison raised a good point with respect to instances in which an arrival/departure time vary.
  • I think the vast majority of producers will have these values be identical, but in the instances in which they're not, I see the case in which it could match the arrival time, the departure time, or even neither (occurring somewhere in the middle).
  • I would strongly discourage the case where an employee's event on a trip precedes the arrival_time or succeeds the departure_time.
    • Doing so would limit the ability to distinguish between an employee arriving at a stop early to relieve another operator vs two employees working on the same trip at the same time.
    • Example: An employee alighting at a stop "on the trip," letting a train continue somewhere and returning to the original station, at which point the employee returns onboard the trip.
    • Granted, the above example is limited to a handful of edge-case networks, although there could be minor discrepancies in times between systems for which coupling the trip times and event times admittedly need not be mandatory.
    • I'd propose the language is thus modified to "this time SHOULD match the arrival_time, departure_time, or any time in-between."

• Permission/Restriction of Overlapping Events

  • I think the idea here was to show instances in which a scheduling software has someone on a piece like "availability" or "protect," and then has them covering a trip on top of that.
  • Likewise, the practice could be used to show employees having a particular duty / activity over which their specific work is included.
  • Per my understanding, if any restriction were needed, it would simply be that an employee can not be on two trips at the same time, but that they could otherwise be undertaking two activities at the same time.
  • This is not a blocker for me moving forward, and I'm fine having this come in at a later point in the spec as applicable, but I wouldn't want people to build implementations such that this subsequently becomes a breaking change.

[Matthias-Gruetzner]

So far I stick with my concerns and cannot accept the mid_trip flags and the overlapping events. I guess that makes it a "Support with Minor Correction".

[skyqrose]

Mid trip reliefs:

To show a concrete application of this field, here's an example screenshot from one of MBTA's internal bus operations tools, showing how a run's second piece starts mid-trip, along with where and when and on what run that trip started:

Displaying this information to bus dispatchers and officials helps them run service better (compared to thinking that this was a normal relief during a layover). E.g. an official at Andrew Station, where the swing will take place, would see this information, and then be better prepared to make sure that the shift change happens quickly without delaying passengers on the bus.

That said, if there's this much push back against the field, and not everyone would find it useful, then I like Jeff's suggestion of making it optional. If a producer and consumer both find it valuable, then they can include it. If a producer doesn't want to include it (because it would be extra work to compare to the trip times), then they don't have to. And if a consumer wants it but the producer didn't include it, they can recalculate it.

I propose this format:

start_mid_trip Enum Optional Indicates whether the event begins at the start of the trip or in the middle of the trip (after applying any trip supplement).

0 or blank - Run event is not associated with a trip, or no information about whether the run event starts mid-trip. 1 - Run event starts mid-trip. 2 - Run event starts at the first stop of the trip.

(Edit: Done)

Arrival/Departure correspondence

I don't think we should strongly suggest that times line up to stop times. Ensuring that would require the producer to compare data to stop_times.txt, which (based on the discussion about calculating the mid-trip fields) we want to avoid forcing the producers to have to do. If we don't require this, then for some producers it might become possible to make run_events.txt by looking only at crew schedules and not at trip schedules.

You're right that it could be ambiguous which stop_sequence a run_event starts at if a trip visits the run_events.start_location multiple times and the run_events.start_time doesn't line up with a stop_times.arrival/departure_time, but I don't think that's worth worrying about in practice.

I think the description should suggest that this will correspond to stop times because it will help producers understand the intent of the field, but if we want to avoid producers comparing to trip times, then I don't think the spec should describe matching to trip times as a SHOULD or MUST.

Overlapping Events

Thanks for the example about available / protected time.

Restricting trips from overlapping seems like an okay compromise. It would allow the cases about available/protected time, and would remove the most unintuitive part of overlapping events. But it would still require the complexity of event_sequence, could hypothetically make a producer unable to represent their schedule, and could still cause a breaking change for consumers if we want to allow overlapping events on trips in the future. So I'd be willing to compromise on it, but I'd still prefer to not restrict any overlaps.

(Whoops, I closed and reopened the pull request. That was an accident.)

[safrazier17]

So far I stick with my concerns and cannot accept the mid_trip flags and the overlapping events. I guess that makes it a "Support with Minor Correction".

@Matthias-Gruetzner we would call this a vote for a substantial revision.

• Does making the field optional resolve your concern about its inclusion?
• If not, can we (issue working group plus Matthias) schedule a call to figure out how we can account for this use case (as I understand it, being able to directly tie a run's entire event composition to a trip or stop time within a trip) differently?

[safrazier17]

@Matthias-Gruetzner can you let me know by EOD Friday whether making the field optional works for you? else, I will set up a working group meeting including you for further discussion

[Matthias-Gruetzner]

Sky thinks it's useful and apparently intends to use it, so I won't block it. But yes, the entire 2 columns for mid trip should be optional. If we do that, and remove allowing overlapping events: +1 from me.

[BTollison]

Edit -- nevermind about the below. I shouldn't respond to technical questions after midnight :) I end up confusing blocks and duties.

For overlapping trips, would a zero minute trip count as an overlapping trip? My guess is yes.

A zero minute trip is when a trip has no duration (0 minutes), so starting at 12:00 and ending at 12:00, then is proceeded by a "real" trip whether it is in revenue or not and starts at 12:00 also. In Hastus, this is a standard outcome for when you use the remake block feature for pull and taxi reliefs. In many instances I have seen the use of a zero minute trip as a way to create logistical movements that would otherwise not be possible when using an optimizer.

The zero minute trip in Hastus serves the purpose of creating an anchor point for a pull or deadhead when there is otherwise nothing to anchor on.

[safrazier17]

Voting period outcome

The voting period ended on Tuesday, July 16 at 23:59:59 UTC. Votes recorded for this pull request were as follows:

1. @wmata-eajensen (WMATA): +1 with minor corrections
2. @lemald (MBTA): +1 with minor corrections
3. @BTollison (Transdev): +1 with minor corrections
4. @Matthias-Gruetzner (INIT): +1 with minor corrections (see note below)

The vote has met the minimum threshold for support. Because there were multiple votes of support with minor corrections, voters have until Tuesday, July 23 at 23:59:59 UTC to either retract or affirm their vote of support for this proposal. @skyqrose please confirm when we have a final Pull Request that reflects the requested changes including:

• Optional start_mid_trip and end_mid_trip
• Restricting overlapping trips

If we retain >= 3 votes of support at the end of the review period, the proposal will be adopted as TODS 2.0.0.

(note: There is a lack of guidance in the current governance docs as to what should be considered a minor requested change vs a substantial revision. As it stands, Matthias's initial vote was a -1 vote for substantial revision because the vote was contingent upon the removal of two fields (start_mid_trip and end_mid_trip) included in the pull request. A compromise proposal was reached in which the fields were retained but the constraints were altered such that the fields would be purely optional, rather than conditionally required. Matthias amended his vote to +1 on this basis. I will ask the Board for additional guidance and updates to the governance docs to help account for similar cases in the future, but am comfortable with recording this vote as having 4 votes of support with minor corrections.)

[skyqrose]

• 👍 I will edit the spec to make start_mid_trip and end_mid_trip optional. (Edit: Done)
• 🤔 Overlapping trips is less clear. I'd like a little more discussion on it.

I have several questions for everyone:

• What are people's reasons for wanting overlapping events to be prohibited?
• Would prohibiting overlapping trips but allowing other non-trip events to overlap be okay?
• Are there other solutions (maybe trying to simplify the docs for event_sequence?) that would resolve the objections while still allowing overlapping trips?

My opinion is that overlapping non-trip events are useful, and although they could be removed, it'd be limiting for some use cases. Overlapping trips are not useful, but it seems simpler, more forward-compatible, and potentially hypothetically useful to allow them. I'm willing to prohibit overlapping trips but want to understand a little more about the objections first to make sure that a compromise actually addresses people's objections.

[Matthias-Gruetzner]

A "run" is the workload of a person on an operating day (~duty), similar to what a block is for a vehicle. A run can be split into different pieces, just like a block can consist of many trips. And just like there cannot be overlapping trips in a block, there cannot be overlapping pieces of a run. And it doesn't matter whether the pieces are trip-related or not. A driver cannot do 2 tasks called "yard cleaning" and "vehicle inspection" at the same time. If he has to do both, it has to be 1 task called "yard cleaning and vehicle inspection". No blocking software can purposefully create overlapping trips in a block, and no runcutting and dispatching software accepts overlapping pieces. Or am I mistaken?

[skyqrose]

I've been talking with a couple people 1:1 about overlapping run events.

• 👍 I'll change the spec to prohibit overlapping trips.

I thought having overlapping trips would allow more flexibility and make the spec more useful, but despite looking, I haven't heard of any concrete situations where it'd be needed. Making the spec easy to understand and a little easier for consumers outweighs any hypothetical future situations. There is a bit of a risk that if a concrete situation for overlapping trips does pop up in the future, it'd be a difficult backwards-incompatible change for consumers, but that risk seems to be worth taking.

I'm planning to keep allowing overlapping events (which aren't trips) because having sections of the day (such as available/protected time) is much more likely to be useful and pop up in real situations.

I will also relax the rules for event_sequence to make the spec a little simpler and easier to follow.

Edit: Done

[skyqrose]

I've made all edits (including making start/end_mid_trip optional, and prohibiting overlapping trips, but not prohibiting non-trip events). I've given everything one last readthrough and made a couple final minor wording tweaks. It's good to merge now!

[safrazier17]

Yes, we’ll leave as-is for now

On Thu, Aug 1, 2024 at 3:28 AM Jeff Kessler @.***> wrote:

@.**** commented on this pull request.

In docs/spec/index.md https://github.com/cal-itp/operational-data-standard/pull/66#discussion_r1699915280 :

@@ -20,8 +20,7 @@ There are two types of files used in the TODS standard: | stops_supplement.txt | Supplement | Supplements and modifies GTFS stops.txt with internal stop locations, waypoints, and other non-public stop information.| | stop_times_supplement.txt | Supplement | Supplements and modifies GTFS stop_times.txt with non-public times at which trips stop at locations, stop_times entries for non-public trips, and related information. | | routes_supplement.txt | Supplement | Supplements and modifies GTFS routes.txt with internal route identifiers and other non-public route identification. | -| runs_pieces.txt | TODS-Specific | Defines daily personnel schedules within a feed. | -| run_events.txt | TODS-Specific | Defines other scheduled activities to be performed by a member of personnel during a run. | +| run_events.txt | TODS-Specific | Lists all trips and other scheduled activities to be performed by a member of personnel during a run. |

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.

That works for me, although I'm not sure how that fits into the broader scope of things given that (a) it wasn't officially proposed during the vote itself; and (b) that was technically already approved as part of #61 https://github.com/cal-itp/operational-data-standard/pull/61's PR, not this one. If we don't want to pursue for the sake of governance, perhaps we add that tweak to 2.1's planned changes.

— Reply to this email directly, view it on GitHub https://github.com/cal-itp/operational-data-standard/pull/66#discussion_r1699915280, or unsubscribe https://github.com/notifications/unsubscribe-auth/ALKK7YEVZHSDOBQJLT2XIHTZPIETLAVCNFSM6AAAAABFSJ362GVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDEMJSGM2TCOJTGU . You are receiving this because you were mentioned.Message ID: @.***>