Skip to content

employee_run_dates.txt #87

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.

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

Merged
merged 29 commits into from
May 6, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 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
d3d1de0
more edits to roster spec. rename rosters to roster_positions.
skyqrose Feb 25, 2025
66ffdac
service_id may be omitted
skyqrose Feb 28, 2025
fb4e3b3
fixup uniqueness
skyqrose Feb 28, 2025
025ee2e
add to examples todo
skyqrose Feb 28, 2025
f9dbb9a
typo
skyqrose Feb 28, 2025
3780c5b
move drafts of examples into a new file
skyqrose Mar 3, 2025
64e3368
Merge remote-tracking branch 'upstream/main' into roster
skyqrose Mar 3, 2025
991e8b3
lint
skyqrose Mar 3, 2025
24f2502
adjust employee_id column order and docs
skyqrose Mar 7, 2025
f3c883b
write a couple examples
skyqrose Mar 7, 2025
737edce
write a couple more examples
skyqrose Mar 11, 2025
9c9b4b9
finish drafing examples
skyqrose Mar 12, 2025
d68b2f0
add links
skyqrose Mar 12, 2025
841eaf8
adjust column order. proofread
skyqrose Mar 12, 2025
df8466f
move employee_run_dates to top of roster. forbid run if exception_type=2
skyqrose Mar 12, 2025
6b533c2
lint
skyqrose Mar 13, 2025
6097800
typo
skyqrose Mar 13, 2025
952e47b
remove all files except employee_run_dates.txt
skyqrose Mar 13, 2025
0394dcf
make service ID required
skyqrose Mar 13, 2025
76dcf58
move one remaining example to main examples file
skyqrose Mar 13, 2025
67da576
fix file list
skyqrose Mar 13, 2025
b15606d
date description. example calendar header.
skyqrose Mar 24, 2025
e0e9cd3
remove duplicate rows from example
skyqrose Apr 4, 2025
a16c162
prohibit multiple employees on the same run. adjust column order
skyqrose Apr 4, 2025
d933e26
allow assigning multiple employees to the same run
skyqrose Apr 10, 2025
97cea85
Merge remote-tracking branch 'upstream/main' into roster-simple
skyqrose Apr 10, 2025
e7bc306
fix broken links
skyqrose Apr 14, 2025
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
50 changes: 50 additions & 0 deletions docs/spec/examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,3 +168,53 @@ 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
```

## Employee Assignments

This example uses [`employee_run_dates.txt`](/spec#employee_run_datestxt) to assign employees to runs (and trips).

In this example, `A` and `B` work Monday-Wednesday and Sunday. `C` and `D` work Thursday-Saturday.

On Wedneday, July 3, `A` has scheduled vacation, so a substitute is assigned instead.

**[`calendar.txt`](https://gtfs.org/documentation/schedule/reference/#calendartxt)**

```csv
service_id,monday,tuesday,wednesday,thursday,friday,saturday,sunday,start_date,end_date
weekday,1,1,1,1,1,0,0,20240701,20240707
weekend,0,0,0,0,0,1,1,20240701,20240707
```

July 1, 2024 was a Monday.

**[`run_events.txt`](/spec#run_eventstxt)**

For this example, the purpose of this file is just to show which runs exist. Real runs would have more interesting data.

```csv
service_id,run_id,event_sequence,event_type,trip_id,start_location,start_time,end_location,end_time
weekday,101,1,work,trip1,station,09:00:00,station,17:00:00
weekday,102,1,work,trip2,station,09:00:00,station,17:00:00
weekend,103,1,work,trip3,station,09:00:00,station,17:00:00
weekend,104,1,work,trip4,station,09:00:00,station,17:00:00
```

**[`employee_run_dates.txt`](/spec#employee_run_datestxt)**

```csv
date,service_id,run_id,employee_id
20240701,weekday,101,A
20240701,weekday,102,B
20240702,weekday,101,A
20240702,weekday,102,B
20240703,weekday,101,A
20240703,weekday,102,B
20240704,weekday,101,C
20240704,weekday,102,D
20240705,weekday,101,C
20240705,weekday,102,D
20240706,weekend,103,C
20240706,weekend,104,D
20240707,weekend,103,A
20240707,weekend,104,B
```
24 changes: 24 additions & 0 deletions docs/spec/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ There are two types of files used in the TODS standard:
- **Supplement files**, used to add, modify, and delete information from public GTFS files to model the operational service for internal purposes (with a `_supplement` filename suffix).
- **TODS-Specific files**, used to model operational elements not currently defined in the GTFS standard.

All files are optional.

### Files

| **File Name** | **Type** | **Description** |
Expand All @@ -21,6 +23,7 @@ There are two types of files used in the TODS standard:
| stop_times_supplement.txt | Supplement | Supplements and modifies GTFS [stop_times.txt](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#stop_timestxt) 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](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. |
| employee_run_dates.txt | TODS-Specific | Assigns employees to runs. |

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

Expand Down Expand Up @@ -133,9 +136,30 @@ Events that don't have `trip_id` set may overlap in time with any other events.

Because some events may overlap in time, it may not be possible to choose a single order for events within a run that's correct for all uses. Producers should use `event_sequence` to define a reasonable order. If a consumer cares about exactly how overlapping events are ordered, they should sort based on the time fields and `event_type` instead.

#### Run ID Uniqueness

Run IDs may be non-unique. E.g. E.g. there may be a "Run 100" on both Weekday and Weekend service. There may even be a Run 100 on both `garage1-weekday` and `garage2-weekday` services, happening on the same day. Runs are uniquely referred to by a `(service_id, run_id)` pair. This is why the service ID is required on this file and other files that refer to run IDs.

#### `run_events` Notes

- Multiple `run_event`s may refer to the same `trip_id`, if multiple employees work on that trip.
- 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`.

### `employee_run_dates.txt`

Describes which employees are scheduled to which runs on which dates.

This file should represent the schedule after holidays, vacations, and other scheduled exceptions have been applied.

Each run and date combination may appear 0 times in this file (if there's no assigned employee), 1 time, or multiple times (if multiple employees are assigned to the same run on the same date).

Primary Key: `*`

Choose a reason for hiding this comment

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

The primary key being * suggests that multiple employees could be schedule for the same run and service_id on the same day. While we know this situation occurs in reality when there are service problems, is there a case for scheduling this way? We suggest the primary key be (date, run_id, service_id).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yeah, I think this is good. My original thought was that if two employees really are doing the same thing all day (maybe like 2 fare collectors who work the same trains), they could share a run number and the producer could skip some rows. But consumers knowing that there's at most one employee per run is more valuable.

I've made the change.

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 request to revert this change for the original reason cited by @skyqrose: on the railroad front, it is common to have multiple employees assigned to the same run.

While some may pre-specify by craft, others include dual-certified personnel whereby two employees work the same run and are required to vary up who works as the engineer vs conductor on each trip. Likewise, other operations include two matched crew members who work identical shifts in the same function.

In practice, I suspect most consumers can treat (date, run_id, service_id) as the primary key, but retaining the flexibility for those of us who schedule that way would be ideal.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ah, I didn't realize that there were schedules like that in practice. Given that this is a real situation, I'll revert it.


| **Field Name** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| `date` | Date | Required | Service date. |
| `service_id` | ID referencing [`run_events.txt`](#run_eventstxt) | Required | Part of the Run ID, which is refered to as `(service_id, run_id)`. See [Run ID Uniqueness](#run-id-uniqueness). |
| `run_id` | ID referencing [`run_events.txt`](#run_eventstxt) | Required | The run that's added to this employee's schedule. |
| `employee_id` | ID | Required | References an agency's external systems. Employee IDs are not used elsewhere in TODS. |