Package 'gtfs2gps'

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

Help Index


Adjust the arrival and departure times of a GTFS data (deprecated)

Description

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:

  1. 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.

  2. 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.

  3. 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.

Usage

adjust_arrival_departure(gtfs_data, min_lag = 20)

Arguments

gtfs_data

A GTFS data created with read_gtfs.

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.

Value

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.

Examples

poa <- read_gtfs(system.file("extdata/poa.zip", package="gtfs2gps"))

poa <- adjust_arrival_departure(poa)

Adjust the speeds of a gps-like table created with gtfs2gps (deprecated)

Description

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.

Usage

adjust_speed(
  gps_data,
  min_speed = 2,
  max_speed = 80,
  new_speed = NULL,
  clone = TRUE
)

Arguments

gps_data

A GPS-like data.table created with gtfs2gps.

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, new_speed = NULL and the function uses the distance-weighted mean of the valid speeds of points that are not at stops. It is rounded to 3 decimals in km/h, as the output speeds are.

clone

Use a copy of the gps_data? Defaults to TRUE. With FALSE, gps_data is updated in place.

Value

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.

Examples

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 with height to GPS data

Description

Add a column named height to GPS data using a tif data as reference.

Usage

append_height(gps, heightfile)

Arguments

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.

Value

The GPS data with a new column named height, a plain number in the units of the raster (metres for SRTM data).

Examples

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 GTFS trips in order to have one trip per shape_id

Description

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.

Usage

filter_single_trip(gtfs_data)

Arguments

gtfs_data

A list of data.tables read using gtfs2gps::read_gtfs().

Value

A filtered GTFS data.

Examples

poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps"))

subset <- filter_single_trip(poa)

Filter GTFS data using valid stop times (deprecated)

Description

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.

Usage

filter_valid_stop_times(gtfs_data)

Arguments

gtfs_data

A list of data.tables read using gtfs2gps::read_gtfs().

Value

A filtered GTFS data.

Examples

poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps"))

subset <- suppressWarnings(filter_valid_stop_times(poa))

Converts a GPS-like data.table to a LineString Simple Feature (sf) object

Description

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.

Usage

gps_as_sflinestring(gps)

Arguments

gps

A GPS data.table created with gtfs2gps, or the path of a .txt file written by gtfs2gps(filepath = , compress = FALSE).

Value

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.

Examples

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 GPS-like data.table to a Simple Feature points object

Description

Convert a GPS data stored in a data.table into Simple Feature points.

Usage

gps_as_sfpoints(gps, crs = 4326)

Arguments

gps

A data.table with timestamp data.

crs

The coordinate reference system of the output, as accepted by st_crs. Points are read as WGS84 (EPSG:4326) and transformed to crs. The default value is 4326 (no transformation).

Value

A simple feature (sf) object with point data.

Examples

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)

Convert GTFS shapes to simple feature object (deprecated)

Description

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.

Usage

gtfs_shapes_as_sf(gtfs, crs = 4326)

Arguments

gtfs

A GTFS data. shape_id must be character and shape_pt_sequence integer, as produced by read_gtfs.

crs

The coordinate reference system of the output: an EPSG code, a string accepted by st_crs, or a crs object. Shapes are read as WGS84 (EPSG:4326) and transformed to crs. The default value is 4326 (no transformation). Other inputs (e.g. NA) raise an error, and an empty or unknown CRS raises an error of class gtfs2gps_crs_error.

Value

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.

Examples

sp <- read_gtfs(system.file("extdata/saopaulo.zip", package = "gtfs2gps"))
sp_sf <- suppressWarnings(gtfs_shapes_as_sf(sp))

Convert GTFS stops to simple feature object (deprecated)

Description

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.

Usage

gtfs_stops_as_sf(gtfs, crs = 4326)

Arguments

gtfs

A GTFS data. stop_id must be character and stop_lon and stop_lat numeric, as produced by read_gtfs.

crs

The coordinate reference system of the output: an EPSG code, a string accepted by st_crs, or a crs object. Stops are read as WGS84 (EPSG:4326) and transformed to crs. The default value is 4326 (no transformation). Other inputs (e.g. NA) raise an error, and an empty or unknown CRS raises an error of class gtfs2gps_crs_error.

Value

A simple feature (sf) object.

Examples

poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps"))
poa_stops <- suppressWarnings(gtfs_stops_as_sf(poa))

Convert GTFS to GPS-like data given a spatial resolution

Description

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.

Usage

gtfs2gps(
  gtfs_data,
  spatial_resolution = 100,
  parallel = NULL,
  ncores = 2,
  strategy = NULL,
  filepath = NULL,
  compress = FALSE,
  snap_method = NULL,
  continue = FALSE,
  quiet = FALSE
)

Arguments

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 units length. Default is 100m. This function only creates points in order to guarantee that consecutive points are at most spatial_resolution metres apart. If a given shape has two consecutive points with a distance lower than the spatial resolution, the algorithm will not remove such points.

parallel

This argument is deprecated and ignored. Please use argument ncores instead.

ncores

Number of threads used. Defaults to 2. If Inf, it uses all threads available, as given by data.table::getDTthreads().

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 shape_id. Characters that can't be in a file name on some systems (such as /, : or *) and % are written as %XX, their hexadecimal code, so utils::URLdecode() gives the id back (e.g. "a/b" is saved as a%2Fb.txt). In this case, no output is returned. See argument compress for another option.

compress

Argument that can be used only with filepath. When TRUE, it compresses the output files by saving them using .rds format. Default value is FALSE. Note that compress guarantees that the data saved will be read in the same way as it was created in R. If not compress, the txt extension requires the data to be converted from ITime to string, and therefore they need to be manually converted back to ITime to be properly handled by gtfs2gps.

snap_method

This argument is deprecated and ignored. Stops are now located along the shapes with gtfstools::interpolate_shape_dist_traveled() (see details).

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 FALSE.

quiet

Hide messages while processing the data. Defaults to FALSE.

Details

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.

Value

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.

Examples

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 GTFS data into a list of data.tables

Description

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.

Usage

read_gtfs(gtfszip, quiet = FALSE)

Arguments

gtfszip

A zipped GTFS data.

quiet

A logical. Whether to hide log messages and progress bars. Defaults to FALSE.

Value

A list of data.tables, where each index represents the respective GTFS file name.

Examples

poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps"))

Remove invalid objects from GTFS data (deprecated)

Description

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.

Usage

remove_invalid(gtfs_data, only_essential = TRUE, prompt_invalid = FALSE)

Arguments

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.

Value

A subset of the input GTFS data.

Examples

poa <- read_gtfs(system.file("extdata/poa.zip", package = "gtfs2gps"))
object.size(poa)
subset <- suppressWarnings(remove_invalid(poa))
object.size(subset)

Write GTFS data into a zip file

Description

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.

Usage

write_gtfs(
  gtfs,
  zipfile,
  overwrite = TRUE,
  quiet = FALSE,
  compression_level = 6
)

Arguments

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 .zip file. If FALSE and zipfile already exists, an error is raised. Defaults to TRUE.

quiet

A logical. Whether to hide log messages and progress bars. Defaults to FALSE.

compression_level

A whole number from 1 (fastest) to 9 (smallest file). The compression level of the zip file. Defaults to 6.

Value

The GTFS data, invisibly.

Examples

# 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"))