Skip to contents

Sets the average speed of each specified trip_id, or of a segment of it, by changing the arrival_time and departure_time columns in stop_times.

Usage

set_trip_speed(
  gtfs,
  trip_id = NULL,
  speed,
  unit = "km/h",
  first_stop = NULL,
  last_stop = NULL,
  from = NULL,
  to = NULL,
  route_type = NULL,
  by_reference = FALSE
)

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. If NULL (the default), route_type must be given, and the speed of every trip of these types is 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. Must be positive and finite. A trip_id listed more than once must be given the same speed. Must be a single number when trip_id is NULL.

unit

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

first_stop

A string. The stop_id where the segment whose speed is set starts. If NULL (the default), the segment starts at each trip's first stop.

last_stop

A string. The stop_id where the segment ends. If NULL (the default), the segment ends at each trip's last stop.

from

A string, in the "HH:MM:SS" format. Only trips that depart from the segment's first stop at or after from are changed. If NULL (the default), there is no lower limit.

to

A string, in the "HH:MM:SS" format. Only trips that depart from the segment's first stop at or before to are changed. If NULL (the default), there is no upper limit.

route_type

An integer vector of route_types (see filter_by_route_type()). If given, only trips of routes of these types are changed; together with the other selection arguments, it restricts their selection. route_types not listed in routes are ignored. If NULL (the default), trips of any type are changed.

by_reference

Whether to update stop_times' data.table by reference. Defaults to 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).

Details

The duration of each trip's segment, from the departure at first_stop to the arrival at last_stop, is set to its length divided by speed. Lengths are calculated by get_trip_length() along the trip's shape, or as straight lines between stops, with a warning, if there are no shapes; the stops table is required. Trips whose length is NA (e.g. not linked to a shape) are left unchanged.

The times at stops strictly inside the segment are set to "" (written as NA by write_gtfs()). Times after last_stop are shifted by the change in the segment's duration. Dwell times at first_stop and last_stop are kept, except at the trip's first and last stops, whose dwell time becomes 0. first_stop is matched at its first visit in stop_sequence order, and last_stop at its next visit after that (which may be the same stop). Blank times at last_stop are filled if it's the trip's last stop.

With first_stop or last_stop, trips that don't visit first_stop and then last_stop, or whose departure at first_stop is blank, or whose times at last_stop are both blank (unless it's the trip's last stop), are left unchanged, with a warning if they were given in trip_id. Without first_stop, last_stop, from and to, a blank departure at the trip's first stop leaves all the times of the trip blank, without a warning.

Times after midnight written as early morning times (e.g. "00:30:00" instead of "24:30:00") are first fixed with fix_overnight_times() in every trip, so the returned GTFS has them fixed (with by_reference = TRUE, even if an error is then raised).

from and to are compared with the departure_time at first_stop as written in stop_times, once fixed (template times, for trips listed in frequencies), so use times past "24:00:00" for departures after midnight; trips whose departure there is blank are then left unchanged. Existing _secs columns in stop_times are updated to match.

Examples

library(dplyr)

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 |>
  filter(trip_id == "CPTM L07-0")
#> Index: <trip_id>
#>        trip_id arrival_time departure_time stop_id stop_sequence
#>         <char>       <char>         <char>  <char>         <int>
#>  1: CPTM L07-0     04:00:00       04:00:00   18940             1
#>  2: CPTM L07-0                               18920             2
#>  3: CPTM L07-0                               18919             3
#>  4: CPTM L07-0                               18917             4
#>  5: CPTM L07-0                               18916             5
#>  6: CPTM L07-0                               18965             6
#>  7: CPTM L07-0                               18923             7
#>  8: CPTM L07-0                               18922             8
#>  9: CPTM L07-0                             4114459             9
#> 10: CPTM L07-0                               18921            10
#> 11: CPTM L07-0                               18924            11
#> 12: CPTM L07-0                               18925            12
#> 13: CPTM L07-0                               18926            13
#> 14: CPTM L07-0                               18971            14
#> 15: CPTM L07-0                               18972            15
#> 16: CPTM L07-0                               18973            16
#> 17: CPTM L07-0                               18974            17
#> 18: CPTM L07-0     05:12:42       05:12:42   18975            18

# 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 |>
  filter(trip_id == "CPTM L07-0")
#> Index: <trip_id>
#>        trip_id arrival_time departure_time stop_id stop_sequence
#>         <char>       <char>         <char>  <char>         <int>
#>  1: CPTM L07-0     04:00:00       04:00:00   18940             1
#>  2: CPTM L07-0                               18920             2
#>  3: CPTM L07-0                               18919             3
#>  4: CPTM L07-0                               18917             4
#>  5: CPTM L07-0                               18916             5
#>  6: CPTM L07-0                               18965             6
#>  7: CPTM L07-0                               18923             7
#>  8: CPTM L07-0                               18922             8
#>  9: CPTM L07-0                             4114459             9
#> 10: CPTM L07-0                               18921            10
#> 11: CPTM L07-0                               18924            11
#> 12: CPTM L07-0                               18925            12
#> 13: CPTM L07-0                               18926            13
#> 14: CPTM L07-0                               18971            14
#> 15: CPTM L07-0                               18972            15
#> 16: CPTM L07-0                               18973            16
#> 17: CPTM L07-0                               18974            17
#> 18: CPTM L07-0     05:07:19       05:07:19   18975            18

# set the speed only between two stops. later stops are shifted
gtfs_new_speed <- set_trip_speed(
  gtfs,
  trip_id = "CPTM L07-0",
  speed = 30,
  first_stop = "18917",
  last_stop = "18922"
)
gtfs_new_speed$stop_times |>
  filter(trip_id == "CPTM L07-0")
#> Index: <trip_id>
#>        trip_id arrival_time departure_time stop_id stop_sequence
#>         <char>       <char>         <char>  <char>         <int>
#>  1: CPTM L07-0     04:00:00       04:00:00   18940             1
#>  2: CPTM L07-0     04:08:00       04:08:00   18920             2
#>  3: CPTM L07-0     04:16:00       04:16:00   18919             3
#>  4: CPTM L07-0     04:24:00       04:24:00   18917             4
#>  5: CPTM L07-0                               18916             5
#>  6: CPTM L07-0                               18965             6
#>  7: CPTM L07-0                               18923             7
#>  8: CPTM L07-0     04:42:04       04:42:04   18922             8
#>  9: CPTM L07-0     04:50:04       04:50:04 4114459             9
#> 10: CPTM L07-0     04:58:04       04:58:04   18921            10
#> 11: CPTM L07-0     05:06:04       05:06:04   18924            11
#> 12: CPTM L07-0     05:14:04       05:14:04   18925            12
#> 13: CPTM L07-0     05:22:04       05:22:04   18926            13
#> 14: CPTM L07-0     05:30:04       05:30:04   18971            14
#> 15: CPTM L07-0     05:38:04       05:38:04   18972            15
#> 16: CPTM L07-0     05:46:04       05:46:04   18973            16
#> 17: CPTM L07-0     05:54:04       05:54:04   18974            17
#> 18: CPTM L07-0     06:02:04       06:02:04   18975            18

# set the speed only of the trips that depart within a time of day
poa_path <- system.file("extdata/poa_gtfs.zip", package = "gtfstools")
poa_gtfs <- read_gtfs(poa_path)

poa_new_speed <- set_trip_speed(
  poa_gtfs,
  trip_id = poa_gtfs$trips$trip_id,
  speed = 25,
  from = "07:00:00",
  to = "09:00:00"
)

# the arrival at the last stop of a trip that departs at 07:02 changes
poa_gtfs$stop_times |>
  filter(trip_id == "T2-1@1#702") |>
  slice_tail(n = 1)
#>       trip_id arrival_time departure_time stop_id stop_sequence
#>        <char>       <char>         <char>  <char>         <int>
#> 1: T2-1@1#702     08:03:00       08:03:00    1456            62

poa_new_speed$stop_times |>
  filter(trip_id == "T2-1@1#702") |>
  slice_tail(n = 1)
#> Index: <trip_id>
#>       trip_id arrival_time departure_time stop_id stop_sequence
#>        <char>       <char>         <char>  <char>         <int>
#> 1: T2-1@1#702     07:41:39       07:41:39    1456            62

# original gtfs remains unchanged
gtfs$stop_times |>
  filter(trip_id == "CPTM L07-0")
#>        trip_id arrival_time departure_time stop_id stop_sequence
#>         <char>       <char>         <char>  <char>         <int>
#>  1: CPTM L07-0     04:00:00       04:00:00   18940             1
#>  2: CPTM L07-0     04:08:00       04:08:00   18920             2
#>  3: CPTM L07-0     04:16:00       04:16:00   18919             3
#>  4: CPTM L07-0     04:24:00       04:24:00   18917             4
#>  5: CPTM L07-0     04:32:00       04:32:00   18916             5
#>  6: CPTM L07-0     04:40:00       04:40:00   18965             6
#>  7: CPTM L07-0     04:48:00       04:48:00   18923             7
#>  8: CPTM L07-0     04:56:00       04:56:00   18922             8
#>  9: CPTM L07-0     05:04:00       05:04:00 4114459             9
#> 10: CPTM L07-0     05:12:00       05:12:00   18921            10
#> 11: CPTM L07-0     05:20:00       05:20:00   18924            11
#> 12: CPTM L07-0     05:28:00       05:28:00   18925            12
#> 13: CPTM L07-0     05:36:00       05:36:00   18926            13
#> 14: CPTM L07-0     05:44:00       05:44:00   18971            14
#> 15: CPTM L07-0     05:52:00       05:52:00   18972            15
#> 16: CPTM L07-0     06:00:00       06:00:00   18973            16
#> 17: CPTM L07-0     06:08:00       06:08:00   18974            17
#> 18: CPTM L07-0     06:16:00       06:16:00   18975            18

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

gtfs$stop_times |>
  filter(trip_id == "CPTM L07-0")
#> Index: <trip_id>
#>        trip_id arrival_time departure_time stop_id stop_sequence
#>         <char>       <char>         <char>  <char>         <int>
#>  1: CPTM L07-0     04:00:00       04:00:00   18940             1
#>  2: CPTM L07-0                               18920             2
#>  3: CPTM L07-0                               18919             3
#>  4: CPTM L07-0                               18917             4
#>  5: CPTM L07-0                               18916             5
#>  6: CPTM L07-0                               18965             6
#>  7: CPTM L07-0                               18923             7
#>  8: CPTM L07-0                               18922             8
#>  9: CPTM L07-0                             4114459             9
#> 10: CPTM L07-0                               18921            10
#> 11: CPTM L07-0                               18924            11
#> 12: CPTM L07-0                               18925            12
#> 13: CPTM L07-0                               18926            13
#> 14: CPTM L07-0                               18971            14
#> 15: CPTM L07-0                               18972            15
#> 16: CPTM L07-0                               18973            16
#> 17: CPTM L07-0                               18974            17
#> 18: CPTM L07-0     05:12:42       05:12:42   18975            18