From 030bc323ceb70de0d460c75f78fc73923bf557b3 Mon Sep 17 00:00:00 2001 From: Flavio Poletti Date: Mon, 26 Jul 2021 10:43:11 +0200 Subject: [PATCH] change title, update documentation --- DESCRIPTION | 2 +- R/frequencies.R | 2 +- R/io.R | 22 +++++++++++++--------- R/joins.R | 8 +++++--- R/plot.R | 9 ++++++--- R/raptor.R | 2 +- R/service.R | 5 +++-- R/spatial.R | 11 +++++++++-- R/summary.R | 10 +++++++++- R/transitfeeds.R | 4 ++-- R/validate_gtfs.R | 2 +- man/agency_info.Rd | 8 ++++++++ man/filter_feed_by_date.Rd | 4 +--- man/filter_stop_times.Rd | 7 ++++--- man/filter_stops.Rd | 2 +- man/get_feedlist.Rd | 2 +- man/gtfs_as_sf.Rd | 2 +- man/gtfs_transform.Rd | 3 +++ man/plot.tidygtfs.Rd | 4 ++++ man/print.tidygtfs.Rd | 2 +- man/read_gtfs.Rd | 1 + man/set_api_key.Rd | 3 +++ man/set_servicepattern.Rd | 4 ++-- man/sf_as_tbl.Rd | 3 +++ man/summary.tidygtfs.Rd | 3 +++ man/validate_gtfs.Rd | 2 +- man/write_gtfs.Rd | 5 ++++- 27 files changed, 92 insertions(+), 40 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 40b9872f..6dd72ad4 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: tidytransit Type: Package -Title: Read, Validate, Analyze, and Map Files in the General Transit Feed Specification +Title: Read, Validate, Analyze, and Map GTFS Feeds Version: 1.1.0 Authors@R: c( person("Flavio", "Poletti", role = c("aut", "cre"), email = "flavio.poletti@hotmail.ch"), diff --git a/R/frequencies.R b/R/frequencies.R index 930792c9..51efa9cb 100644 --- a/R/frequencies.R +++ b/R/frequencies.R @@ -11,7 +11,6 @@ #' identifying a particular service id. If not provided the service_id #' with the most departures is used #' @param by_route default TRUE, if FALSE then calculate headway for any line coming through the stop in the same direction on the same schedule. -#' @export #' @return dataframe of stops with the number of departures and the headway #' (departures divided by timespan) as columns. #' @@ -19,6 +18,7 @@ #' @importFrom rlang .data !! quo enquo #' @importFrom stats median sd #' @importFrom tidyr spread +#' @export #' @examples #' data(gtfs_duke) #' stop_frequency <- get_stop_frequency(gtfs_duke) diff --git a/R/io.R b/R/io.R index 35b8b46f..e79a8176 100644 --- a/R/io.R +++ b/R/io.R @@ -9,7 +9,7 @@ #' existing files are read. #' @param quiet Whether to hide log messages and progress bars (defaults to TRUE). #' @return A tidygtfs object: a list of tibbles in which each entry represents a -#' GTFS text file. Additional tables are stored in the \code{.} sublist. +#' GTFS text file. Additional tables are stored in the \code{.} sublist. #' #' @seealso \code{\link{validate_gtfs}} #' @@ -20,6 +20,7 @@ #' #' gtfs <- read_gtfs(local_gtfs_path, files = c("trips", "stop_times")) #' names(gtfs) +#' #' @importFrom gtfsio import_gtfs new_gtfs #' @export read_gtfs <- function(path, files = NULL, quiet = TRUE) { @@ -46,11 +47,13 @@ read_gtfs <- function(path, files = NULL, quiet = TRUE) { #' Write a tidygtfs object to a zip file #' #' @note Auxilliary tidytransit tables (e.g. \code{dates_services}) are not exported. -#' @param gtfs_obj a gtfs feed object +#' @param gtfs_obj a tidygtfs object #' @param zipfile path to the zip file the feed should be written to #' @param compression_level a number between 1 and 9.9, passed to zip::zip #' @param as_dir if TRUE, the feed is not zipped and zipfile is used as a directory path. #' Files within the directory will be overwritten. +#' @return Invisibly returns gtfs_obj +#' #' @importFrom zip zipr #' @importFrom gtfsio export_gtfs #' @export @@ -58,19 +61,20 @@ write_gtfs <- function(gtfs_obj, zipfile, compression_level = 9, as_dir = FALSE) stopifnot(inherits(gtfs_obj, "tidygtfs")) # convert sf tables - gtfs_obj <- sf_as_tbl(gtfs_obj) + gtfs_out = sf_as_tbl(gtfs_obj) # data.tables - gtfs_obj <- gtfs_obj[names(gtfs_obj) != "."] - gtfs_obj <- lapply(gtfs_obj, as.data.table) - class(gtfs_obj) <- list("gtfs") + gtfs_out <- gtfs_out[names(gtfs_out) != "."] + gtfs_out <- lapply(gtfs_out, as.data.table) + class(gtfs_out) <- list("gtfs") # convert dates/times to strings - gtfs_obj <- convert_dates(gtfs_obj, date_as_gtfsio_char) - gtfs_obj <- convert_hms_to_char(gtfs_obj) + gtfs_out <- convert_dates(gtfs_out, date_as_gtfsio_char) + gtfs_out <- convert_hms_to_char(gtfs_out) - gtfsio::export_gtfs(gtfs_obj, zipfile, + gtfsio::export_gtfs(gtfs_out, zipfile, standard_only = FALSE, compression_level = compression_level, as_dir = as_dir, overwrite = TRUE) + invisible(gtfs_obj) } diff --git a/R/joins.R b/R/joins.R index e986cea2..046f81f7 100644 --- a/R/joins.R +++ b/R/joins.R @@ -3,7 +3,8 @@ #' @param gtfs_obj as read by read_gtfs() #' @param service_ids the service for which to get stops #' @param route_ids the route_ids for which to get stops -#' @return stops for a given service +#' @return stops table for a given service +#' #' @export #' @examples \donttest{ #' library(dplyr) @@ -32,10 +33,10 @@ filter_stops <- function(gtfs_obj, service_ids, route_ids) { #' Only stop_times, stops, routes, services (in calendar and calendar_dates), shapes, #' frequencies and transfers belonging to one of those trips are kept. #' -#' @return tidygtfs object with filtered tables -#' #' @param gtfs_obj tidygtfs object #' @param trip_ids vector with trip_ids +#' @return tidygtfs object with filtered tables +#' #' @seealso \code{\link{filter_feed_by_stops}}, \code{\link{filter_feed_by_area}}, \code{\link{filter_feed_by_date}} #' @export filter_feed_by_trips = function(gtfs_obj, trip_ids) { @@ -121,6 +122,7 @@ filter_feed_by_area <- function(gtfs_obj, area) { #' @param gtfs_obj tidygtfs object #' @param stop_ids vector with stop_ids. You can either provide stop_ids or stop_names #' @param stop_names vector with stop_names (will be converted to stop_ids) +#' #' @seealso \code{\link{filter_feed_by_trips}}, \code{\link{filter_feed_by_trips}}, \code{\link{filter_feed_by_date}} #' @export filter_feed_by_stops = function(gtfs_obj, stop_ids = NULL, stop_names = NULL) { diff --git a/R/plot.R b/R/plot.R index 93d5a369..44b2d92a 100644 --- a/R/plot.R +++ b/R/plot.R @@ -1,10 +1,9 @@ #' Plot GTFS stops and trips #' #' @param x a gtfs_obj as read by read_gtfs() -#' @export #' @param ... further specifications -#' @importFrom graphics plot -#' @importFrom dplyr select +#' @return plot +#' #' @examples \donttest{ #' local_gtfs_path <- system.file("extdata", #' "google_transit_nyc_subway.zip", @@ -12,6 +11,10 @@ #' nyc <- read_gtfs(local_gtfs_path) #' plot(nyc) #' } +#' +#' @importFrom graphics plot +#' @importFrom dplyr select +#' @export plot.tidygtfs <- function(x, ...) { dots <- list(...) if(!feed_contains(x, "stops")) { diff --git a/R/raptor.R b/R/raptor.R index 3afc47b4..5a09c714 100644 --- a/R/raptor.R +++ b/R/raptor.R @@ -445,7 +445,7 @@ travel_times = function(filtered_stop_times, #' @param max_arrival_time The latest arrival time. Can be given as "HH:MM:SS", #' hms object or numeric value in seconds #' -#' This function creates filtered `stop_times` for [travel_times()] and [raptor()]. +#' @return Filtered `stop_times` data.table for [travel_times()] and [raptor()]. #' #' @export #' @examples diff --git a/R/service.R b/R/service.R index 9a7b0ff1..05044aa0 100644 --- a/R/service.R +++ b/R/service.R @@ -28,8 +28,9 @@ service_by_dow <- function(calendar, #' @param id_prefix all servicepattern id will start with this string #' @param hash_algo hashing algorithm used by digest #' @param hash_length length the hash should be cut to with substr(). Use -1 if the full hash should be used -#' @return modified gtfs_obj with added servicepattern list and a table linking trips and pattern (trip_servicepatterns) -#' @keywords internal +#' @return modified gtfs_obj with added servicepattern list and a table linking +#' trips and pattern (trip_servicepatterns) +#' #' @importFrom dplyr group_by summarise ungroup left_join #' @importFrom digest digest #' @importFrom rlang .data diff --git a/R/spatial.R b/R/spatial.R index 87625295..81eafa06 100644 --- a/R/spatial.R +++ b/R/spatial.R @@ -9,7 +9,7 @@ #' @param crs optional coordinate reference system (used by sf::st_transform) to transform #' lon/lat coordinates of stops and shapes #' @param quiet boolean whether to print status messages -#' @return gtfs_obj a tidytransit gtfs object with stops and shapes as sf data frames +#' @return tidygtfs object with stops and shapes as sf dataframes #' @seealso \code{\link{sf_as_tbl}} #' @export gtfs_as_sf <- function(gtfs_obj, skip_shapes = FALSE, crs = NULL, quiet = TRUE) { @@ -56,8 +56,8 @@ stops_as_sf <- function(stops, crs = NULL) { #' @param gtfs_shapes a gtfs$shapes dataframe #' @param crs optional coordinate reference system (used by sf::st_transform) to transform #' lon/lat coordinates -#' @export #' @return an sf dataframe for gtfs shapes +#' @export shapes_as_sf <- function(gtfs_shapes, crs = NULL) { list_of_line_tibbles <- split(gtfs_shapes, gtfs_shapes$shape_id) list_of_linestrings <- lapply(list_of_line_tibbles, shape_as_sf_linestring) @@ -80,6 +80,7 @@ shapes_as_sf <- function(gtfs_shapes, crs = NULL) { #' @param route_ids routes to extract #' @param service_ids service_ids to extract #' @return an sf dataframe for gtfs routes with a row/linestring for each trip +#' #' @importFrom dplyr inner_join distinct #' @importFrom sf st_cast #' @export @@ -122,6 +123,7 @@ get_route_geometry <- function(gtfs_sf_obj, route_ids = NULL, service_ids = NULL #' @param gtfs_sf_obj tidytransit gtfs object with sf data frames #' @param trip_ids trip_ids to extract shapes #' @return an sf dataframe for gtfs routes with a row/linestring for each trip +#' #' @export #' @examples #' data(gtfs_duke) @@ -158,6 +160,8 @@ shape_as_sf_linestring <- function(df) { #' Transform or convert coordinates of a gtfs feed #' @param gtfs_obj tidygtfs object #' @param crs target coordinate reference system, used by sf::st_transform +#' @return tidygtfs object with transformed stops and shapes sf dataframes +#' #' @importFrom sf st_transform #' @export gtfs_transform = function(gtfs_obj, crs) { @@ -173,6 +177,9 @@ gtfs_transform = function(gtfs_obj, crs) { #' #' Coordinates are transformed to lon/lat #' @param gtfs_obj tidygtfs object +#' +#' @return tidygtfs object with stops and shapes converted to tibbles +#' #' @seealso \code{\link{gtfs_as_sf}} #' @export sf_as_tbl = function(gtfs_obj) { diff --git a/R/summary.R b/R/summary.R index 69a3f1f6..2b8ed998 100644 --- a/R/summary.R +++ b/R/summary.R @@ -5,7 +5,7 @@ #' @param x A GTFS object. #' @param ... Optional arguments ultimately passed to \code{format}. #' -#' @return The GTFS object that was printed, invisibly. +#' @return The GTFS object that was printed, invisibly #' #' @examples \dontrun{ #' path = system.file("extdata", @@ -27,6 +27,9 @@ print.tidygtfs = function(x, ...) { #' #' @param object a gtfs_obj as read by [read_gtfs()] #' @export +#' +#' @return the tidygtfs object, invisibly +#' #' @param ... further specifications #' @importFrom dplyr select arrange filter summary.tidygtfs <- function(object, ...) { @@ -77,10 +80,15 @@ summary.tidygtfs <- function(object, ...) { cat(paste0("# stop_ids ", format(n_stop_ids, width = w), "\n")) cat(paste0("# stop_names ", format(n_stop_names, width = w), "\n")) cat(paste0("# shapes ", format(n_shapes, width = w), "\n")) + + invisible(object) } #' Create a text listing the first `max_agencies` agencies of the feed +#' @param gtfs_obj tidygtfs object +#' @param max_agencies max number of agencies to list before using "..." #' @keywords internal +#' @return called for side effects agency_info <- function(gtfs_obj, max_agencies = 3) { agencies <- gtfs_obj$agency$agency_name ag_n <- length(agencies) diff --git a/R/transitfeeds.R b/R/transitfeeds.R index e2e4fc66..c06dd200 100644 --- a/R/transitfeeds.R +++ b/R/transitfeeds.R @@ -3,7 +3,7 @@ #' @importFrom utils "read.csv" #' @importFrom stats "na.omit" #' @importFrom stats "setNames" -#' @return a data frame with the gtfs feeds on transitfeeds. +#' @return a data frame with the gtfs feeds on transitfeeds #' @seealso feedlist_df #' #' @export @@ -121,8 +121,8 @@ gtfs_api_key <- tools_api_key() clear_api_key <- gtfs_api_key$clear #' Set TransitFeeds API key for recall +#' @return No value returned, function is used for setting environment variables #' @export - set_api_key <- gtfs_api_key$set api_check <- function() { diff --git a/R/validate_gtfs.R b/R/validate_gtfs.R index 40c58181..55bef530 100644 --- a/R/validate_gtfs.R +++ b/R/validate_gtfs.R @@ -11,7 +11,7 @@ #' @param quiet Whether to hide log messages (defaults to TRUE). #' @param warnings Whether to display warning messages (defaults to TRUE). #' -#' @return A GTFS object with a \code{validation_result} attribute. This +#' @return A tidygtfs with a \code{validation_result} attribute. This #' attribute is a \code{tibble} containing the validation summary of all #' possible fields from the specified files. #' diff --git a/man/agency_info.Rd b/man/agency_info.Rd index 9e2b0810..098c06f6 100644 --- a/man/agency_info.Rd +++ b/man/agency_info.Rd @@ -6,6 +6,14 @@ \usage{ agency_info(gtfs_obj, max_agencies = 3) } +\arguments{ +\item{gtfs_obj}{tidygtfs object} + +\item{max_agencies}{max number of agencies to list before using "..."} +} +\value{ +called for side effects +} \description{ Create a text listing the first \code{max_agencies} agencies of the feed } diff --git a/man/filter_feed_by_date.Rd b/man/filter_feed_by_date.Rd index 17848f31..26ed9633 100644 --- a/man/filter_feed_by_date.Rd +++ b/man/filter_feed_by_date.Rd @@ -20,9 +20,7 @@ filter_feed_by_date( hms object or numeric value in seconds.} \item{max_arrival_time}{The latest arrival time. Can be given as "HH:MM:SS", -hms object or numeric value in seconds - -This function creates filtered \code{stop_times} for \code{\link[=travel_times]{travel_times()}} and \code{\link[=raptor]{raptor()}}.} +hms object or numeric value in seconds} } \value{ tidygtfs object with filtered tables diff --git a/man/filter_stop_times.Rd b/man/filter_stop_times.Rd index 8fd5d9c9..f1036b1f 100644 --- a/man/filter_stop_times.Rd +++ b/man/filter_stop_times.Rd @@ -15,9 +15,10 @@ filter_stop_times(gtfs_obj, extract_date, min_departure_time, max_arrival_time) hms object or numeric value in seconds.} \item{max_arrival_time}{The latest arrival time. Can be given as "HH:MM:SS", -hms object or numeric value in seconds - -This function creates filtered \code{stop_times} for \code{\link[=travel_times]{travel_times()}} and \code{\link[=raptor]{raptor()}}.} +hms object or numeric value in seconds} +} +\value{ +Filtered \code{stop_times} data.table for \code{\link[=travel_times]{travel_times()}} and \code{\link[=raptor]{raptor()}}. } \description{ Filter a \code{stop_times} table for a given date and timespan. diff --git a/man/filter_stops.Rd b/man/filter_stops.Rd index acd1dbeb..6f1efcff 100644 --- a/man/filter_stops.Rd +++ b/man/filter_stops.Rd @@ -14,7 +14,7 @@ filter_stops(gtfs_obj, service_ids, route_ids) \item{route_ids}{the route_ids for which to get stops} } \value{ -stops for a given service +stops table for a given service } \description{ Get a set of stops for a given set of service ids and route ids diff --git a/man/get_feedlist.Rd b/man/get_feedlist.Rd index c15c216d..118d1695 100644 --- a/man/get_feedlist.Rd +++ b/man/get_feedlist.Rd @@ -7,7 +7,7 @@ get_feedlist() } \value{ -a data frame with the gtfs feeds on transitfeeds. +a data frame with the gtfs feeds on transitfeeds } \description{ Get list of all available feeds from transitfeeds API diff --git a/man/gtfs_as_sf.Rd b/man/gtfs_as_sf.Rd index d0bdcf7f..e7a97ab5 100644 --- a/man/gtfs_as_sf.Rd +++ b/man/gtfs_as_sf.Rd @@ -17,7 +17,7 @@ lon/lat coordinates of stops and shapes} \item{quiet}{boolean whether to print status messages} } \value{ -gtfs_obj a tidytransit gtfs object with stops and shapes as sf data frames +tidygtfs object with stops and shapes as sf dataframes } \description{ Stops are converted to POINT sf data frames. Shapes are created as diff --git a/man/gtfs_transform.Rd b/man/gtfs_transform.Rd index b4216611..d5d2bb7f 100644 --- a/man/gtfs_transform.Rd +++ b/man/gtfs_transform.Rd @@ -11,6 +11,9 @@ gtfs_transform(gtfs_obj, crs) \item{crs}{target coordinate reference system, used by sf::st_transform} } +\value{ +tidygtfs object with transformed stops and shapes sf dataframes +} \description{ Transform or convert coordinates of a gtfs feed } diff --git a/man/plot.tidygtfs.Rd b/man/plot.tidygtfs.Rd index 07ecc22c..b4318323 100644 --- a/man/plot.tidygtfs.Rd +++ b/man/plot.tidygtfs.Rd @@ -11,6 +11,9 @@ \item{...}{further specifications} } +\value{ +plot +} \description{ Plot GTFS stops and trips } @@ -22,4 +25,5 @@ local_gtfs_path <- system.file("extdata", nyc <- read_gtfs(local_gtfs_path) plot(nyc) } + } diff --git a/man/print.tidygtfs.Rd b/man/print.tidygtfs.Rd index 6789f4b6..43d823e6 100644 --- a/man/print.tidygtfs.Rd +++ b/man/print.tidygtfs.Rd @@ -12,7 +12,7 @@ \item{...}{Optional arguments ultimately passed to \code{format}.} } \value{ -The GTFS object that was printed, invisibly. +The GTFS object that was printed, invisibly } \description{ Prints a GTFS object suppressing the \code{class} attribute. diff --git a/man/read_gtfs.Rd b/man/read_gtfs.Rd index f5b6aebc..35672a33 100644 --- a/man/read_gtfs.Rd +++ b/man/read_gtfs.Rd @@ -30,6 +30,7 @@ names(gtfs) gtfs <- read_gtfs(local_gtfs_path, files = c("trips", "stop_times")) names(gtfs) + } \seealso{ \code{\link{validate_gtfs}} diff --git a/man/set_api_key.Rd b/man/set_api_key.Rd index 7a61b2db..2dda9b33 100644 --- a/man/set_api_key.Rd +++ b/man/set_api_key.Rd @@ -6,6 +6,9 @@ \usage{ set_api_key() } +\value{ +No value returned, function is used for setting environment variables +} \description{ Set TransitFeeds API key for recall } diff --git a/man/set_servicepattern.Rd b/man/set_servicepattern.Rd index d8025867..e3ab7cfb 100644 --- a/man/set_servicepattern.Rd +++ b/man/set_servicepattern.Rd @@ -21,7 +21,8 @@ set_servicepattern( \item{hash_length}{length the hash should be cut to with substr(). Use -1 if the full hash should be used} } \value{ -modified gtfs_obj with added servicepattern list and a table linking trips and pattern (trip_servicepatterns) +modified gtfs_obj with added servicepattern list and a table linking +trips and pattern (trip_servicepatterns) } \description{ Each trip has a defined number of dates it runs on. This set of dates is called a @@ -29,4 +30,3 @@ service pattern in tidytransit. Trips with the same servicepattern id run on the dates. In general, \code{service_id} can work this way but it is not enforced by the GTFS standard. } -\keyword{internal} diff --git a/man/sf_as_tbl.Rd b/man/sf_as_tbl.Rd index 2c718d63..5bc4d4f4 100644 --- a/man/sf_as_tbl.Rd +++ b/man/sf_as_tbl.Rd @@ -9,6 +9,9 @@ sf_as_tbl(gtfs_obj) \arguments{ \item{gtfs_obj}{tidygtfs object} } +\value{ +tidygtfs object with stops and shapes converted to tibbles +} \description{ Coordinates are transformed to lon/lat } diff --git a/man/summary.tidygtfs.Rd b/man/summary.tidygtfs.Rd index 68390c8b..e3cb56a9 100644 --- a/man/summary.tidygtfs.Rd +++ b/man/summary.tidygtfs.Rd @@ -11,6 +11,9 @@ \item{...}{further specifications} } +\value{ +the tidygtfs object, invisibly +} \description{ GTFS feed summary } diff --git a/man/validate_gtfs.Rd b/man/validate_gtfs.Rd index 79d76b8f..1c82501e 100644 --- a/man/validate_gtfs.Rd +++ b/man/validate_gtfs.Rd @@ -19,7 +19,7 @@ possible GTFS text files.} \item{warnings}{Whether to display warning messages (defaults to TRUE).} } \value{ -A GTFS object with a \code{validation_result} attribute. This +A tidygtfs with a \code{validation_result} attribute. This attribute is a \code{tibble} containing the validation summary of all possible fields from the specified files. } diff --git a/man/write_gtfs.Rd b/man/write_gtfs.Rd index 46a174b2..e01a923d 100644 --- a/man/write_gtfs.Rd +++ b/man/write_gtfs.Rd @@ -7,7 +7,7 @@ write_gtfs(gtfs_obj, zipfile, compression_level = 9, as_dir = FALSE) } \arguments{ -\item{gtfs_obj}{a gtfs feed object} +\item{gtfs_obj}{a tidygtfs object} \item{zipfile}{path to the zip file the feed should be written to} @@ -16,6 +16,9 @@ write_gtfs(gtfs_obj, zipfile, compression_level = 9, as_dir = FALSE) \item{as_dir}{if TRUE, the feed is not zipped and zipfile is used as a directory path. Files within the directory will be overwritten.} } +\value{ +Invisibly returns gtfs_obj +} \description{ Write a tidygtfs object to a zip file }