From 7d97095347953c4c51209ac8a8f7e49be58e88d0 Mon Sep 17 00:00:00 2001 From: rafapereirabr Date: Sun, 1 Nov 2026 22:04:02 -0300 Subject: [PATCH] minor docs --- NEWS.md | 2 ++ R/filter_by_weekday.R | 15 +++++++++++++++ R/get_trip_speed.R | 8 +++++--- R/set_dwell_time.R | 6 +++--- R/validate_gtfs.R | 9 +++++---- R/write_gtfs.R | 6 +++--- README.Rmd | 15 ++++++++++----- README.md | 31 ++++++++++++++++++------------- man/filter_by_weekday.Rd | 8 ++++++++ man/get_trip_speed.Rd | 8 +++++--- man/set_dwell_time.Rd | 6 +++--- man/validate_gtfs.Rd | 7 ++++--- man/write_gtfs.Rd | 6 +++--- vignettes/editing.Rmd | 3 +++ 14 files changed, 87 insertions(+), 43 deletions(-) diff --git a/NEWS.md b/NEWS.md index a34b8a92..c48335f0 100644 --- a/NEWS.md +++ b/NEWS.md @@ -9,6 +9,8 @@ disrespects the GTFS standard to report times as 24:MM:SS in such cases. This bug has been fixed. Now all functions that calculate or change durations and speeds now fix these times using a new function `fix_overnight_times()` and return correct estimates for overnight trips. +- `filter_by_weekday()` now warns when the GTFS object has no `calendar` table, instead of silently returning it unchanged. Its documentation now states that services defined only in `calendar_dates` are never related to a weekday (use `filter_by_date()` to consider them). +- `validate_gtfs()` now raises an error when `n_threads` is not a whole number, as documented, instead of passing it to the validator. ## New features diff --git a/R/filter_by_weekday.R b/R/filter_by_weekday.R index 596c7d4c..0d4f5c71 100644 --- a/R/filter_by_weekday.R +++ b/R/filter_by_weekday.R @@ -31,6 +31,13 @@ #' that run on mondays and tuesdays or drop them, depending on the value you #' pass to `keep`. #' +#' @details # `calendar_dates` +#' Only the weekday columns of the `calendar` table are used: services defined +#' only in `calendar_dates` are never related to a weekday, so they are dropped +#' when `keep = TRUE` and kept when `keep = FALSE`. A GTFS object without a +#' `calendar` table is returned unchanged, with a warning. To filter by the dates +#' in `calendar_dates` too, use [filter_by_date()]. +#' #' @family filtering functions #' #' @examplesIf requireNamespace("dplyr", quietly = TRUE) @@ -110,6 +117,14 @@ filter_by_weekday <- function(gtfs, weekday, combine = "or", keep = TRUE) { relevant_services <- unique(filtered_calendar$service_id) gtfs <- filter_by_service_id(gtfs, relevant_services, keep) + } else { + cli::cli_warn( + c( + "The GTFS object has no {.file calendar} table.", + "i" = "It was returned unchanged." + ), + class = "gtfstools_no_calendar_warning" + ) } return(gtfs) diff --git a/R/get_trip_speed.R b/R/get_trip_speed.R index ccd78135..6025b6da 100644 --- a/R/get_trip_speed.R +++ b/R/get_trip_speed.R @@ -32,9 +32,11 @@ #' duration calculated by [get_trip_duration()] (with `by = "trip"`) or by #' [get_trip_segment_duration()] (with `by = "segment"`). Speeds are `NA` when #' the length is `NA` (e.g. trips not linked to a shape) or when the duration -#' is missing (e.g. blank times at intermediate stops) or not positive. With -#' `by = "trip"`, trips without any arrival or departure time raise the warning -#' of [get_trip_duration()]. +#' is missing or not positive. With `by = "segment"`, the duration is missing +#' when the segment's departure or arrival time is blank. With `by = "trip"`, +#' blank times at intermediate stops don't affect the duration, which is +#' missing only for trips without any arrival or departure time; these trips +#' raise the warning of [get_trip_duration()]. #' #' The `route_id` of each trip comes from the `trips` table, which is required #' (also with `method = "euclidean"`). Trips not listed in `trips` have an `NA` diff --git a/R/set_dwell_time.R b/R/set_dwell_time.R index 0f2a83d2..b9006e79 100644 --- a/R/set_dwell_time.R +++ b/R/set_dwell_time.R @@ -52,9 +52,9 @@ #' #' @section Details: #' -#' Since the first stop is never changed, the departures of trips listed in -#' `frequencies` are not changed either. Blank arrival or departure times -#' are never filled. +#' The departures of trips listed in `frequencies` are never changed, because +#' [frequencies_to_stop_times()] anchors each of them on the first departure +#' of the trip's template. Blank arrival or departure times are never filled. #' #' For trips listed in `frequencies`, the times in `stop_times` are a template #' (see [frequencies_to_stop_times()]), so setting the dwell time at the first diff --git a/R/validate_gtfs.R b/R/validate_gtfs.R index 8ca57148..c3141596 100644 --- a/R/validate_gtfs.R +++ b/R/validate_gtfs.R @@ -25,9 +25,10 @@ #' Defaults to `FALSE`. #' @param quiet A logical. Whether to hide informative messages. Defaults to #' `TRUE`. -#' @param n_threads An integer between 1 and the number of cores in the running -#' machine. Control how many threads are used during the validation. Defaults -#' to 1. +#' @param n_threads An integer. Control how many threads are used during the +#' validation. Defaults to 1. Values larger than the number of cores in the +#' running machine, or than the number of free R connections, are capped to +#' the smaller of these numbers. #' #' @return Invisibly returns the normalized path to the directory where the #' validation results were saved to. @@ -252,7 +253,7 @@ assert_overwritten_files <- function(output_path, overwrite) { } assert_and_assign_n_threads <- function(n_threads) { - checkmate::assert_number(n_threads, lower = 1, finite = TRUE) + checkmate::assert_count(n_threads, positive = TRUE) n_threads <- min( n_threads, diff --git a/R/write_gtfs.R b/R/write_gtfs.R index 2b7b28f0..057e4c0c 100644 --- a/R/write_gtfs.R +++ b/R/write_gtfs.R @@ -11,7 +11,7 @@ #' @param standard_only Whether to write only standard files and fields #' (defaults to `FALSE`, which doesn't drop extra files and fields). #' @param as_dir Whether to write the feed as a directory, instead of a `.zip` -#' file (defaults to `FALSE`, which means that the field is written as a zip +#' file (defaults to `FALSE`, which means that the feed is written as a zip #' file). #' @param overwrite Whether to overwrite existing `.zip` file (defaults to #' `TRUE`). @@ -22,8 +22,8 @@ #' larger files. Defaults to 6, which is usually several times faster than 9 #' and creates files of very similar size. Ignored when `as_dir = TRUE`. #' -#' @return Invisibly returns the same GTFS object passed to the `gtfs` -#' parameter. +#' @return Invisibly returns the GTFS object passed to the `gtfs` parameter, as +#' a `dt_gtfs` object. #' #' @family io functions #' diff --git a/README.Rmd b/README.Rmd index 4b3e110d..860d7b13 100644 --- a/README.Rmd +++ b/README.Rmd @@ -15,9 +15,9 @@ knitr::opts_chunk$set( [![CRAN status](https://www.r-pkg.org/badges/version/gtfstools)](https://CRAN.R-project.org/package=gtfstools) [![gtfstools status badge](https://dhersz.r-universe.dev/badges/gtfstools)](https://dhersz.r-universe.dev) -[![B status](https://github.com/ipea/gtfstools/workflows/check/badge.svg)](https://github.com/ipea/gtfstools/actions?query=workflow%3Acheck) +[![R-CMD-check](https://github.com/ipea/gtfstools/workflows/check/badge.svg)](https://github.com/ipea/gtfstools/actions?query=workflow%3Acheck) [![Codecov test coverage](https://codecov.io/gh/ipeaGIT/gtfstools/branch/main/graph/badge.svg)](https://app.codecov.io/gh/ipeaGIT/gtfstools?branch=main) -[![Lifecycle: experimental](https://lifecycle.r-lib.org/articles/figures/lifecycle-stable.svg)](https://lifecycle.r-lib.org/articles/stages.html) +[![Lifecycle: stable](https://lifecycle.r-lib.org/articles/figures/lifecycle-stable.svg)](https://lifecycle.r-lib.org/articles/stages.html) [![CRAN/METACRAN Total downloads](http://cranlogs.r-pkg.org/badges/grand-total/gtfstools?color=yellow)](https://CRAN.R-project.org/package=gtfstools) **gtfstools** offers a set of convenient tools for editing and analysing @@ -84,9 +84,14 @@ Please read **gtfstools** vignettes for more on the package usage: ## Related packages -- [`{tidytransit}`](https://github.com/r-transit/tidytransit) -- [`{gtfs2gps}`](https://github.com/ipea/gtfs2gps) -- [`{gtfsrouter}`](https://github.com/UrbanAnalyst/gtfsrouter) +- [`{gtfs2gps}`](https://github.com/ipea/gtfs2gps): Converting public transport data from GTFS format to GPS-like records +- [`{gtfs2emis}`](https://github.com/ipea/gtfs2emis): Estimating public transport emissions from GTFS data +- [`{GTFShift}`](https://u-shift.github.io/GTFShift/): Explore and Analyse GTFS with a Focus on Urban Mobility +- [`{tidytransit}`](https://github.com/r-transit/tidytransit): Read, Validate, Analyze, and Map GTFS Feeds +- [`{croquis}`](https://github.com/julian-city/croquis/): Interactive way to create and edit GTFS feeds in R +- [`{gtfsrealtime}`](https://projects.indicatrix.org/gtfsrealtime-r/): Read GTFS-Realtime Files into Data Frames +- [`{gtfsrouter}`](https://github.com/UrbanAnalyst/gtfsrouter): Routing with GTFS data +- [`{r5r}`](https://ipea.github.io/r5r/): Rapid Realistic Routing with R5 in R ## Acknowledgement IPEA diff --git a/README.md b/README.md index a6454542..cad9eec7 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,11 @@ status](https://www.r-pkg.org/badges/version/gtfstools)](https://CRAN.R-project.org/package=gtfstools) [![gtfstools status badge](https://dhersz.r-universe.dev/badges/gtfstools)](https://dhersz.r-universe.dev) -[![B -status](https://github.com/ipea/gtfstools/workflows/check/badge.svg)](https://github.com/ipea/gtfstools/actions?query=workflow%3Acheck) +[![R-CMD-check](https://github.com/ipea/gtfstools/workflows/check/badge.svg)](https://github.com/ipea/gtfstools/actions?query=workflow%3Acheck) [![Codecov test coverage](https://codecov.io/gh/ipeaGIT/gtfstools/branch/main/graph/badge.svg)](https://app.codecov.io/gh/ipeaGIT/gtfstools?branch=main) [![Lifecycle: -experimental](https://lifecycle.r-lib.org/articles/figures/lifecycle-stable.svg)](https://lifecycle.r-lib.org/articles/stages.html) +stable](https://lifecycle.r-lib.org/articles/figures/lifecycle-stable.svg)](https://lifecycle.r-lib.org/articles/stages.html) [![CRAN/METACRAN Total downloads](http://cranlogs.r-pkg.org/badges/grand-total/gtfstools?color=yellow)](https://CRAN.R-project.org/package=gtfstools) @@ -80,16 +79,22 @@ Please read **gtfstools** vignettes for more on the package usage: ## Related packages -- [`{gtfs2gps}`](https://github.com/ipea/gtfs2gps): Converting public transport data from GTFS format to GPS-like records -- [`{gtfs2emis}`](https://github.com/ipea/gtfs2emis): Estimating public transport emissions from GTFS data -- [`{GTFShift}`](https://u-shift.github.io/GTFShift/): Explore and Analyse GTFS with a Focus on Urban Mobility -- [`{tidytransit}`](https://github.com/r-transit/tidytransit): Read, Validate, Analyze, and Map GTFS Feeds -- [`{croquis}`](https://github.com/julian-city/croquis/): Interactive way to create and edit GTFS feeds in R -- [`{gtfsrealtime}`](https://projects.indicatrix.org/gtfsrealtime-r/): Read GTFS-Realtime Files into Data Frames -- [`{gtfsrouter}`](https://github.com/UrbanAnalyst/gtfsrouter): Routing with GTFS data -- [`{r5r}`](https://ipea.github.io/r5r/): Rapid Realistic Routing with R5 in R - - +- [`{gtfs2gps}`](https://github.com/ipea/gtfs2gps): Converting public + transport data from GTFS format to GPS-like records +- [`{gtfs2emis}`](https://github.com/ipea/gtfs2emis): Estimating public + transport emissions from GTFS data +- [`{GTFShift}`](https://u-shift.github.io/GTFShift/): Explore and + Analyse GTFS with a Focus on Urban Mobility +- [`{tidytransit}`](https://github.com/r-transit/tidytransit): Read, + Validate, Analyze, and Map GTFS Feeds +- [`{croquis}`](https://github.com/julian-city/croquis/): Interactive + way to create and edit GTFS feeds in R +- [`{gtfsrealtime}`](https://projects.indicatrix.org/gtfsrealtime-r/): + Read GTFS-Realtime Files into Data Frames +- [`{gtfsrouter}`](https://github.com/UrbanAnalyst/gtfsrouter): Routing + with GTFS data +- [`{r5r}`](https://ipea.github.io/r5r/): Rapid Realistic Routing with + R5 in R ## Acknowledgement IPEA diff --git a/man/filter_by_weekday.Rd b/man/filter_by_weekday.Rd index fc199c70..ec9f8d37 100644 --- a/man/filter_by_weekday.Rd +++ b/man/filter_by_weekday.Rd @@ -43,6 +43,14 @@ that run on mondays and tuesdays or drop them, depending on the value you pass to \code{keep}. } +\section{\code{calendar_dates}}{ +Only the weekday columns of the \code{calendar} table are used: services defined +only in \code{calendar_dates} are never related to a weekday, so they are dropped +when \code{keep = TRUE} and kept when \code{keep = FALSE}. A GTFS object without a +\code{calendar} table is returned unchanged, with a warning. To filter by the dates +in \code{calendar_dates} too, use \code{\link[=filter_by_date]{filter_by_date()}}. +} + \examples{ \dontshow{if (requireNamespace("dplyr", quietly = TRUE)) withAutoprint(\{ # examplesIf} \dontshow{ diff --git a/man/get_trip_speed.Rd b/man/get_trip_speed.Rd index 27590271..344ae4bd 100644 --- a/man/get_trip_speed.Rd +++ b/man/get_trip_speed.Rd @@ -72,9 +72,11 @@ The speed is the length calculated by \code{\link[=get_trip_length]{get_trip_len duration calculated by \code{\link[=get_trip_duration]{get_trip_duration()}} (with \code{by = "trip"}) or by \code{\link[=get_trip_segment_duration]{get_trip_segment_duration()}} (with \code{by = "segment"}). Speeds are \code{NA} when the length is \code{NA} (e.g. trips not linked to a shape) or when the duration -is missing (e.g. blank times at intermediate stops) or not positive. With -\code{by = "trip"}, trips without any arrival or departure time raise the warning -of \code{\link[=get_trip_duration]{get_trip_duration()}}. +is missing or not positive. With \code{by = "segment"}, the duration is missing +when the segment's departure or arrival time is blank. With \code{by = "trip"}, +blank times at intermediate stops don't affect the duration, which is +missing only for trips without any arrival or departure time; these trips +raise the warning of \code{\link[=get_trip_duration]{get_trip_duration()}}. The \code{route_id} of each trip comes from the \code{trips} table, which is required (also with \code{method = "euclidean"}). Trips not listed in \code{trips} have an \code{NA} diff --git a/man/set_dwell_time.Rd b/man/set_dwell_time.Rd index 8abd4c15..5f57467e 100644 --- a/man/set_dwell_time.Rd +++ b/man/set_dwell_time.Rd @@ -87,9 +87,9 @@ change. \section{Details}{ -Since the first stop is never changed, the departures of trips listed in -\code{frequencies} are not changed either. Blank arrival or departure times -are never filled. +The departures of trips listed in \code{frequencies} are never changed, because +\code{\link[=frequencies_to_stop_times]{frequencies_to_stop_times()}} anchors each of them on the first departure +of the trip's template. Blank arrival or departure times are never filled. For trips listed in \code{frequencies}, the times in \code{stop_times} are a template (see \code{\link[=frequencies_to_stop_times]{frequencies_to_stop_times()}}), so setting the dwell time at the first diff --git a/man/validate_gtfs.Rd b/man/validate_gtfs.Rd index 4eb2c170..c88b3aac 100644 --- a/man/validate_gtfs.Rd +++ b/man/validate_gtfs.Rd @@ -39,9 +39,10 @@ Defaults to \code{FALSE}.} \item{quiet}{A logical. Whether to hide informative messages. Defaults to \code{TRUE}.} -\item{n_threads}{An integer between 1 and the number of cores in the running -machine. Control how many threads are used during the validation. Defaults -to 1.} +\item{n_threads}{An integer. Control how many threads are used during the +validation. Defaults to 1. Values larger than the number of cores in the +running machine, or than the number of free R connections, are capped to +the smaller of these numbers.} } \value{ Invisibly returns the normalized path to the directory where the diff --git a/man/write_gtfs.Rd b/man/write_gtfs.Rd index 0865c05d..1c5e0cfe 100644 --- a/man/write_gtfs.Rd +++ b/man/write_gtfs.Rd @@ -29,7 +29,7 @@ object are written.} (defaults to \code{FALSE}, which doesn't drop extra files and fields).} \item{as_dir}{Whether to write the feed as a directory, instead of a \code{.zip} -file (defaults to \code{FALSE}, which means that the field is written as a zip +file (defaults to \code{FALSE}, which means that the feed is written as a zip file).} \item{overwrite}{Whether to overwrite existing \code{.zip} file (defaults to @@ -44,8 +44,8 @@ larger files. Defaults to 6, which is usually several times faster than 9 and creates files of very similar size. Ignored when \code{as_dir = TRUE}.} } \value{ -Invisibly returns the same GTFS object passed to the \code{gtfs} -parameter. +Invisibly returns the GTFS object passed to the \code{gtfs} parameter, as +a \code{dt_gtfs} object. } \description{ Writes GTFS objects as GTFS \code{.zip} files. diff --git a/vignettes/editing.Rmd b/vignettes/editing.Rmd index fdcdb589..e7c13c56 100644 --- a/vignettes/editing.Rmd +++ b/vignettes/editing.Rmd @@ -34,7 +34,10 @@ GTFS feeds describe the transit services of a city or region as they are. Quite - `interpolate_shape_dist_traveled()`: calculates the distances, in meters, travelled along the shapes up to each stop and shape point, replacing any existing ones; - `set_route_speed()`: sets the average speed of the trips of routes, or of a segment of them; - `set_max_speed()`: caps the speed of trips, slowing down only the parts that are faster than a maximum speed; +- `set_min_speed()`: raises the speed of trips, speeding up only the parts that are slower than a minimum speed; - `set_dwell_time()`: sets how long vehicles stay at stops; +- `set_min_dwell_time()`: makes vehicles stay at least a minimum time at stops; +- `combine_nearby_stops()`: merges the stops within a given distance of each other into a single stop; - `frequencies_to_stop_times()`: converts frequency-based trips into scheduled ones; - `merge_gtfs()`: combines several feeds into a single one; - `remove_duplicates()`: removes duplicated entries from the feed's tables;