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
Datevector (includingIDate) 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. IfNULL(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 (seefilter_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 basicroute_types). If given, only routes of these modes are described. IfNULL(the default), all modes are described.- agency_id
A character vector of
agency_ids. If given, only the services of these agencies are described. IfNULL(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. IfNULL(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), agtfstoolsdirectory insidetempdir()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 toFALSE).- 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: theagency_id,agency_name,agency_timezone,agency_urlandagency_langcolumns (those present in the feed) of the agencies that run the selected trips (all agencies, if the selected routes have noagency_id);services: a single row summarising the calendar of the selected services, with the columnsstart_dateandend_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 ofservice_ids),mean_trips_per_day(over the days with service),busiest_dateandmax_trips_per_day(the day with the most trips and its number of trips) andfeed_start_dateandfeed_end_date(fromfeed_info,NAif absent);totals: the columnsindicator,valueandunit, 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, andvkt_daily_meanover the days with counted departures (see Details). Ifby_route_type = TRUE,valueis replaced by one column per mode followed by the columnall(codes of extendedroute_types, such as"700", are non-syntactic names, so they need backticks);speed,distanceandfrequency: summary statistics (n,min,q25,median,mean,q75,maxandunit) of the trip speeds (in km/h), of the trip lengths (in km) and of the route headways (in minutes).frequencyalso has the columnsdate,fromandto, with the day and the time of day in which the headways were measured. Ifby_route_type = TRUE, these tables start with amodecolumn and have one row per mode followed by the rowall.
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.
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(), if
stop_sequence is an integer column.
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
# \donttest{
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
# }
}
#> indicator subway rail bus all
#> <char> <num> <num> <num> <num>
#> 1: n_agencies 1.000000e+00 1.000000e+00 1.000000e+00 1.000000e+00
#> 2: n_routes 6.000000e+00 7.000000e+00 6.000000e+00 1.900000e+01
#> 3: n_trips 1.200000e+01 1.400000e+01 1.000000e+01 3.600000e+01
#> 4: n_stops 8.800000e+01 1.000000e+02 4.660000e+02 6.540000e+02
#> 5: total_shape_length 1.969668e+02 5.256466e+02 1.733147e+02 8.959281e+02
#> 6: mean_shape_length 1.641390e+01 3.754619e+01 1.733147e+01 2.488689e+01
#> 7: total_trip_length 1.959420e+02 5.247475e+02 1.708881e+02 8.915777e+02
#> 8: mean_trip_length 1.632850e+01 3.748197e+01 1.708881e+01 2.476605e+01
#> 9: vkt_total 3.833453e+08 4.255697e+08 5.176208e+07 8.606771e+08
#> 10: vkt_daily_mean 8.509330e+04 9.446608e+04 1.148992e+04 1.910493e+05
#> 11: total_trip_duration 7.263333e+00 1.966667e+01 1.581667e+01 4.274667e+01
#> 12: mean_trip_duration 3.631667e+01 8.428571e+01 9.490000e+01 7.124444e+01
#> 13: mean_trip_speed 2.736401e+01 2.906481e+01 1.094215e+01 2.346380e+01
#> 14: mean_route_headway 6.283301e+00 1.096129e+01 6.508947e+01 2.443757e+01
#> unit
#> <char>
#> 1: <NA>
#> 2: <NA>
#> 3: <NA>
#> 4: <NA>
#> 5: km
#> 6: km
#> 7: km
#> 8: km
#> 9: km
#> 10: km/day
#> 11: h
#> 12: min
#> 13: km/h
#> 14: min
