Sets the headway of each specified route_id within a given time of day, by
replacing its trips in that time of day with a single frequency-based trip,
described in the frequencies table.
Arguments
- gtfs
A GTFS object, as created by
read_gtfs().- route_id
A character vector including the
route_ids to have their frequency set.route_ids not listed intripsare ignored, with a warning. IfNULL(the default),route_typemust be given, and the frequency of every route of these types is set.- headway
A number. The headway to be set, in minutes. It is rounded to whole seconds and applies to every
route_id(call the function once per route to set different headways).- from
A string. The starting point of the time of day, in the "HH:MM:SS" format.
- to
A string. The ending point of the time of day, in the "HH:MM:SS" format. Must be later than
from.- route_type
An integer vector of
route_types (seefilter_by_route_type()). If given, only routes of these types are changed; together withroute_id, it restricts the given routes.route_types not listed inroutesare ignored. IfNULL(the default), routes of any type are changed.
Value
A GTFS object with updated frequencies, trips and stop_times
tables (and transfers, when present). If the given GTFS object has no
frequencies table, one is created.
Details
Departures are grouped by route_id, service_id and direction_id (if
present in trips) and counted within the time of day (at or after from
and before to) as in get_route_frequency(), which thus reports the new
headway (exactly, when the length of the time of day is a multiple of
headway). Departures after midnight are listed with times past
"24:00:00", so use a time of day such as "24:00:00"-"26:00:00" for them.
Times after midnight written as early morning times (e.g. "00:30:00"
instead of "24:30:00"), and end_times earlier than start_times in
frequencies, are first fixed with fix_overnight_times(), so the
returned GTFS has them fixed.
The function changes existing service, it does not create it: groups with
no departure within the time of day are not modified, and scheduled trips
that depart before from are not changed, even if they run within the time
of day. In each other group:
the trips that depart within the time of day are replaced by a single template: among the trips of the stop pattern (see
get_stop_times_patterns()) with the most departures within the time of day, the one that departs first. Its travel times apply to all the new departures. The other trips that depart within the time of day are removed (frequency-based ones instead lose theirfrequenciesentries within the time of day, see below);a
frequenciesentry is added for the template, fromfromtoto, withheadway_secsset toheadwayandexact_times = 0; thetransfersentries that refer to the template then apply to all of its departures;the existing
frequenciesentries of the group's trips are cut atfromandto, keeping their departures outside the time of day exactly as before (as converted byfrequencies_to_stop_times()withstrategy = "exact"). Trips left without any departure are removed fromtrips,stop_timesandtransfers.
Groups whose trips within the time of day have no departure time in
stop_times can't have a template and are left unchanged, with a warning.
Removed trips may leave unused entries in other tables, such as shapes
and calendar, which remove_unused_ids() removes.
stop_times requires the stop_id and stop_sequence fields. Existing
_secs columns in frequencies (e.g. created with
convert_time_to_seconds()) are updated.
Examples
data_path <- system.file("extdata/spo_gtfs.zip", package = "gtfstools")
gtfs <- read_gtfs(data_path)
get_route_frequency(
gtfs,
route_id = "CPTM L07",
from = "07:00:00",
to = "09:00:00"
)
#> Key: <route_id, direction_id, service_id>
#> route_id direction_id service_id departures mean_headway
#> <char> <int> <char> <int> <num>
#> 1: CPTM L07 0 USD 20 6
#> 2: CPTM L07 1 USD 20 6
# sets a 10 minutes headway from 7 to 9 am
new_gtfs <- set_route_frequency(
gtfs,
route_id = "CPTM L07",
headway = 10,
from = "07:00:00",
to = "09:00:00"
)
get_route_frequency(
new_gtfs,
route_id = "CPTM L07",
from = "07:00:00",
to = "09:00:00"
)
#> Key: <route_id, direction_id, service_id>
#> route_id direction_id service_id departures mean_headway
#> <char> <int> <char> <int> <num>
#> 1: CPTM L07 0 USD 12 10
#> 2: CPTM L07 1 USD 12 10
# use frequencies_to_stop_times() to get the scheduled trips
new_gtfs <- frequencies_to_stop_times(new_gtfs)
