-
Notifications
You must be signed in to change notification settings - Fork 30
User Interface String Display Logic
This page describes the logic of various front-end UI’s and API’s and how it changes around:
- Explicit accounting of formal (i.e. run/block-based) vs. informal (i.e. trip/route-based) inference
- Addition of time-based predictions
Concepts for this discussion:
- consider a customer or API client querying for information regarding buses that will stop at a particular stop. This stop is “the given stop”. For the context of this discussion, the given stop is served by a single route.
- “the terminal” is the terminus, for that single route, from which buses depart on trips that will serve the given stop.
- “wrapped trips” are trips on a block that includes a trip that departs from the terminal and serves the given stop, and are (in that block) prior to the trip that will serve the given stop
- “wrapped buses” are buses on wrapped trips
- “formal” means the bus is matched to a trip and block, allowing projection into the future for what trips the bus will serve after the current one (i.e. the bus can be “wrapped” onto future trips).
- “informal” means the bus is matched to a trip only (not a block), not allowing projection into the future for what trips the bus will serve after the current one.
The following discussion is with respect to a query for buses serving the given stop. The concepts should generalize cleanly to a stop served by multiple routes; it’s just that each route has its own terminal, etc.
A simple decision rule will dictate if stops or miles are shown to the end user:
show distance in miles if and only if:
(distance in miles to immediate next stop is > D) OR (distance in stops to current stop is > N AND distance in miles to current stop > E)
in other words, show distance in stops if and only if:
(distance in miles to immediate next stop is <= D) AND (distance in stops to current stop <= N OR distance in miles to current stop <= E)
Show “approaching” if and only if:
distance_in_miles to immediate next stop < P
show “at stop” if and only if:
distance_in_miles to immediate next stop < T
Current/default Parameter Values:
D: .5 miles
N: 3 stops
E: .5 miles
P: 500 feet
T: 100 feet
These values are configurable through the admin console.
Initially, the system would only present to the user those buses which are between the initial terminal and a stop (i.e. immediately inbound buses). It now also shows information about buses which will turn around at a terminal before heading towards the current stop. That is, when looking at a stop on an eastbound stop, the system will not only show eastbound buses that are inbound, but also westbound buses which are near the end of their run (at which point they will turn around and become eastbound buses).
Pre-departure behavior depends on the formality of the inference for a given vehicle—if block level inference is present, the departure time for the next trip to be served is offered; if informal, no estimate is given. See below for more details.
- under no circumstances return information about wrapped buses
- under no circumstances return information about the scheduled departure time of buses at the terminal
- under no circumstances include block_id in API call results
In UI’s, when the bus is at a terminal on a given trip, display distance and or time prediction along with:
Desktop and Mobile:
| Layover | Non-Layover | |
| Previous Trip | No additional information | No additional information |
| Current Trip | “(at terminal)” | No additional information |
SMS:
| Layover | Non-Layover | |
| Previous Trip | No additional information | No additional information |
| Current Trip | “(@term.)” | No additional information |
- always include block_id in API call results (SIRI MonitoredVehicleJourney’s have a BlockRef element)
- when a bus is at the terminal in a layover state, include the scheduled departure time from the terminal in API call results (i.e. OriginAimedDepartureTime which is child element of the MonitoredVehicleJourney) and in the UI.
- When the scheduled departure time is in the future, say “at terminal, scheduled to depart at HH:MM”
- wrapped buses should only be included when they are on the trip immediately prior to the trip that will serve the given stop, and are below a hard distance away limit (X).
- default value of X is 5 miles, configurable via the TDM.
- N.B.: In time this threshold may evolve to a more time-based notion (e.g. buses predicted to be within X minutes of the given stop, even if they are 2 or more trips back)
- include wrapped buses in API call results at the stop level (i.e. SIRI SM). There is no need to include information about future trips or stops on those trips in API call results at the vehicle level (i.e. SIRI VM).
- Set ProgressStatus to “prevTrip” in the stop-level API result (i.e. SIRI SM) to indicate that the bus is wrapped, and thus (a) is further away from the given stop than the given stop is from the terminal, and (b) has a layover standing between it and the given stop.
- In SIRI SM, the MonitoredVehicleJourney for the wrapped trip should only show information about the trip on which the bus will serve the given stop. This includes:
- Scalars, including: LineRef, DirectionRef, Origin/Destination Ref’s, Destination Sign Text, FramedVehicleJourneyRef (i.e. trip_id), and OriginAimedDepartureTime.
- OnwardCalls: start with the first stop on the trip on which the bus will serve the given stop (which may not be the immediate next stop for that bus), continue through all stops on that trip but no further.
In UI’s:
Desktop and Mobile:
| Layover | Non-Layover | |
| Previous Trip | 1) No additional information if previous terminal is greater than 5 miles of current terminal 2) “(at terminal, scheduled to depart HH:MM)” if previous terminal is within 5 miles of current terminal (even for short routes) |
1) No additional information if vehicle is further than 5 miles of current terminal 2) “(+scheduled layover at terminal)” if within 5 miles of current terminal then show |
| Current Trip | 1) “(at terminal, scheduled to depart HH:MM)” if current time is less than or equal to departure time HH:MM 2) “(at terminal)” if current time is greater than departure time HH:MM |
No additional information |
SMS:
| Layover | Non-Layover | |
| Previous Trip | 1) No additional information if previous terminal is greater than 5 miles of current terminal 2) “(@term.)” if previous terminal is within 5 miles of current terminal (short routes) |
1) No additional information if vehicle is further than 5 miles from current terminal 2) “(+layover@term.)” if within 5 miles of current terminal |
| Current Trip | 1) “(at term. sched. dep. HH:MM)” if current time is less than or equal to departure time HH:MM 2) “(at term.)” if current time is greater than departure time HH:MM |
No additional information |
- display distance only.
NOTE: This discussion assumes that the time-based predictions are singular for each stop. That is, stops are not given independent predictions for arrival vs departure time.
Thus, we can define “the predicted time” to describe the time prediction associated with a given bus at a given stop.
In API call results:
- include the predicted time for all stops shown for all buses shown (i.e. all Monitored and OnwardCall elements)
- for origin terminals, this should be labeled as the departure time (i.e. EstimatedDepartureTime)
- for all other stops this should be labeled as the arrival time (i.e. EstimatedArrivalTime)