filter_by_time_of_day: Filter GTFS object by time of day

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

Filter GTFS object by time of day

Description

Filters a GTFS object by time of day, keeping (or dropping) the stop_times and frequencies entries within it, and keeping the entries of the other tables related to the trips that remain.

Usage

filter_by_time_of_day(
  gtfs,
  from,
  to,
  keep = TRUE,
  full_trips = FALSE,
  update_frequencies = TRUE
)

Arguments

gtfs	A GTFS object, as created by read_gtfs().
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.
keep	A logical. Whether the entries related to the specified time of day should be kept or dropped (defaults to TRUE, which keeps the entries).
full_trips	A logical. Whether trips should be treated as immutable blocks or each of its stops should be considered separately when filtering the stop_times table (defaults to FALSE, which considers each stop individually). Please check the details section for more information on how this parameter changes the function behaviour.
update_frequencies	A logical. Whether the frequencies table should have its start_time and end_time fields updated to fit inside/outside the specified time of day (defaults to TRUE, which updates the fields).

Value

The GTFS object passed to the gtfs parameter, after the filtering process.

Details

The time of day includes both from and to.

Trips listed in frequencies are filtered through their frequencies entries; their stop_times entries are templates and are kept whatever their times. With keep = TRUE, the entries that overlap the time of day are kept; with keep = FALSE, those entirely within it are dropped. With update_frequencies = TRUE and keep = TRUE, an entry that starts before from starts at from (or, if exact_times is 1, at its first departure at or after from), and an entry that ends after to ends one second after to, so that a departure exactly at to is kept. With update_frequencies = TRUE and keep = FALSE, an entry that crosses from ends at from, an entry that crosses to starts one second after to (or, if exact_times is 1, at its first departure after to), and an entry that spans the whole time of day is split in two. Entries left without any departure are removed, and trips left without any entry are dropped from the feed.

The other trips are filtered through their stop_times entries, which are within the time of day when the visit, from arrival_time to departure_time, overlaps it (a blank time is ignored when the other is known). With full_trips = FALSE, each entry is kept or dropped on its own, and entries with both times blank (or, with keep = FALSE, either) are dropped. With full_trips = TRUE, a trip with any entry within the time of day is kept (keep = TRUE) or dropped (keep = FALSE) as a whole, including its blank entries. The other tables are then filtered to the trips left in stop_times, as in filter_by_trip_id(), with a warning if stop_times lists trips missing from trips.

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.

See Also

Other filtering functions: filter_by_agency_id(), filter_by_date(), filter_by_period(), filter_by_route_id(), filter_by_route_type(), filter_by_service_id(), filter_by_shape_id(), filter_by_spatial_extent(), filter_by_stop_id(), filter_by_trip_id(), filter_by_weekday()

Examples

data_path <- system.file("extdata/spo_gtfs.zip", package = "gtfstools")
gtfs <- read_gtfs(data_path)

# taking a look at the original frequencies and stop_times
head(gtfs$frequencies)
head(gtfs$stop_times)

smaller_gtfs <- filter_by_time_of_day(gtfs, "05:00:00", "06:00:00")

# filter_by_time_of_day filters the frequencies table but doesn't filter the
# stop_times table because they're just templates
head(smaller_gtfs$frequencies)
head(smaller_gtfs$stop_times)

# frequencies entries are adjusted by default. use update_frequencies =
# FALSE to keep their original times
smaller_gtfs <- filter_by_time_of_day(
  gtfs,
  "05:30:00",
  "06:00:00",
  update_frequencies = FALSE
)
head(smaller_gtfs$frequencies)

# when keep = FALSE, the behaviour of the function in general, and of
# update_frequencies in particular, is a bit different
smaller_gtfs <- filter_by_time_of_day(
  gtfs,
  "05:30:00",
  "06:00:00",
  keep = FALSE,
  update_frequencies = TRUE
)
head(smaller_gtfs$frequencies)

# let's remove the frequencies table to check the behaviour of full_trips
gtfs$frequencies <- NULL
smaller_gtfs <- filter_by_time_of_day(
  gtfs,
  "05:30:00",
  "06:00:00"
)
head(smaller_gtfs$stop_times)

smaller_gtfs <- filter_by_time_of_day(
  gtfs,
  "05:30:00",
  "06:00:00",
  full_trips = TRUE
)
head(smaller_gtfs$stop_times)

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