get_summary: Get a summary of a GTFS feed

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

Get a summary of a GTFS feed

Description

Runs a set of diagnostics on a GTFS feed (optionally restricted to some dates, routes, modes, agencies and a time of day), writes them to a report with tables and figures, renders the report to HTML and opens it in the browser (in interactive sessions). The diagnostics are also returned as a list of data.tables. This function does not validate or look for quality issues in the GTFS feed. To do that, use validate_gtfs().

Usage

get_summary(
  gtfs,
  date = NULL,
  route_id = NULL,
  route_type = NULL,
  agency_id = NULL,
  from = NULL,
  to = NULL,
  output_path = NULL,
  html_preview = TRUE,
  by_route_type = FALSE,
  unit = "km/h"
)

Arguments

gtfs	A GTFS object, as created by read_gtfs(), or the path to a GTFS file.
date	A Date vector (including IDate) or a character vector of dates in the "YYYYMMDD" or "YYYY-MM-DD" formats. If given, only the services that run on these dates are described. If NULL (the default), the whole period covered by the feed is described.
route_id	A character vector. If given, only these routes are described. If NULL (the default), all routes are described.
route_type	An integer vector of route_types (see filter_by_route_type()) or, unlike in other functions, a character vector of mode names ("tram", "subway", "rail", "bus", "ferry", "cable_tram", "aerial_lift", "funicular", "trolleybus" and "monorail", which correspond to the basic route_types). If given, only routes of these modes are described. If NULL (the default), all modes are described.
agency_id	A character vector of agency_ids. If given, only the services of these agencies are described. If NULL (the default), all agencies are described.
from, to	Strings in the "HH:MM:SS" format. If given (both must be), only the trips that run within this time of day are described. If NULL (the default), the whole day is described.
output_path	A string. The directory in which the report is saved (created if needed). If NULL (the default), a gtfstools directory inside tempdir() is used. Existing reports in this directory are overwritten.
html_preview	A logical. Whether to open the HTML report in the browser, in interactive sessions (defaults to TRUE).
by_route_type	A logical. Whether to break down the totals, speeds, distances and frequencies by transport mode (route_type), in addition to the whole selection (defaults to FALSE).
unit	A string. Either "km/h" (the default), to report distances in km and speeds in km/h, or "mph", to report them in miles and miles per hour.

Value

A named list of data.tables (invisibly, if the report was opened in the browser):

• files: the tables in the feed (file) and their number of rows (n_rows), before any filtering;

• agency: the agency_id, agency_name, agency_timezone, agency_url and agency_lang columns (those present in the feed) of the agencies that run the selected trips (all agencies, if the selected routes have no agency_id);

• services: a single row summarising the calendar of the selected services, with the columns start_date and end_date (the first and last days with service), n_days (the number of days between them, both included), n_service_days (the number of days with service), n_services (the number of service_ids), mean_trips_per_day (over the days with service), busiest_date and max_trips_per_day (the day with the most trips and its number of trips) and feed_start_date and feed_end_date (from feed_info, NA if absent);

• totals: the columns indicator, value and unit, with the number of agencies, routes, trips and stops, the total and mean length of the shapes and of the trips (in km), the vehicle-kilometres travelled (vkt_total, in km) and their mean per day (vkt_daily_mean, in km/day), the total duration of the trips (in hours), the mean duration of the trips (in minutes), the mean trip speed (in km/h) and the mean route headway (in minutes). The means of lengths, durations and speeds are taken over the shapes and trips whose value is known, and vkt_daily_mean over the days with counted departures (see Details). If by_route_type = TRUE, value is replaced by one column per mode followed by the column all (codes of extended route_types, such as "700", are non-syntactic names, so they need backticks);

• speed, distance and frequency: summary statistics (n, min, q25, median, mean, q75, max and unit) of the trip speeds (in km/h), of the trip lengths (in km) and of the route headways (in minutes). frequency also has the columns date, from and to, with the day and the time of day in which the headways were measured. If by_route_type = TRUE, these tables start with a mode column and have one row per mode followed by the row all.

With unit = "mph", distances are in miles (mi and mi/day) and speeds in miles per hour (mph), and the rows vkt_total and vkt_daily_mean of totals are named vmt_total and vmt_daily_mean (vehicle-miles travelled).

The report is saved as gtfs_summary.md and gtfs_summary.html (together with its figures) in output_path.

Details

The report requires the {ggplot2}, {knitr} and {rmarkdown} packages and Pandoc.

The time-of-day filter keeps whole trips (as filter_by_time_of_day() with full_trips = TRUE), so trip speeds and lengths refer to whole trips.

Trip lengths, durations and speeds are calculated with get_trip_length(), get_trip_duration() and get_trip_speed(), counting each trip once, however many days it runs on or departures frequencies lists for it. Trips with a zero or negative duration count in the durations but have no speed. Shape lengths count each shape used by the selected trips once, and the number of stops counts the stops visited by the selected trips.

The VKT are calculated as in get_vkt() (or get_vmt(), with unit = "mph"): the length of each selected trip counts once per departure on every counted day on which its service runs. The counted days are the given dates or, if date is NULL, every day on which the selected services run; vkt_daily_mean is the mean over the counted days on which at least one counted departure runs. With from and to, only the departures at or after from and at or before to are counted, as listed before the feed is filtered by time of day, so selected trips that depart before from add nothing. vkt_total and vkt_daily_mean are NA if no selected trip departs on the counted days (within the time of day, if given). An error is raised if frequencies has invalid entries for selected trips that run on the counted days.

services and the calendar chart describe the whole calendar of the selected services: with date, the services running on these dates are kept whole (as in filter_by_date()), so they may cover other days too. The trips per day are counted as in get_calendar_overlap().

Route headways are calculated with get_route_frequency(), by route (and direction_id, if present in trips), on a single day: the one with the most trips among the given dates or in the whole feed (the earliest, on ties). They are measured within the given time of day (excluding to, as in get_route_frequency(), unlike the other indicators) or, without from and to, from the first to the last departure of that day, rounded out to whole hours. Trips of the previous service day running after midnight are not counted. With from and to, headways and trips per day are counted on the time-filtered feed, whose frequencies entries crossing from start at from (unless exact_times is 1), so they may differ from get_route_frequency() and get_calendar_overlap() on the full feed.

With by_route_type = TRUE, modes are named as in the route_type argument, extended route_types by their code and trips of unknown route_type as "unknown", ordered by route_type with "unknown" last. Each mode is described as if selected alone (except that all headways share the same day and time of day), so stops, shapes and agencies shared by modes count in each. Only the numbers of routes and trips, the total trip lengths and durations and vkt_total (or vmt_total) add up to all. Modes whose routes have blank agency_ids count all the agencies of the selection. Trips listed in stop_times but not in trips count only in all (and not in the VKT, as they have no service).

Examples

if (
  requireNamespace("ggplot2", quietly = TRUE) &&
    requireNamespace("knitr", quietly = TRUE) &&
    requireNamespace("rmarkdown", quietly = TRUE) &&
    rmarkdown::pandoc_available()
) {
  data_path <- system.file("extdata/spo_gtfs.zip", package = "gtfstools")

  feed_summary <- get_summary(
    data_path,
    output_path = tempdir(),
    html_preview = FALSE
  )
  feed_summary$totals

  
  feed_summary <- get_summary(
    data_path,
    route_type = "bus",
    from = "07:00:00",
    to = "09:00:00",
    output_path = tempdir(),
    html_preview = FALSE
  )
  feed_summary$frequency

  feed_summary <- get_summary(
    data_path,
    output_path = tempdir(),
    html_preview = FALSE,
    by_route_type = TRUE
  )
  feed_summary$totals
  
}

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