Sets the dwell time of each specified trip_id at each specified stop_id,
i.e. the time the vehicle stays at the stop for passengers to board and
alight, by changing the times at these stops in stop_times. By default,
the later times of the trips are shifted accordingly. Alternatively, the
trip durations are kept and the running times between stops absorb the
change.
Usage
set_dwell_time(
gtfs,
dwell_time,
unit = "s",
strategy = "shift_trip_end",
trip_id = NULL,
stop_id = NULL,
from = NULL,
to = NULL,
route_type = NULL,
by_reference = FALSE
)Arguments
- gtfs
A GTFS object, as created by
read_gtfs().- dwell_time
A non-negative number, the dwell time to be set, in
unit. It's rounded to the nearest whole second and applies to every specified visit (call the function once per value to set different dwell times).- unit
A string representing the time unit in which
dwell_timeis given. One of"s"(seconds, the default),"min"(minutes),"h"(hours) or"d"(days).- strategy
A string, how the trips absorb the changes in dwell time. One of:
"shift_trip_end"(the default): keeps the running times between stops and shifts all the later times of the trip, so the arrival at the last stop moves later (or earlier, if dwell times are shortened). It preserves the implicit average speed between stops but changes the trip duration."keep_total_duration": centres each intermediate stop's dwell on its original time, taking half of the change from the running time before the stop and half from the one after it. The first and last stops are not changed, so the trip keeps its duration, its arrival at the last stop and the implicit average speed between its first and last stops. An error is raised if a running time would become negative.
- trip_id
A character vector including the
trip_ids to have their dwell times set. IfNULL(the default), the dwell times of everytrip_idin the GTFS (or of every trip of the givenroute_types) are set.- stop_id
A character vector including the
stop_ids at which the dwell times are set. IfNULL(the default), the dwell times are set at everystop_idin the GTFS.- from
A string, in the "HH:MM:SS" format. Only visits whose arrival time is at or after
fromare changed. IfNULL(the default), there is no lower limit.- to
A string, in the "HH:MM:SS" format. Only visits whose arrival time is at or before
toare changed. IfNULL(the default), there is no upper limit.- route_type
An integer vector of
route_types (seefilter_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 inroutesare ignored. IfNULL(the default), trips of any type are changed.- by_reference
Whether to update
stop_times'data.tableby reference. Defaults toFALSE.
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 departures of trips listed in frequencies are never changed, because
frequencies_to_stop_times() anchors each of them on the first departure
of the trip's template. Blank arrival or departure times are never filled.
For trips listed in frequencies, the times in stop_times are a template
(see frequencies_to_stop_times()), so setting the dwell time at the first
stop only changes how long before each departure the vehicle arrives there,
while changes at later stops lengthen or shorten every 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 (with by_reference = TRUE,
even if an error is then raised).
from and to are compared with the arrival_time of each visit as written
in stop_times before any change other than this fix (template times, for
trips listed in frequencies), so use times past "24:00:00" for arrivals
after midnight. A shift caused by an earlier visit may thus move a changed
visit out of the time of day, or another visit into it. Visits with a blank
arrival time are never selected when from or to is given. When the time
of day contains no visit of the specified trips to the specified stops, the
GTFS is returned with no change other than this fix.
stop_ids are matched against the stop_ids in stop_times, which are
never stations: to set the dwell times at a station, pass its children that
appear in stop_times (see get_children_stops()). Existing _secs
columns in stop_times (e.g. created with convert_time_to_seconds()) are
updated to match.
Examples
library(dplyr)
data_path <- system.file("extdata/spo_gtfs.zip", package = "gtfstools")
gtfs <- read_gtfs(data_path)
# set a 30 seconds dwell time at a stop of a trip. the later times of the
# trip are shifted by 30 seconds
new_gtfs <- set_dwell_time(
gtfs,
trip_id = "CPTM L07-0",
stop_id = "18920",
dwell_time = 30
)
new_gtfs$stop_times |>
filter(trip_id == "CPTM L07-0") |>
head()
#> 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:30 18920 2
#> 3: CPTM L07-0 04:16:30 04:16:30 18919 3
#> 4: CPTM L07-0 04:24:30 04:24:30 18917 4
#> 5: CPTM L07-0 04:32:30 04:32:30 18916 5
#> 6: CPTM L07-0 04:40:30 04:40:30 18965 6
# set the dwell time at a stop in every trip that visits it. use the unit
# argument to give the dwell time in another unit
new_gtfs <- set_dwell_time(
gtfs,
stop_id = "18960",
dwell_time = 1,
unit = "min"
)
get_dwell_time(new_gtfs, stop_id = "18960")
#> trip_id stop_id stop_sequence dwell_time
#> <char> <char> <int> <num>
#> 1: CPTM L08-0 18960 7 60
#> 2: CPTM L08-1 18960 16 60
#> 3: CPTM L09-0 18960 1 60
#> 4: CPTM L09-1 18960 18 60
# set the dwell time only at the visits that arrive within a time of day
new_gtfs <- set_dwell_time(
gtfs,
trip_id = "CPTM L07-0",
dwell_time = 30,
from = "05:00:00",
to = "06:00:00"
)
get_dwell_time(new_gtfs, trip_id = "CPTM L07-0")
#> trip_id stop_id stop_sequence dwell_time
#> <char> <char> <int> <num>
#> 1: CPTM L07-0 18940 1 0
#> 2: CPTM L07-0 18920 2 0
#> 3: CPTM L07-0 18919 3 0
#> 4: CPTM L07-0 18917 4 0
#> 5: CPTM L07-0 18916 5 0
#> 6: CPTM L07-0 18965 6 0
#> 7: CPTM L07-0 18923 7 0
#> 8: CPTM L07-0 18922 8 0
#> 9: CPTM L07-0 4114459 9 30
#> 10: CPTM L07-0 18921 10 30
#> 11: CPTM L07-0 18924 11 30
#> 12: CPTM L07-0 18925 12 30
#> 13: CPTM L07-0 18926 13 30
#> 14: CPTM L07-0 18971 14 30
#> 15: CPTM L07-0 18972 15 30
#> 16: CPTM L07-0 18973 16 30
#> 17: CPTM L07-0 18974 17 0
#> 18: CPTM L07-0 18975 18 0
# keep the trip duration: the running times between the stops absorb the
# dwell times, and the arrival at the last stop doesn't change
new_gtfs <- set_dwell_time(
gtfs,
trip_id = "CPTM L07-0",
dwell_time = 30,
strategy = "keep_total_duration"
)
new_gtfs$stop_times |>
filter(trip_id == "CPTM L07-0") |>
tail()
#> trip_id arrival_time departure_time stop_id stop_sequence
#> <char> <char> <char> <char> <int>
#> 1: CPTM L07-0 05:35:45 05:36:15 18926 13
#> 2: CPTM L07-0 05:43:45 05:44:15 18971 14
#> 3: CPTM L07-0 05:51:45 05:52:15 18972 15
#> 4: CPTM L07-0 05:59:45 06:00:15 18973 16
#> 5: CPTM L07-0 06:07:45 06:08:15 18974 17
#> 6: CPTM L07-0 06:16:00 06:16:00 18975 18
# original gtfs remains unchanged
get_dwell_time(gtfs, stop_id = "18960")
#> trip_id stop_id stop_sequence dwell_time
#> <char> <char> <int> <num>
#> 1: CPTM L08-0 18960 7 0
#> 2: CPTM L08-1 18960 16 0
#> 3: CPTM L09-0 18960 1 0
#> 4: CPTM L09-1 18960 18 0
# when doing by reference, original gtfs is changed
set_dwell_time(
gtfs,
trip_id = "CPTM L07-0",
stop_id = "18920",
dwell_time = 30,
by_reference = TRUE
)
gtfs$stop_times |>
filter(trip_id == "CPTM L07-0") |>
head()
#> 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:30 18920 2
#> 3: CPTM L07-0 04:16:30 04:16:30 18919 3
#> 4: CPTM L07-0 04:24:30 04:24:30 18917 4
#> 5: CPTM L07-0 04:32:30 04:32:30 18916 5
#> 6: CPTM L07-0 04:40:30 04:40:30 18965 6
