Skip to contents

Fills blank arrival_times and departure_times in stop_times, or overwrites those of the intermediate stops of each trip, assuming that vehicles travel at a constant speed between consecutive stops with known times (timepoints).

Usage

interpolate_stop_times(
  gtfs,
  trip_id = NULL,
  method = "shapes",
  overwrite = FALSE,
  keep_dwell_times = TRUE
)

Arguments

gtfs

A GTFS object, as created by read_gtfs().

trip_id

A character vector including the trip_ids to have their stop times interpolated. If NULL (the default), the function interpolates the stop times of every trip_id in the GTFS.

method

A string, either "shapes" (the default) or "euclidean". "shapes" measures lengths along the trip's shape, described in the shapes table, while "euclidean" measures the straight-line (great-circle) distances between consecutive stops. If the GTFS object doesn't have a shapes table, or if its trips table doesn't have a shape_id column, "euclidean" is used instead, with a warning.

overwrite

A logical. If FALSE (the default), only blank times are filled. If TRUE, the times of every stop between the first and the last stop of each trip (in stop_sequence order) are replaced by interpolated ones, so only the trips' first and last times are used. Trips whose times can't be interpolated keep their original times as they are, with a warning, so blanks that overwrite = FALSE would fill in some of their stops may be left blank.

keep_dwell_times

A logical. Only used when overwrite = TRUE. If TRUE (the default), the stops between the first and the last keep their original dwell times (the difference between their departure and arrival times), and the remaining time is spread over the distance travelled. Dwell times that can't be calculated (e.g. a blank time) or that are negative (e.g. a stop arriving at "23:59:00" and departing at "00:01:00") are taken as 0. If FALSE, interpolated stops get equal arrival and departure times.

Value

A GTFS object whose stop_times has its blank times filled in (or, with overwrite = TRUE, the times of its intermediate stops replaced). The order of the rows and the other columns are kept. The given GTFS object is not modified.

Details

Within each trip, in stop_sequence order, a stop whose arrival and departure times are both blank gets a time interpolated linearly on the distance travelled from the preceding timepoint, as measured by get_trip_length() (if the distance between two timepoints is 0, their times are spread evenly between the stops in between). Interpolated stops get equal arrival and departure times, rounded to the nearest second, unless they keep their dwell times (see keep_dwell_times). Times past "24:00:00" are supported. A timepoint with only one of its two times blank gets the other time in both columns. If stop_times has a timepoint column, interpolated stops get timepoint = 0; the column is not created otherwise.

Some stops are left blank, with a warning:

  • stops before a trip's first or after its last timepoint, including every stop of trips with fewer than two timepoints;

  • stops between timepoints whose distance can't be calculated, e.g. trips not linked to a shape or stops without coordinates;

  • stops between timepoints in which the arrival is earlier than the previous departure. 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, and only times that go back by 12 hours or less remain.

Times are blank when they are NA, empty or whitespace-only strings, or "NA". Malformed time strings are left unchanged (unless overwritten with overwrite = TRUE), with a warning, and are not used as timepoints. Rows without a trip_id are left unchanged. For trips listed in frequencies, the template times are interpolated. Times are read from the time strings, and existing _secs columns (e.g. created with convert_time_to_seconds()) are updated to match.

Interpolating between timepoints requires the stops table.

Examples

library(dplyr)

data_path <- system.file("extdata/poa_gtfs.zip", package = "gtfstools")
gtfs <- read_gtfs(data_path)
trip <- "T2-1@1#520"

# only the first and last stops of each trip have times
gtfs$stop_times |>
  filter(trip_id == trip) |>
  head()
#>       trip_id arrival_time departure_time stop_id stop_sequence
#>        <char>       <char>         <char>  <char>         <int>
#> 1: T2-1@1#520     05:20:00       05:20:00    3609             1
#> 2: T2-1@1#520                                3608             2
#> 3: T2-1@1#520                                3564             3
#> 4: T2-1@1#520                                6336             4
#> 5: T2-1@1#520                                3633             5
#> 6: T2-1@1#520                                5544             6

# distances measured along the trips' shapes. some trips of this feed have
# times past midnight written as "00:xx:xx", which are fixed first
interpolated_gtfs <- suppressWarnings(interpolate_stop_times(gtfs))
interpolated_gtfs$stop_times |>
  filter(trip_id == trip) |>
  head()
#>       trip_id arrival_time departure_time stop_id stop_sequence
#>        <char>       <char>         <char>  <char>         <int>
#> 1: T2-1@1#520     05:20:00       05:20:00    3609             1
#> 2: T2-1@1#520     05:20:27       05:20:27    3608             2
#> 3: T2-1@1#520     05:22:00       05:22:00    3564             3
#> 4: T2-1@1#520     05:24:02       05:24:02    6336             4
#> 5: T2-1@1#520     05:25:55       05:25:55    3633             5
#> 6: T2-1@1#520     05:26:31       05:26:31    5544             6

# the speed is now known between every pair of consecutive stops
head(get_trip_speed(interpolated_gtfs, trip, by = "segment"))
#>    route_id    trip_id segment from_stop_id to_stop_id    speed
#>      <char>     <char>   <int>       <char>     <char>    <num>
#> 1:       T2 T2-1@1#520       1         3609       3608 18.97450
#> 2:       T2 T2-1@1#520       2         3608       3564 19.07504
#> 3:       T2 T2-1@1#520       3         3564       6336 19.04637
#> 4:       T2 T2-1@1#520       4         6336       3633 19.05867
#> 5:       T2 T2-1@1#520       5         3633       5544 19.32197
#> 6:       T2 T2-1@1#520       6         5544       3644 18.78885

# straight-line distances between stops, for a single trip
interpolated_gtfs <- interpolate_stop_times(
  gtfs,
  trip_id = trip,
  method = "euclidean"
)
interpolated_gtfs$stop_times |>
  filter(trip_id == trip) |>
  head()
#>       trip_id arrival_time departure_time stop_id stop_sequence
#>        <char>       <char>         <char>  <char>         <int>
#> 1: T2-1@1#520     05:20:00       05:20:00    3609             1
#> 2: T2-1@1#520     05:20:29       05:20:29    3608             2
#> 3: T2-1@1#520     05:21:30       05:21:30    3564             3
#> 4: T2-1@1#520     05:23:27       05:23:27    6336             4
#> 5: T2-1@1#520     05:25:21       05:25:21    3633             5
#> 6: T2-1@1#520     05:26:01       05:26:01    5544             6