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. IfNULL(the default), the function interpolates the stop times of everytrip_idin the GTFS.- method
A string, either
"shapes"(the default) or"euclidean"."shapes"measures lengths along the trip's shape, described in theshapestable, while"euclidean"measures the straight-line (great-circle) distances between consecutive stops. If the GTFS object doesn't have ashapestable, or if itstripstable doesn't have ashape_idcolumn,"euclidean"is used instead, with a warning.- overwrite
A logical. If
FALSE(the default), only blank times are filled. IfTRUE, the times of every stop between the first and the last stop of each trip (instop_sequenceorder) 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 thatoverwrite = FALSEwould fill in some of their stops may be left blank.- keep_dwell_times
A logical. Only used when
overwrite = TRUE. IfTRUE(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. IfFALSE, 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 withfix_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
