gtfstools (version 1.4.0)

set_trip_speed: Set trip average speed

Description

Sets the average speed of each specified trip_id by changing the arrival_time and departure_time columns in stop_times.

Usage

set_trip_speed(gtfs, trip_id, speed, unit = "km/h", by_reference = FALSE)

Value

If by_reference is set to FALSE, returns a GTFS object with the time columns of its stop_times adjusted. Else, returns a GTFS object invisibly (note that in this case the original GTFS object is altered).

Arguments

gtfs

A GTFS object, as created by read_gtfs().

trip_id

A string vector including the trip_ids to have their average speed set.

speed

A numeric representing the speed to be set. Its length must either equal 1, in which case the value is recycled for all trip_ids, or equal trip_id's length.

unit

A string representing the unit in which the speed is given. One of "km/h" (the default) or "m/s".

by_reference

Whether to update stop_times' data.table by reference. Defaults to FALSE.

Details

The average speed is calculated as the difference between the arrival time at the last stop minus the departure time at the first top, over the trip's length (as calculated via get_trip_geometry(), based on the shapes file). The arrival and departure times at all other stops (i.e. not the first neither the last) are set as "", which is written as NA with write_gtfs(). Some transport routing software, such as OpenTripPlanner, support specifying stop times like so. In such cases, they estimate arrival/departure times at the others stops based on the average speed as well. We plan to add that feature to this function in the future.

Examples

# \dontshow{
  old_dt_threads <- data.table::setDTthreads(1)
  on.exit(data.table::setDTthreads(old_dt_threads), add = TRUE)
# }
data_path <- system.file("extdata/spo_gtfs.zip", package = "gtfstools")

gtfs <- read_gtfs(data_path)

gtfs_new_speed <- set_trip_speed(gtfs, trip_id = "CPTM L07-0", 50)
gtfs_new_speed$stop_times[trip_id == "CPTM L07-0"]

# use the unit argument to change the speed unit
gtfs_new_speed <- set_trip_speed(
  gtfs,
  trip_id = "CPTM L07-0",
  speed = 15,
  unit = "m/s"
)
gtfs_new_speed$stop_times[trip_id == "CPTM L07-0"]

# original gtfs remains unchanged
gtfs$stop_times[trip_id == "CPTM L07-0"]

# when doing by reference, original gtfs is changed
set_trip_speed(gtfs, trip_id = "CPTM L07-0", 50, by_reference = TRUE)
gtfs$stop_times[trip_id == "CPTM L07-0"]