Skip to contents

On Time Performance

Source: vignettes/on_time_performance.Rmd
on_time_performance.Rmd

Overview

On-time performance is calculated from combined Onscreen BusOnTimePerformance and Zonar Schedule data.

Since Onscreen and RP (Routing and Planning) are directly integrated, the Onscreen data is relatively easy to retrieve. The Zonar data is not directly integrated with RP and has to be joined with the Onscreen data by Zone / Anchor name.

Because we have multiple systems recording arrival time, we have a set of decision rules the determine which record is used if the systems disagree. These rules are somewhat complex, but basically we use the arrival time that is close to the scheduled arrival time.

Retrieving OTP report data

The ?report_otp function retrieves and formats on-time performance data from Onscreen and Zonar. Key defaults are listed below:

  • Looks for database connection and Zonar API information etc. in environment variables; see vignette("data_sources_and_credentials").
  • Retrieves both AM (i.e., inbound trip) and PM (i.e. outbound trip) data; select via the ampm argument.
  • Retrieves data for the current day; select via the date argument.

For example, this will retrieve all available data for the current day:

while this will retrieve just the PM (i.e., outbound trip) data for the day before yesterday:

day <- as.character(Sys.Date() - lubridate::days(2))
otp <- report_otp(date = day, ampm = "PM")

Only a single day can be retrieved per function call, if you need to retrieve multiple days please iterate over them explicitly, e.g., with help("for") or help("lapply").

The report_otp() function returns a large number of variables to facilitate analysis of patterns and trends in on-time or unreported status etc. Some of the key variables included in the OTP report data are:

  • Date dttm Date
  • RPRoute chr Visible route id number
  • RPVehicle chr Vehicle number
  • ExpectedTime dttm Route anchor time
  • Arrival dttm Arrival time calculated from combined Onscreen and Zonar data
  • DelayTimeCombined int Delay time calculated from combined Onscreen and ZOnar data, in minutes
  • TripOutcome chr Classification of trip outcome: “on time”, “late”, “unreported”, etc.

see ?report_otp for complete documentation of the remaining variables.

Updating OTP summary reports

After retrieving OTP data with report_otp() you may wish to use it to update OTP summary reports and data archives. This can be done using the update_otp_report() function.

By default update_otp_report() updates internal and external OTP summaries, as well as both AM and PM “raw” data files. The format of the “raw” data files is documented in ?prepare_raw_otp; the format of the summary files was undocumented at the time of this writing. The destinations to be updated can be specified via the *id arguments documented in ?update_otp_report; by default these are retrieved from environment variables as described in vignette("data_sources_and_credentials").

Note that update_otp_report calls summary.otpdata to calculate OTP summary statistics. See ?summary.otpdata for details about how these summaries are calculated.

Use cases and examples

Perhaps the most common use case is to retrieve and upload everything for the previous day. Assuming you have all credentials and targets set as environment variables (as described in vignette("data_sources_and_credentials")) this can be accomplished as follows:

## Get yesterday's date:
yesterday <- as.character(Sys.Date() - lubridate::days(1)) ## or specify as "YYYY-MM-DD"
otp <- report_otp(date = yesterday) ## retrieve and assign report data to `otp`.
update_otp_report(otp) ## update report summaries and "raw" data

Alternatively, you may wish to update just a subset of the targets, e.g. to share preliminary OTP numbers to the internal report. This can be accomplished by setting all target *id arguments to FALSE for all targets you wish to skip:

## OTP for this morning
otp_am <- report_otp(ampm = "AM") ## retrieve and assign AM trip report data to `otp_am`.
update_otp_report(
  otp_am, id=FALSE, dashboard_id=FALSE, am_raw_id=FALSE, pm_raw_id=FALSE) ## update internal only