Title: | Read and Write General Transit Feed Specification (GTFS) Files |
---|---|
Description: | Tools for the development of packages related to General Transit Feed Specification (GTFS) files. Establishes a standard for representing GTFS feeds using R data types. Provides fast and flexible functions to read and write GTFS feeds while sticking to this standard. Defines a basic 'gtfs' class which is meant to be extended by packages that depend on it. And offers utility functions that support checking the structure of GTFS objects. |
Authors: | Daniel Herszenhut [aut, cre] , Flavio Poletti [aut], Mark Padgham [aut], Rafael H. M. Pereira [rev] , Tom Buckley [rev], Ipea - Institute for Applied Economic Research [cph, fnd] |
Maintainer: | Daniel Herszenhut <[email protected]> |
License: | MIT + file LICENSE |
Version: | 1.2.0.9000 |
Built: | 2024-10-14 12:25:56 UTC |
Source: | https://github.com/r-transit/gtfsio |
Subsetting a GTFS object using [
preserves the object class.
## S3 method for class 'gtfs' x[value]
## S3 method for class 'gtfs' x[value]
x |
A GTFS object. |
value |
Either a numeric or a character vector. Designates the elements to be returned. |
A GTFS object.
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) names(gtfs) class(gtfs) small_gtfs <- gtfs[1:5] names(small_gtfs) class(small_gtfs) small_gtfs <- gtfs[c("shapes", "trips")] names(small_gtfs) class(small_gtfs)
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) names(gtfs) class(gtfs) small_gtfs <- gtfs[1:5] names(small_gtfs) class(small_gtfs) small_gtfs <- gtfs[c("shapes", "trips")] names(small_gtfs) class(small_gtfs)
Asserts that a GTFS object is valid. Valid objects are those in which:
Every element is named.
Every element inherits from data.frame
s.
The exception to the second rule are objects that contain an element named
"."
. In such case, this element is actually composed by a named list of
elements who inherit from data.frame
s.
assert_gtfs(x)
assert_gtfs(x)
x |
A GTFS object. |
The same GTFS object passed to x
.
Other constructors:
new_gtfs()
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) gtfs <- assert_gtfs(gtfs)
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) gtfs <- assert_gtfs(gtfs)
Checks the classes of fields, represented by columns, inside a GTFS object element.
check_field_class(x, file, fields, classes) assert_field_class(x, file, fields, classes)
check_field_class(x, file, fields, classes) assert_field_class(x, file, fields, classes)
x |
A GTFS object. |
file |
A string. The element, that represents a GTFS text file, whose fields' classes should be checked. |
fields |
A character vector. The fields to have their classes checked. |
classes |
A character vector, with the same length of |
check_field_class
returns TRUE
if the check is successful, and
FALSE
otherwise. assert_field_class
returns x
invisibly if the check is
successful, and throws an error otherwise.
Other checking functions:
check_field_exists()
,
check_file_exists()
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) check_field_class( gtfs, "calendar", fields = c("monday", "tuesday"), classes = rep("integer", 2) ) check_field_class( gtfs, "calendar", fields = c("monday", "tuesday"), classes = c("integer", "character") )
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) check_field_class( gtfs, "calendar", fields = c("monday", "tuesday"), classes = rep("integer", 2) ) check_field_class( gtfs, "calendar", fields = c("monday", "tuesday"), classes = c("integer", "character") )
Checks the existence of fields, represented by columns, inside a GTFS object element.
check_field_exists(x, file, fields) assert_field_exists(x, file, fields)
check_field_exists(x, file, fields) assert_field_exists(x, file, fields)
x |
A GTFS object. |
file |
A string. The element, that represents a GTFS text file, where fields should be searched. |
fields |
A character vector. The fields to check the existence of. |
check_field_exists
returns TRUE
if the check is successful, and
FALSE
otherwise. assert_field_exists
returns x
invisibly if the check is
successful, and throws an error otherwise.
Other checking functions:
check_field_class()
,
check_file_exists()
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) check_field_exists(gtfs, "calendar", c("monday", "tuesday")) check_field_exists(gtfs, "calendar", c("monday", "oi"))
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) check_field_exists(gtfs, "calendar", c("monday", "tuesday")) check_field_exists(gtfs, "calendar", c("monday", "oi"))
Checks the existence of elements inside a GTFS object that represent specific GTFS text files.
check_file_exists(x, files) assert_file_exists(x, files)
check_file_exists(x, files) assert_file_exists(x, files)
x |
A GTFS object. |
files |
A character vector. The files to check the existence of. |
check_file_exists
returns TRUE
if the check is successful, and
FALSE
otherwise. assert_file_exists
returns x
invisibly if the check is
successful, and throws an error otherwise.
Other checking functions:
check_field_class()
,
check_field_exists()
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) check_file_exists(gtfs, c("calendar", "agency")) check_file_exists(gtfs, c("calendar", "oi"))
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) check_file_exists(gtfs, c("calendar", "agency")) check_file_exists(gtfs, c("calendar", "oi"))
Writes GTFS objects to disk as GTFS transit feeds. The object must be
formatted according to the standards for reading and writing GTFS transit
feeds, as specified in gtfs_reference
(i.e. data types are
not checked). If present, does not write auxiliary tables held in a sub-list
named "."
.
export_gtfs( gtfs, path, files = NULL, standard_only = FALSE, compression_level = 9, as_dir = FALSE, overwrite = TRUE, quiet = TRUE )
export_gtfs( gtfs, path, files = NULL, standard_only = FALSE, compression_level = 9, as_dir = FALSE, overwrite = TRUE, quiet = TRUE )
gtfs |
A GTFS object. |
path |
A string. Where the resulting |
files |
A character vector. The name of the elements to be written to the feed. |
standard_only |
A logical. Whether only standard files and fields should
be written (defaults to |
compression_level |
A numeric, between 1 and 9. The higher the value, the best the compression, which demands more processing time. Defaults to 9 (best compression). |
as_dir |
A logical. Whether the feed should be exported as a directory,
instead of a |
overwrite |
A logical. Whether to overwrite an existing |
quiet |
A logical. Whether to hide log messages and progress bars
(defaults to |
Invisibly returns the same GTFS object passed to gtfs
.
Other io functions:
import_gtfs()
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) tmpf <- tempfile(pattern = "gtfs", fileext = ".zip") export_gtfs(gtfs, tmpf) zip::zip_list(tmpf)$filename export_gtfs(gtfs, tmpf, files = c("shapes", "trips")) zip::zip_list(tmpf)$filename
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) tmpf <- tempfile(pattern = "gtfs", fileext = ".zip") export_gtfs(gtfs, tmpf) zip::zip_list(tmpf)$filename export_gtfs(gtfs, tmpf, files = c("shapes", "trips")) zip::zip_list(tmpf)$filename
The dataset gtfs_reference now contains the standard specifications.
This function is deprecated and no longer used in import_gtfs()
or export_gtfs()
.
get_gtfs_standards()
get_gtfs_standards()
Generates a list specifying the standards to be used when reading and writing GTFS feeds with R. Each list element (also a list) represents a distinct GTFS table, and describes:
whether the table is required, optional or conditionally required;
the fields that compose the table, including which R data type is best
suited to represent it, whether the field is required, optional or
conditionally required, and which values it can assume (most relevant to GTFS
ENUM
s.
Note: the standards list is based on the specification as revised in May 9th, 2022.
A named list, in which each element represents the R equivalent of each GTFS table standard.
GTFS standards were derived from GTFS Schedule Reference. The R data types chosen to represent each GTFS data type are described below:
Color = character
Currency amount = numeric
Currency code = character
Date = integer
Email = character
ENUM = integer
ID = character
Integer = integer
Language code = character
Latitude = numeric
Longitude = numeric
Float = numeric
Phone number = character
Text = character
Time = character
Timezone = character
URL = character
## Not run: gtfs_standards <- get_gtfs_standards() ## End(Not run)
## Not run: gtfs_standards <- get_gtfs_standards() ## End(Not run)
The data from the official GTFS specification document parsed to a list. Revision date:
2024-08-16
.
gtfs_reference
gtfs_reference
A list with data for every GTFS file. Each named list element (also a list) has specifications for one GTFS file in the following structure:
File_Name
: file name including file extension (txt or geojson)
File_Presence
: Presence condition applied to the file
file
: file name without file extension
file_ext
: file extension
fields
: data.frame with parsed field specification (columns:
Field_Name
, Type
, Presence
, Description
, gtfsio_type
)
primary_key
: primary key as vector
field_types
: named vector on how GTFS types (values) should be read in gtfsio
(names). Values are the same as in fields
.
GTFS Types are converted to R types in gtfsio according to the following list:
Array = geojson_array
Color = character
Currency amount = numeric
Currency code = character
Date = integer
Email = character
Enum = character, integer
Float = numeric
ID = character
Integer = integer
Language code = character
Latitude = numeric
Longitude = numeric
Non-negative float = numeric
Non-negative integer = integer
Non-null integer = integer
Non-zero integer = integer
Object = geojson_object
Phone number = character
Positive float = numeric
Positive integer = integer
String = character
Text = character
Text or URL or Email or Phone number = character
Time = character
Timezone = character
URL = character
Unique ID = character
https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md
Imports GTFS transit feeds from either a local .zip
file or an URL.
Columns are parsed according to the standards for reading and writing GTFS
feeds specified in gtfs_reference
.
import_gtfs( path, files = NULL, fields = NULL, extra_spec = NULL, skip = NULL, quiet = TRUE, encoding = "unknown" )
import_gtfs( path, files = NULL, fields = NULL, extra_spec = NULL, skip = NULL, quiet = TRUE, encoding = "unknown" )
path |
A string. The path to a GTFS |
files |
A character vector. The text files to be read from the GTFS,
without the |
fields |
A named list. The fields to be read from each text file, in the
format |
extra_spec |
A named list. Custom specification used when reading
undocumented fields, in the format
|
skip |
A character vector. Text files that should not be read from the
GTFS, without the |
quiet |
A logical. Whether to hide log messages and progress bars
(defaults to |
encoding |
A string. Passed to |
A GTFS object: a named list of data frames, each one corresponding to a distinct text file from the given GTFS feed.
Other io functions:
export_gtfs()
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") # read all files and columns gtfs <- import_gtfs(gtfs_path) names(gtfs) names(gtfs$trips) # read all columns from selected files gtfs <- import_gtfs(gtfs_path, files = c("trips", "stops")) names(gtfs) names(gtfs$trips) # read specific columns from selected files gtfs <- import_gtfs( gtfs_path, files = c("trips", "stops"), fields = list( trips = c("route_id", "trip_id"), stops = c("stop_id", "stop_lat", "stop_lon") ) )
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") # read all files and columns gtfs <- import_gtfs(gtfs_path) names(gtfs) names(gtfs$trips) # read all columns from selected files gtfs <- import_gtfs(gtfs_path, files = c("trips", "stops")) names(gtfs) names(gtfs$trips) # read specific columns from selected files gtfs <- import_gtfs( gtfs_path, files = c("trips", "stops"), fields = list( trips = c("route_id", "trip_id"), stops = c("stop_id", "stop_lat", "stop_lon") ) )
Creates a GTFS object. Mostly useful for package authors who may want to
either create gtfs
objects in their packages or create subclasses of
the main gtfs
class. The usage of this function assumes some knowledge
on gtfs
objects, thus inputs are not extensively checked. See
assert_gtfs
for more thorough checks.
new_gtfs(x, subclass = character(), ...)
new_gtfs(x, subclass = character(), ...)
x |
A GTFS-like object (either a GTFS object or a named list). Each element must represent a distinct GTFS text file. |
subclass |
A character vector. Subclasses to be assigned to the
|
... |
Name-value pairs. Additional attributes. |
A GTFS object: a named list of data frames, each one corresponding to
a distinct GTFS text file, with gtfs
and list
classes.
Other constructors:
assert_gtfs()
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") tmpdir <- tempfile(pattern = "new_gtfs_example") zip::unzip(gtfs_path, exdir = tmpdir) agency <- data.table::fread(file.path(tmpdir, "agency.txt")) stops <- data.table::fread(file.path(tmpdir, "stops.txt")) routes <- data.table::fread(file.path(tmpdir, "routes.txt")) trips <- data.table::fread(file.path(tmpdir, "trips.txt")) stop_times <- data.table::fread(file.path(tmpdir, "stop_times.txt")) calendar <- data.table::fread(file.path(tmpdir, "calendar.txt")) txt_files <- list( agency = agency, stops = stops, routes = routes, trips = trips, stop_times = stop_times, calendar = calendar ) gtfs <- new_gtfs(txt_files) class(gtfs) names(gtfs)
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") tmpdir <- tempfile(pattern = "new_gtfs_example") zip::unzip(gtfs_path, exdir = tmpdir) agency <- data.table::fread(file.path(tmpdir, "agency.txt")) stops <- data.table::fread(file.path(tmpdir, "stops.txt")) routes <- data.table::fread(file.path(tmpdir, "routes.txt")) trips <- data.table::fread(file.path(tmpdir, "trips.txt")) stop_times <- data.table::fread(file.path(tmpdir, "stop_times.txt")) calendar <- data.table::fread(file.path(tmpdir, "calendar.txt")) txt_files <- list( agency = agency, stops = stops, routes = routes, trips = trips, stop_times = stop_times, calendar = calendar ) gtfs <- new_gtfs(txt_files) class(gtfs) names(gtfs)
Prints a GTFS object suppressing the class
attribute.
## S3 method for class 'gtfs' print(x, ...)
## S3 method for class 'gtfs' print(x, ...)
x |
A GTFS object. |
... |
Optional arguments ultimately passed to |
The GTFS object that was printed, invisibly.
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) # subset 'gtfs' for a smaller output gtfs <- gtfs[c("routes", "trips")] print(gtfs)
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) # subset 'gtfs' for a smaller output gtfs <- gtfs[c("routes", "trips")] print(gtfs)
Print summary of a GTFS object
## S3 method for class 'gtfs' summary(object, ...)
## S3 method for class 'gtfs' summary(object, ...)
object |
A GTFS object. |
... |
Ignored. |
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) summary(gtfs)
gtfs_path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio") gtfs <- import_gtfs(gtfs_path) summary(gtfs)