| Title: | Converting Transport Data from GTFS Format to GPS-Like Records |
|---|---|
| Description: | Convert general transit feed specification (GTFS) data to global positioning system (GPS) records in 'data.table' format. It also has functions to post-process these GPS records, for example converting them to simple feature format. |
| Authors: | Rafael H. M. Pereira [aut] (ORCID: <https://orcid.org/0000-0003-2125-7465>), Pedro R. Andrade [aut, cre] (ORCID: <https://orcid.org/0000-0001-8675-4046>), Joao Bazzo [aut] (ORCID: <https://orcid.org/0000-0003-4536-5006>), Daniel Herszenhut [ctb] (ORCID: <https://orcid.org/0000-0001-8066-1105>), Marcin Stepniak [ctb], Marcus Saraiva [ctb] (ORCID: <https://orcid.org/0000-0001-6218-2338>), Ipea - Institute for Applied Economic Research [cph, fnd] |
| Maintainer: | Pedro R. Andrade <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 2.1-4.9000 |
| Built: | 2026-11-09 02:37:06 UTC |
| Source: | https://github.com/ipea/gtfs2gps |
This function is deprecated and will be removed in a future
version; it warns once per session. Its job has moved to gtfstools: use
gtfstools::set_dwell_time() or gtfstools::set_min_dwell_time()
to edit and fix GTFS feeds before converting them. Unlike this function,
set_min_dwell_time() keeps arrivals, delays the departure and the later
times of the trip, and leaves each trip's first and last timed stops unchanged
(set_dwell_time() sets them too); neither fills blank times.
Some GTFS.zip data have issues related to arrival and departure time on stops. This function makes sure the GTFS has dis/embarking times at each stop. For each stop time row, this function applies the following steps:
If there is arrival_time but no departure_time, it creates a departure_time
column by summing the arrival plus a pre-defined min_lag.
If there is departure_time but no arrival_time, it creates an arrival_time
column by subtracting a pre-defined min_lag from the departure.
If there is an arrival_time and a departure_time but their difference
is smaller than min_lag, it reduces the arrival_time and increases
departure_time so that the difference will be exactly min_lag. Odd
differences give the extra second to the departure.
Arrivals before 00:00:00 are set to 00:00:00 and the departure moved to
keep min_lag. Times are not kept increasing across consecutive stops.
The input GTFS data is not modified.
adjust_arrival_departure(gtfs_data, min_lag = 20)adjust_arrival_departure(gtfs_data, min_lag = 20)
gtfs_data |
A GTFS data created with |
min_lag |
Numeric. Minimum waiting time when a vehicle arrives at a stop. It can be a numeric or a units value that can be converted to seconds, rounded to whole seconds. Default is 20s. |
A GTFS with adjusted arrival_time and departure_time on
data.table stop_times. Stops with neither time come back with empty
strings (""), which GTFS allows for stops that are not timepoints.
poa <- read_gtfs(system.file("extdata/poa.zip", package="gtfs2gps")) poa <- adjust_arrival_departure(poa)poa <- read_gtfs(system.file("extdata/poa.zip", package="gtfs2gps")) poa <- adjust_arrival_departure(poa)
gtfs2gps (deprecated)This function is deprecated and will be removed in a future
version; it warns once per session. It edits the GPS-like output of
gtfs2gps(). We strongly recommend using our sister package gtfstools
to fix and edit GTFS data before processing them with gtfs2gps, for example
with gtfstools::set_max_speed() and gtfstools::set_min_speed().
Unlike this function,
they work on the GTFS before conversion, and do not replace missing speeds in
the GPS output.
Some GTFS.zip data sets might have quality issues, for example
by assuming that a trip speed is unreasonably high (e.g. an urban bus running
over 100 km/h), or in other cases the timestamp information might be
missing for some route segments. This can lead a gps-like table to have NA
or unrealistic speed and timestamp values.
This function allows the
user to adjust the speed of trips and updates timestamp values
accordingly. The user can adjust the problematic speeds by either setting a
custom constant value, or by considering the distance-weighted mean of the valid
speeds (Default). The columns timestamp and cumtime are updated accordingly.
Each trip keeps the timestamp of its first timed point, and dwell times at
stops are kept, so stop timestamps don't change when every speed is within
range; segments whose speeds are replaced are re-timed. Trips without any
timestamp keep NA timestamps. Timestamps wrap at 24:00:00.
gps_data must be ordered as gtfs2gps returns it.
adjust_speed( gps_data, min_speed = 2, max_speed = 80, new_speed = NULL, clone = TRUE )adjust_speed( gps_data, min_speed = 2, max_speed = 80, new_speed = NULL, clone = TRUE )
gps_data |
A GPS-like data.table created with |
min_speed |
Minimum speed to be considered as valid. It can be a numeric (in km/h) or a units value able to be converted to km/h. Values below minimum speed will be adjusted. Defaults to 2 km/h; must be a single number, not negative. Outside stops, speeds that round to 0 km/h at 3 decimals are also adjusted, as they would take too long to cover any distance. |
max_speed |
Maximum speed to be considered as valid. It can be a numeric (in km/h) or a units value able to be converted to km/h. Values above maximum speed will be adjusted. Defaults to 80 km/h. |
new_speed |
Speed to replace missing values as well as values
outside min_speed and max_speed range. It can
be a numeric (in km/h) or a units value able to be converted to km/h.
By default, |
clone |
Use a copy of the gps_data? Defaults to TRUE. With |
A GPS-like data with adjusted speed values and the same
columns as gps_data. The columns timestamp and cumtime
are also updated accordingly. An error is raised if no speed is within range
and new_speed is not given.
poa <- read_gtfs(system.file("extdata/poa.zip", package="gtfs2gps")) |> gtfstools::filter_by_shape_id("T2-1") |> gtfstools::filter_by_weekday(c("monday", "wednesday")) |> filter_single_trip() poa_gps <- gtfs2gps(poa) poa_gps_new <- adjust_speed(poa_gps)poa <- read_gtfs(system.file("extdata/poa.zip", package="gtfs2gps")) |> gtfstools::filter_by_shape_id("T2-1") |> gtfstools::filter_by_weekday(c("monday", "wednesday")) |> filter_single_trip() poa_gps <- gtfs2gps(poa) poa_gps_new <- adjust_speed(poa_gps)
Add a column named height to GPS data using a tif data as reference.
append_height(gps, heightfile)append_height(gps, heightfile)
gps |
A GPS data created from gtfs2gps(). |
heightfile |
The pathname of a tif file with height data. The raster must be in geographic coordinates (WGS84 longitude and latitude), as the GPS points are used as they are. |
The GPS data with a new column named height, a plain number in the units of the raster (metres for SRTM data).
fortaleza <- system.file("extdata/fortaleza.zip", package = "gtfs2gps") srtmfile <- system.file("extdata/fortaleza-srtm.tif", package = "gtfs2gps") gtfs <- read_gtfs(fortaleza) |> gtfstools::filter_by_shape_id("shape836-I") |> filter_single_trip() fortaleza_gps <- gtfs2gps(gtfs, spatial_resolution = 500, quiet = TRUE) |> append_height(srtmfile)fortaleza <- system.file("extdata/fortaleza.zip", package = "gtfs2gps") srtmfile <- system.file("extdata/fortaleza-srtm.tif", package = "gtfs2gps") gtfs <- read_gtfs(fortaleza) |> gtfstools::filter_by_shape_id("shape836-I") |> filter_single_trip() fortaleza_gps <- gtfs2gps(gtfs, spatial_resolution = 500, quiet = TRUE) |> append_height(srtmfile)
Filter a GTFS data by keeping only the first trip of each
shape_id, using gtfstools::filter_by_trip_id(). Trips without a
shape_id are dropped. The other tables (stop_times, frequencies, shapes,
routes, stops, calendar, etc.) keep only the rows used by the remaining
trips. The input data is not modified.
filter_single_trip(gtfs_data)filter_single_trip(gtfs_data)
gtfs_data |
A list of data.tables read using gtfs2gps::read_gtfs(). |
A filtered GTFS data.
poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) subset <- filter_single_trip(poa)poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) subset <- filter_single_trip(poa)
This function is deprecated and will be removed in a future
version. gtfs2gps() does not need it.
Filter a GTFS data read using gtfs2gps::read_gtfs(). It removes stop_times whose arrival_time or departure_time is missing or is not a well-formed "H:MM:SS" time string (hours may exceed 24). It also filters stops and routes accordingly. The input data is not modified.
filter_valid_stop_times(gtfs_data)filter_valid_stop_times(gtfs_data)
gtfs_data |
A list of data.tables read using gtfs2gps::read_gtfs(). |
A filtered GTFS data.
poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) subset <- suppressWarnings(filter_valid_stop_times(poa))poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) subset <- suppressWarnings(filter_valid_stop_times(poa))
Every interval of GPS data points between stops for each trip_id is converted into a linestring segment. The output assumes constant average speed between consecutive stops.
gps_as_sflinestring(gps)gps_as_sflinestring(gps)
gps |
A GPS data.table created with |
A simple feature (sf) object in CRS 4326 with one LineString per
interval between consecutive stops of each trip. Besides columns of gps
taken from the segment's first point (such as shape_id,
trip_id and trip_number), it has from_stop_id and
to_stop_id ("-" before the first and after the last stop),
from_timestamp and to_timestamp (ITime), and the
speed (km/h), dist and cumdist (m) and cumtime
(s) of each segment.
library(gtfs2gps) poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) poa_subset <- gtfstools::filter_by_shape_id(poa, c("T2-1", "A141-1")) |> filter_single_trip() poa_gps <- gtfs2gps(poa_subset) poa_gps_sf <- gps_as_sflinestring(poa_gps)library(gtfs2gps) poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) poa_subset <- gtfstools::filter_by_shape_id(poa, c("T2-1", "A141-1")) |> filter_single_trip() poa_gps <- gtfs2gps(poa_subset) poa_gps_sf <- gps_as_sflinestring(poa_gps)
Convert a GPS data stored in a data.table into Simple Feature points.
gps_as_sfpoints(gps, crs = 4326)gps_as_sfpoints(gps, crs = 4326)
gps |
A data.table with timestamp data. |
crs |
The coordinate reference system of the output, as accepted by
|
A simple feature (sf) object with point data.
library(gtfs2gps) fortaleza <- read_gtfs(system.file("extdata/fortaleza.zip", package = "gtfs2gps")) srtmfile <- system.file("extdata/fortaleza-srtm.tif", package="gtfs2gps") subset <- fortaleza |> gtfstools::filter_by_weekday(c("monday", "wednesday")) |> filter_single_trip() |> gtfstools::filter_by_shape_id("shape806-I") for_gps <- gtfs2gps(subset) for_gps_sf_points <- gps_as_sfpoints(for_gps)library(gtfs2gps) fortaleza <- read_gtfs(system.file("extdata/fortaleza.zip", package = "gtfs2gps")) srtmfile <- system.file("extdata/fortaleza-srtm.tif", package="gtfs2gps") subset <- fortaleza |> gtfstools::filter_by_weekday(c("monday", "wednesday")) |> filter_single_trip() |> gtfstools::filter_by_shape_id("shape806-I") for_gps <- gtfs2gps(subset) for_gps_sf_points <- gps_as_sfpoints(for_gps)
This function is deprecated and will be removed in a future
version. Use gtfstools::get_shapes_geometry() and, for the length of
each shape, gtfstools::get_shape_length() instead.
Convert the shapes of a GTFS data loaded using
read_gtfs into a LINESTRING simple feature (sf) object, using
get_shapes_geometry, and add the length of each
shape in kilometres, using get_shape_length. The
input data is not modified.
gtfs_shapes_as_sf(gtfs, crs = 4326)gtfs_shapes_as_sf(gtfs, crs = 4326)
gtfs |
A GTFS data. |
crs |
The coordinate reference system of the output: an EPSG code, a
string accepted by |
A simple feature (sf) object with columns shape_id,
geometry and length (km). The length is computed from the
WGS84 points of each shape, whatever crs is.
sp <- read_gtfs(system.file("extdata/saopaulo.zip", package = "gtfs2gps")) sp_sf <- suppressWarnings(gtfs_shapes_as_sf(sp))sp <- read_gtfs(system.file("extdata/saopaulo.zip", package = "gtfs2gps")) sp_sf <- suppressWarnings(gtfs_shapes_as_sf(sp))
This function is deprecated and will be removed in a future
version. Use gtfstools::get_stops_geometry() instead.
Convert the stops of a GTFS data loaded using
read_gtfs into a POINT simple feature (sf) object, using
get_stops_geometry. The input data is not modified.
gtfs_stops_as_sf(gtfs, crs = 4326)gtfs_stops_as_sf(gtfs, crs = 4326)
gtfs |
A GTFS data. |
crs |
The coordinate reference system of the output: an EPSG code, a
string accepted by |
A simple feature (sf) object.
poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) poa_stops <- suppressWarnings(gtfs_stops_as_sf(poa))poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) poa_stops <- suppressWarnings(gtfs_stops_as_sf(poa))
Convert GTFS data to GPS format by sampling points using a given spatial resolution. This function creates additional points in order to guarantee that two points in a same trip will have at most a given distance, indicated as a spatial resolution.
Stops without times are placed along the shape at constant speed between
the timed stops. fix_gtfs can clean a feed before
converting it (e.g. duplicated rows and unused ids), but the stop times it
interpolates may give spiky or infinite speeds here.
gtfs2gps( gtfs_data, spatial_resolution = 100, parallel = NULL, ncores = 2, strategy = NULL, filepath = NULL, compress = FALSE, snap_method = NULL, continue = FALSE, quiet = FALSE )gtfs2gps( gtfs_data, spatial_resolution = 100, parallel = NULL, ncores = 2, strategy = NULL, filepath = NULL, compress = FALSE, snap_method = NULL, continue = FALSE, quiet = FALSE )
gtfs_data |
A path to a GTFS file to be converted to GPS, or a GTFS data represented as a list of data.tables. |
spatial_resolution |
The spatial resolution in meters: a number of at
least 1, or a |
parallel |
This argument is deprecated and ignored. Please use argument ncores instead. |
ncores |
Number of threads used. Defaults to 2. If |
strategy |
This argument is deprecated and ignored. Please use argument ncores instead. |
filepath |
Output file path. As default, the output is returned when gtfs2gps
finishes. When this argument is set, each shape is saved into a txt file
within filepath, named after its |
compress |
Argument that can be used only with filepath. When |
snap_method |
This argument is deprecated and ignored. Stops are now
located along the shapes with |
continue |
Argument that can be used only with filepath. When TRUE, it
skips processing the shape identifiers that were already saved into
files. It is useful to continue processing a GTFS file that was stopped
for some reason. Default value is |
quiet |
Hide messages while processing the data. Defaults to |
Before converting, the feed is cleaned with
gtfstools::remove_duplicates() and gtfstools::remove_unused_ids(), and trips
with an NA trip_id are dropped. Errors and warnings raised by the package
have classes starting with gtfs2gps_ (e.g. gtfs2gps_nothing_converted_error),
and deprecation warnings with deprecated_, so they can be caught.
After creating geometry points for a given shape id, the gtfs2gps()
function snaps the stops to the route geometry. The stops of each trip are
located along the shape with gtfstools::interpolate_shape_dist_traveled(),
which projects each stop onto the shape keeping the stops in their
stop_sequence order, so that loops and shapes that pass by the same place
more than once are handled. Each stop is then snapped to the nearest point of
the shape in high resolution, moved forward when needed so that each stop has
a point of its own. Distances are great-circle distances on the sphere used
by the s2 and sf packages, with a radius of 6,371,010 m.
Each trip runs from its first to its last stop with a departure time: shape
points (and stops without times) before the first one and after the last one
have no time to be interpolated from, and are not returned. The speed,
cumdist, and cumtime are based on the difference of distance and time
between the current and previous row of the same trip. It means that the first
data point of each trip, at its first stop, represents a stationary vehicle,
with dist, cumdist and cumtime equal to zero: cumdist is the distance
travelled from the first stop. Unrealistic speeds are best fixed in the GTFS
before converting it, with gtfstools::set_max_speed() and
gtfstools::set_min_speed(). Two stops at the same place and time give an
NA speed.
Each stop is presented as two data points for each trip in the output. The
timestamp value in the first data point represents the time when the
vehicle arrived at that stop (corresponding the arrival_time column in the
stop_times.txt file), while the timestamp in the second data point
represents the time when the vehicle departed from that stop (corresponding
the departure_time column in the stop_times.txt file). The second point
considers that the vehicle is stationary at the stop, immediately before
departing.
Some GTFS feeds do not report embark/disembark times (so arrival_time and
departure_time are identical at the same stop). In this case,
gtfstools::set_dwell_time() or gtfstools::set_min_dwell_time() can set the
time vehicles spend at stops to embark/disembark passengers.
To avoid division by zero, the minimum speed of vehicles in the output is 1e-12 km/h, so that vehicles are never completely stopped.
A data.table, where each row represents a GPS point. The following
columns are returned (units of measurement in parenthesis): dist and cumdist
(meters), cumtime (seconds), shape_pt_lon and shape_pt_lat (degrees), speed
(km/h), timestamp (data.table::ITime, wrapped at midnight). Speed, dist,
cumdist and cumtime are rounded to 3 decimal places (also when written to
filepath), except speeds closer to zero than that, which keep their value (such
as the 1e-12 km/h of stops). With filepath, each shape is written to a file
and NULL is returned.
library(gtfs2gps) gtfs <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) |> gtfstools::filter_by_shape_id("T2-1") |> filter_single_trip() poa_gps <- gtfs2gps(gtfs, quiet = TRUE)library(gtfs2gps) gtfs <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) |> gtfstools::filter_by_shape_id("T2-1") |> filter_single_trip() poa_gps <- gtfs2gps(gtfs, quiet = TRUE)
Read files of a zipped GTFS feed and load them to memory as a list of data.tables.
It will load the following files: "shapes.txt", "stop_times.txt", "stops.txt", "trips.txt",
"agency.txt", "calendar.txt", "routes.txt", and "frequencies.txt", with
this last four being optional. If one of the mandatory files is missing or
empty, this function raises an error of class gtfs2gps_empty_file_error.
An empty "frequencies.txt" is dropped.
read_gtfs(gtfszip, quiet = FALSE)read_gtfs(gtfszip, quiet = FALSE)
gtfszip |
A zipped GTFS data. |
quiet |
A logical. Whether to hide log messages and progress bars.
Defaults to |
A list of data.tables, where each index represents the respective GTFS file name.
poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps"))poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps"))
This function is deprecated and will be removed in a future
version. Use gtfstools::remove_duplicates() and
gtfstools::remove_unused_ids() instead. Unlike this function, they
keep trips whose shape_id or route_id is not in the feed;
gtfs2gps() skips trips without a shape and returns an NA
route_type for trips without a route.
Remove all objects from GTFS data that are not used in all relations that they are required to be. That is, agency-routes relation (agency_id), routes-trips relation (route_id), trips-shapes relation (shape_id), trips-frequencies relation (trip_id), trips-stop_times relation (trip_id), stop_times-stops relation (stop_id), and trips-calendar relation (service_id), recursively, until GTFS data does not reduce its size anymore. For example, if one agency_id belongs to routes but not to agency will be removed. This might cause one cascade removal of objects in other relations that originally did not have any inconsistency.
remove_invalid(gtfs_data, only_essential = TRUE, prompt_invalid = FALSE)remove_invalid(gtfs_data, only_essential = TRUE, prompt_invalid = FALSE)
gtfs_data |
A list of data.tables read using gtfs2gps::read_gtfs(). |
only_essential |
Remove only the essential files? The essential files are all but agency, calendar, and routes. Default is TRUE, which means that agency-routes, routes-trips, and trips-calendar relations will not be processed as restrictions to remove objects. |
prompt_invalid |
Show the invalid objects. Default is FALSE. |
A subset of the input GTFS data.
poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) object.size(poa) subset <- suppressWarnings(remove_invalid(poa)) object.size(subset)poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) object.size(poa) subset <- suppressWarnings(remove_invalid(poa)) object.size(subset)
Write GTFS stored in memory as a list of data.tables into a
zipped GTFS feed, using write_gtfs. By default an
existing zip file is overwritten; set overwrite = FALSE to raise an
error instead.
write_gtfs( gtfs, zipfile, overwrite = TRUE, quiet = FALSE, compression_level = 6 )write_gtfs( gtfs, zipfile, overwrite = TRUE, quiet = FALSE, compression_level = 6 )
gtfs |
A GTFS data set stored in memory as a list of data.tables/data.frames. |
zipfile |
The pathname of a .zip file to be saved with the GTFS data. |
overwrite |
A logical. Whether to overwrite an existing |
quiet |
A logical. Whether to hide log messages and progress bars.
Defaults to |
compression_level |
A whole number from 1 (fastest) to 9 (smallest file). The compression level of the zip file. Defaults to 6. |
The GTFS data, invisibly.
# read a gtfs.zip to memory poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) |> gtfstools::filter_by_shape_id("T2-1") |> filter_single_trip() # write GTFS data into a zip file write_gtfs(poa, paste0(tempdir(), "/mypoa.zip"))# read a gtfs.zip to memory poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps")) |> gtfstools::filter_by_shape_id("T2-1") |> filter_single_trip() # write GTFS data into a zip file write_gtfs(poa, paste0(tempdir(), "/mypoa.zip"))