
Convert frequencies to stop times
Source:R/frequencies_to_stop_times.R
frequencies_to_stop_times.RdCreates stop_times entries based on the frequencies specified in the
frequencies table.
Arguments
- gtfs
A GTFS object, as created by
read_gtfs().- trip_id
A character vector including the
trip_ids to have their frequencies converted tostop_timesentries. IfNULL(the default), the function converts all trips listed in thefrequenciestable.- force
Whether to convert trips specified in the
frequenciestable even if they are not described instop_times(defaults toFALSE). When set toTRUE, these mismatched trip are removed from thefrequenciestable and their correspondent entries intripsare substituted by what would be their converted counterpart.- strategy
A string. The strategy used to set the departure times of the trips created from frequency-based entries of the
frequenciestable (i.e. those whoseexact_timesis not1). One of:"exact"(the default): trips depart everyheadway_secsfromstart_time;"half_headway": departures are shifted by half the headway, rounded down to whole seconds;"random": departures are shifted by a random whole number of seconds, from 0 up to (but not including) the headway, drawn independently for each entry. Uses R's random number generator, so results can be made reproducible withset.seed().
In entries shorter than their headway, the duration of the entry (from
start_timetoend_time) is used in place of the headway, so that no departure is shifted to or pastend_timeand each entry still yields at least one trip. As departures are shifted towardsend_time, an entry may yield one trip fewer than with"exact". Entries whoseexact_timesis1follow an exact schedule and are always converted as with"exact".
Details
A single trip described in a frequencies table may yield multiple trips
after converting the GTFS. Let's say, for example, that the frequencies
table describes a trip called "example_trip", that starts at 08:00 and
stops at 09:00, with a 30 minutes headway.
In practice, with the default strategy = "exact", that means that one trip
will depart at 08:00 and another at 08:30. As required by the GTFS
specification, no trip departs at the end_time (09:00), which is when the
headway changes or the service ceases.
An entry whose start_time and end_time are equal yields a single trip,
departing at that time. frequencies_to_stop_times() appends a "_<n>"
suffix to the newly created trips to differentiate each one of them (e.g. in
this case, the new trips, described in the trips and stop_times tables,
would be called "example_trip_1" and "example_trip_2").
The times of each new trip are those of its template, shifted so that it departs from the first stop at the departure time. When the template has a dwell time at the first stop, a departure close to midnight may yield an arrival before 00:00:00, which is set to 00:00:00 instead.
Existing _secs columns in stop_times and frequencies (e.g. created
with convert_time_to_seconds()) are used as-is, not recalculated from the
time strings.
Examples
library(dplyr)
data_path <- system.file("extdata/spo_gtfs.zip", package = "gtfstools")
gtfs <- read_gtfs(data_path)
trip <- "CPTM L07-0"
# converts all trips listed in the frequencies table
converted_gtfs <- frequencies_to_stop_times(gtfs)
# converts only the specified trip_id
converted_gtfs <- frequencies_to_stop_times(gtfs, trip)
# how the specified trip_id was described in the frequencies table
gtfs$frequencies |>
filter(trip_id == trip) |>
head()
#> trip_id start_time end_time headway_secs
#> <char> <char> <char> <int>
#> 1: CPTM L07-0 04:00:00 04:59:00 720
#> 2: CPTM L07-0 05:00:00 05:59:00 360
#> 3: CPTM L07-0 06:00:00 06:59:00 360
#> 4: CPTM L07-0 07:00:00 07:59:00 360
#> 5: CPTM L07-0 08:00:00 08:59:00 360
#> 6: CPTM L07-0 09:00:00 09:59:00 480
# the first row of each equivalent stop_times entry in the converted gtfs
converted_gtfs$stop_times |>
filter(grepl(trip, trip_id)) |>
distinct(trip_id, .keep_all = TRUE)
#> trip_id arrival_time departure_time stop_id stop_sequence
#> <char> <char> <char> <char> <int>
#> 1: CPTM L07-0_1 04:00:00 04:00:00 18940 1
#> 2: CPTM L07-0_2 04:12:00 04:12:00 18940 1
#> 3: CPTM L07-0_3 04:24:00 04:24:00 18940 1
#> 4: CPTM L07-0_4 04:36:00 04:36:00 18940 1
#> 5: CPTM L07-0_5 04:48:00 04:48:00 18940 1
#> ---
#> 157: CPTM L07-0_157 23:00:00 23:00:00 18940 1
#> 158: CPTM L07-0_158 23:12:00 23:12:00 18940 1
#> 159: CPTM L07-0_159 23:24:00 23:24:00 18940 1
#> 160: CPTM L07-0_160 23:36:00 23:36:00 18940 1
#> 161: CPTM L07-0_161 23:48:00 23:48:00 18940 1