Discussion: footnotes?

[antrim]

Should we use a timetable_notes.txt file that allows referencing specific timetables, stops, and trips to add footnotes on a timetable?

(Updated: notes.txt -> timetable_notes.txt)

[brendannee]

Sure - that would help solve a lot of one-off things for agencies.

How about calling it timetable_notes.txt and allowing specifying:

note_id
timetabled_id which timetable to apply this to
reference_type: "timetable", "stop", "trip" or "stoptime"
reference_id: id of the timetable, stop, trip or stoptime
symbol:
note:

So an example would look like:

note_id: 1
timetabled_id: 20
reference_type: stop
reference_id: 5684
symbol: *
note: This stop is sometimes underwater due to flooding

Please let me know what you think of the proposed field names and if this would be flexible enough to accommodate all possible scenarios.

[brendannee]

Just checking in on this - does my proposal above sound like it would be flexible enough to cover all scenarios you would want notes for?

[antrim]

Thank you for checking on this. To further brainstorm, here are some ideas & questions.

1: Do we think it would be useful to provide notes that aren't tied to a particular timetable? e.g. A note that is attached to a stop for all timetables?

2: I think it will be useful for notes to have multiple references (e.g. applies to many trips or stops). So, I suggest that we add a timetable_notes_references.txt with fields note_id, stop_id, timetable_id, trip_id, route_id, stop_sequence. If a record references just to stop_id, then it applies for all uses of that stop. But if the reference is to stop_id and timetable_id, then it applies to the stop_id only for that timetable_id, etc. And, multiple rows can reference the same note_id. Multiple rows are not combinatory in their targeting.

3: Default numbering scheme. In cases where a symbol is not provided, should the software automatically generate letters and/or numbers?

I did some looking on the web for examples:

http://old.mbta.com/uploadedFiles/Documents/Schedules_and_Maps/Bus/routesilverwater(1).pdf

https://trimet.org/schedules/s/t1100_1.htm

*: This trip ends at Elmonica/SW 170th Ave MAX Station (Stop ID 9829). For service to Hillsboro Central Transit Center, ride bus Line 57 from Beaverton Transit Center.
Y: At Rose Quarter Transit Center, this MAX turns into a Yellow Line train bound for Expo Center.

[antrim]

BTW, this isn't urgent for @trilliumtransit needs right now. But, definitely something we would use in the future. Just putting these comments in here to start considering the feature.

[brendannee]

Here is an updated proposal for two additional non-standard GTFS files:

timetable_notes.txt

• note_id (string)
• symbol (string, optional if omitted an auto-generated letter will be used)
• note (string)

example

note_id: 1
symbol: *
note: This stop is sometimes underwater due to flooding

timetable_notes_references.txt

• note_id (string)
• timetable_id (string, optional)
• route_id (string, optional)
• trip_id (string, optional)
• stop_id (string, optional)
• stop_sequence (string, optional)

examples

note_id: 1
timetable_id: 5
trip_id: 567
stop_id: 88
stop_sequence: 1
(applies only to a specific stop on a specific trip on a specific timetable at a specific stop_sequence, in cases where the same stop_id is used more than once in a trip)

note_id: 2
route_id: 12
stop_id: 88
(applies note to stop everywhere it appears as part of a specific route)

note_id: 3
trip_id: 12
(applies note to a specific trip)

note_id: 4
stop_id: 88
(applies note to stop everywhere it appears)

note_id: 5
timetable_id: 66
(applies note to a specific timetable)

note_id: 6
route_id: 3
(applies note to a all timetables for a specific route)

• Are there more use cases to consider?
• Would this setup be flexible enough to handle most timetable notes that occur?
• Any suggestions of the field names or file names?

[brendannee]

I have a working version of GTFS-to-HTML with footnote support on this branch: https://github.com/BlinkTagInc/gtfs-to-html/tree/feature/timetable-notes. I'm very interested in your feedback.

An example of the output is here: https://gtfs-to-html-notes-demo.vercel.app/20200913-20201212/17.html

The timetable_notes.txt and timetable_notes_references.txt files used to generate this are attached.
timetable_notes.txt
timetable_notes_references.txt

The first timetable on this page has examples of several types of notes:

• Note a applies to only a specific timetable (this one). None of the other timetables on this timetable_page have this note.

• Note b applies only to a specific route. Since all of the timetables on this page are for this route, it shows up for all.

• Note c applies only to a specific trip. It shows up in the trip header and also for each timepoint on that trip in all timetables that have that trip.

• Note d applies only to a specific stop. It shows up by the stop name and also for each timepoint at that stop in all timetables.

• Note e applies only to a specific stop and stop_sequence. It shows up by the stop name and also for each timepoint at that stop in all timetables only if that stop has that stop_sequence value for any trip in that timetable.

• Note § applies only to a specific stop and trip. It only shows up by the timepoint that matches the specific trip and stop it is for. This is an example of a note that has a symbol specified in timetable_notes.txt.

A few observations and questions:

• Notes can have a symbol specified or can be left blank and GTFS-to-HTML will assign a letter a-z to it (falling back to using integers if more than 26 symbols are needed)

• When a note is auto-assigned a symbol, currently that symbol is not guaranteed to be the same for each timetable. You'll notice on this page that the same note gets different letters on different timetables. Does this seem like a bad thing?

• Is it too noisy to have notes that apply to entire stops or entire trips show up for each timepoint for that stop or trip?

• This new footnote feature is not a breaking change for GTFS-to-HTML so I can merge it into master once it looks good and mark it as an experimental feature.

[brodyFlannigan]

• Is it too noisy to have notes that apply to entire stops or entire trips show up for each timepoint for that stop or trip?

I feel it should be an option in timetable_notes_reference.txt to make the note "noisy". Maybe just an enum value.

[brendannee]

@brodyFlannigan @antrim I'd like to know if there are agencies that currently have notes that apply to entire trips or entire stops where they apply a symbol to each timepoint in a timetable. I don't think I've ever seen this, so maybe it is not a needed config option and it should not be "noisy" at all.

There are a few ways users of GTFS-to-HTML could deal with the "noisy" issue to notes that apply to entire trips or entire stops.

• GTFS-to-HTML could never be "noisy" and if users want notes to show up for each timepoint of a trip they can explicitly add the trip_id stop_id combination to timetable_notes_references.txt for each stoptime. This avoids needing any additional fields.

• Users could use a custom template for GTFS-to-HTML to control if these types of notes show up for stoptimes (this is somewhat technical though - not a good option if many agencies want this feature)

• GTFS-to-HTML could have a noisy field in timetable_notes_references.txt (but I'd want to think of a better name for the
  field) so that users can control the nosiness of each individual note. If going this route, should it be noisy by default or not noisy?

• GTFS-to-HTML could have a field in config.json that sets the noisiness for notes for all timetables (so users could not control it on a note-by-note basis).

[brodyFlannigan]

@brendannee I think the third option (field in GTFS) is the best option for sure.

I think recursive could be a good field name but others may have better suggestions.

[antrim]

• When a note is auto-assigned a symbol, currently that symbol is not guaranteed to be the same for each timetable. You'll notice on this page that the same note gets different letters on different timetables. Does this seem like a bad thing?

Doesn't seem ideal but also doesn't seem terrible. If it matters a lot, users could manually assign notes.

• Is it too noisy to have notes that apply to entire stops or entire trips show up for each timepoint for that stop or trip?

My initial reaction is that GTFS-to-HTML should produce less "noisy" timetables by default. Take that as just an initial reaction.

I don't know that I've seen notes carried all the way through columns or rows like that on timetables. Want me to ask for opinions and/or examples from Trillium's website team?

Alternative/complementary idea: Adding style classes for notes -- e.g. <td class="timetable-note-a"> -- would make it possible to indicate rows, columns, and cells to which a note applies visually.

• This new footnote feature is not a breaking change for GTFS-to-HTML so I can merge it into master once it looks good and mark it as an experimental feature.

Awesome! Also, I love the example footnotes that you've noted.

One other thought:

Anchor links for the notes would be helpful. This might be especially useful for screenreader users. Example: https://trimet.org/schedules/w/t1090_1.htm

[brodyFlannigan]

Anchor links for the notes would be helpful. This might be especially useful for screenreader users. Example: https://trimet.org/schedules/w/t1090_1.htm

+1 on that for sure.

[brendannee]

I pushed an update based on all of your comments.

Latest code on branch branch: https://github.com/BlinkTagInc/gtfs-to-html/tree/feature/timetable-notes

Updated example of the output is here: https://gtfs-to-html-notes-demo.vercel.app/20200913-20201212/17.html

The timetable_notes.txt and timetable_notes_references.txt files used to generate this are attached.
timetable_notes.txt
timetable_notes_references.txt

Here is what has changed:

• timetable_notes_references.txt now has an optional show_on_stoptime field which defaults to 0. This controls whether or not a note should show up for all stops ("noisy") or not.

• You can see on https://gtfs-to-html-notes-demo.vercel.app/20200913-20201212/17.html that notes c and e are noisy while note d is not.

• Notes now have a class with the note_id in it, so individual notes can be hidden or styled via css. For example class="timetable-note-4"

• Notes are now anchor links to their definitions.

Please send me any additional feedback or adjustments you can think of, no matter how minor. What do you think of the field name show_on_stoptime?

The next step will be to merge into master and document the feature.

[brodyFlannigan]

@brendannee Awesome 🎉

[brendannee]

I just merged this in to GTFS-to-HTML version 1.3.0.

I added documentation about the new feature:

https://gtfstohtml.com/docs/timetable-notes
https://gtfstohtml.com/docs/timetable-notes-references

All feedback is appreciated, including ideas on how to better communicate this complex feature in the documentation. Let me know when you start using this with an agency.