change title, update documentation

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

R/frequencies.R

@@ -11,14 +11,14 @@
 #'                    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.
 #'
 #' @importFrom dplyr %>%
 #' @importFrom rlang .data !! quo enquo
 #' @importFrom stats median sd
 #' @importFrom tidyr spread
+#' @export
 #' @examples 
 #' data(gtfs_duke)
 #' stop_frequency <- get_stop_frequency(gtfs_duke)

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,31 +47,34 @@ 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
 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)
 }

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) {

R/plot.R

@@ -1,17 +1,20 @@
 #' 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",
 #'                               package = "tidytransit")
 #' 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")) {

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 

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

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) {

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)

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() {

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.
 #'