set_dwell_time: Set dwell time

In gtfstools: General Transit Feed Specification (GTFS) Editing and Analysing Tools

Set dwell time

Description

Sets the dwell time of each specified trip_id at each specified stop_id, i.e. the time the vehicle stays at the stop, by changing the departure_time at these stops in stop_times and shifting the later times of the trips accordingly.

Usage

set_dwell_time(
  gtfs,
  dwell_time,
  unit = "s",
  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_time is given. One of "s" (seconds, the default), "min" (minutes), "h" (hours) or "d" (days).
trip_id	A character vector including the trip_ids to have their dwell times set. If NULL (the default), the dwell times of every trip_id in the GTFS (or of every trip of the given route_types) are set.
stop_id	A character vector including the stop_ids at which the dwell times are set. If NULL (the default), the dwell times are set at every stop_id in the GTFS.
from	A string, in the "HH:MM:SS" format. Only visits whose arrival time is 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 visits whose arrival time is 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 dwell time of a visit is its departure_time minus its arrival_time in stop_times, as returned by get_dwell_time(). It is set at the visits of every specified trip to every specified stop (not of pairs formed by their elements): the arrival time is kept and the departure time is set to the arrival time plus dwell_time. All the later times of the trip, in stop_sequence order, are shifted by the change, and changes at several visits of the same trip add up. At a trip's last stop, only the departure time changes. A stop visited more than once by the same trip has its dwell time set at each visit.

Blank times are never filled. Selected visits with a blank arrival or departure time are not changed and don't shift the later times, with a warning when stop_id is given; fill them beforehand with interpolate_stop_times(). An error is raised if a shift would result in a negative time (times not in chronological order) or in a time later than "9999:59:59". stop_sequence is assumed to be unique within each trip and not NA. When both trip_id and stop_id are given but none of the trips visits any of the stops, a warning is raised and the GTFS is returned unchanged.

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.

from and to are compared with the arrival_time of each visit as written in stop_times before any change (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 unchanged.

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.

See Also

get_dwell_time(), set_min_dwell_time(), set_trip_speed()

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()

# 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")

# 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")

# original gtfs remains unchanged
get_dwell_time(gtfs, stop_id = "18960")

# 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()

gtfstools documentation built on Oct. 28, 2026, 5:13 p.m.