diff --git a/NEWS.md b/NEWS.md
index a34b8a9..c48335f 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 596c7d4..0d4f5c7 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 ccd7813..6025b6d 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 0f2a83d..b9006e7 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 8ca5714..c314159 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 2b7b28f..057e4c0 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 4b3e110..860d7b1 100644
--- a/README.Rmd
+++ b/README.Rmd
@@ -15,9 +15,9 @@ knitr::opts_chunk$set(
[](https://CRAN.R-project.org/package=gtfstools)
[](https://dhersz.r-universe.dev)
-[](https://github.com/ipea/gtfstools/actions?query=workflow%3Acheck)
+[](https://github.com/ipea/gtfstools/actions?query=workflow%3Acheck)
[](https://app.codecov.io/gh/ipeaGIT/gtfstools?branch=main)
-[](https://lifecycle.r-lib.org/articles/stages.html)
+[](https://lifecycle.r-lib.org/articles/stages.html)
[](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
diff --git a/README.md b/README.md
index a645454..cad9eec 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)
[](https://dhersz.r-universe.dev)
-[](https://github.com/ipea/gtfstools/actions?query=workflow%3Acheck)
+[](https://github.com/ipea/gtfstools/actions?query=workflow%3Acheck)
[](https://app.codecov.io/gh/ipeaGIT/gtfstools?branch=main)
[](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)
[](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
diff --git a/man/filter_by_weekday.Rd b/man/filter_by_weekday.Rd
index fc199c7..ec9f8d3 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 2759027..344ae4b 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 8abd4c1..5f57467 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 4eb2c17..c88b3aa 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 0865c05..1c5e0cf 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 fdcdb58..e7c13c5 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;