Skip to contents

Creates stop_times entries based on the frequencies specified in the frequencies table.

Usage

frequencies_to_stop_times(
  gtfs,
  trip_id = NULL,
  force = FALSE,
  strategy = "exact"
)

Arguments

gtfs

A GTFS object, as created by read_gtfs().

trip_id

A character vector including the trip_ids to have their frequencies converted to stop_times entries. If NULL (the default), the function converts all trips listed in the frequencies table.

force

Whether to convert trips specified in the frequencies table even if they are not described in stop_times (defaults to FALSE). When set to TRUE, these mismatched trip are removed from the frequencies table and their correspondent entries in trips are 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 frequencies table (i.e. those whose exact_times is not 1). One of:

  • "exact" (the default): trips depart every headway_secs from start_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 with set.seed().

In entries shorter than their headway, the duration of the entry (from start_time to end_time) is used in place of the headway, so that no departure is shifted to or past end_time and each entry still yields at least one trip. As departures are shifted towards end_time, an entry may yield one trip fewer than with "exact". Entries whose exact_times is 1 follow an exact schedule and are always converted as with "exact".

Value

A GTFS object with updated frequencies, stop_times and trips tables.

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