diff --git a/r-package/NAMESPACE b/r-package/NAMESPACE index d27d5bc2..e5ee5d6a 100644 --- a/r-package/NAMESPACE +++ b/r-package/NAMESPACE @@ -4,6 +4,7 @@ export(accessibility) export(detailed_itineraries) export(download_r5) export(expanded_travel_time_matrix) +export(fareto_debug) export(find_snap) export(isochrone) export(pareto_frontier) diff --git a/r-package/R/fareto_debug.R b/r-package/R/fareto_debug.R index d66da0f6..7696a7b5 100644 --- a/r-package/R/fareto_debug.R +++ b/r-package/R/fareto_debug.R @@ -1,29 +1,50 @@ #' Output Fareto-format JSON for visualization with Fareto -#' -#' This is primarily intended for debugging the fare system code. Fareto is an external tool -#' that provides visualization for R5's McRAPTOR fare calculator. To use this, -#' run fareto_debug(...) as if you were running paretoFrontier(...). The return value is a JSON-formatted -#' string. Use [rfareto](https://github.com/mattwigway/rfareto) to visualize the results. +#' +#' This is primarily intended for debugging the fare system code. Fareto is an +#' external tool that provides visualization for R5's McRAPTOR fare calculator. +#' To use this, run `fareto_debug(...)` like you would run `pareto_frontier(...)`. +#' Use [rfareto](https://github.com/mattwigway/rfareto) to visualize the results. +#' +#' @template r5r_core +#' @template common_arguments +#' @template time_window_related_args +#' @template fare_structure +#' @template verbose +#' @param percentiles An integer vector (max length of 5). Specifies the +#' percentile to use when returning travel time estimates within the given +#' time window. Please note that this parameter is applied to the travel time +#' estimates only (e.g. if the 25th percentile is specified, and the output +#' between A and B is 15 minutes and 10 dollars, 25% of all trips cheaper +#' than 10 dollars taken between these points are shorter than 15 minutes). +#' Defaults to 50, returning the median travel time. If a vector with length +#' bigger than 1 is passed, the output contains an additional column that +#' specifies the percentile of each travel time and monetary cost +#' combination. Due to upstream restrictions, only 5 percentiles can be +#' specified at a time. For more details, please see R5 documentation at +#' . +#' +#' @return A JSON-formatted string. +#' @export fareto_debug <- function(r5r_core, - origins, - destinations, - mode = c("WALK", "TRANSIT"), - mode_egress = "WALK", - departure_datetime = Sys.time(), - time_window = 10L, - percentiles = 50L, - max_walk_time = Inf, - max_bike_time = Inf, - max_car_time = Inf, - max_trip_duration = 120L, - fare_structure = NULL, - walk_speed = 3.6, - bike_speed = 12, - max_rides = 3, - max_lts = 2, - n_threads = Inf, - verbose = FALSE, - progress = FALSE) { + origins, + destinations, + mode = c("WALK", "TRANSIT"), + mode_egress = "WALK", + departure_datetime = Sys.time(), + time_window = 10L, + percentiles = 50L, + max_walk_time = Inf, + max_bike_time = Inf, + max_car_time = Inf, + max_trip_duration = 120L, + fare_structure = NULL, + walk_speed = 3.6, + bike_speed = 12, + max_rides = 3, + max_lts = 2, + n_threads = Inf, + verbose = FALSE, + progress = FALSE) { checkmate::assert_class(r5r_core, "jobjRef") @@ -93,4 +114,4 @@ fareto_debug <- function(r5r_core, ) return(result) -} \ No newline at end of file +} diff --git a/r-package/man/fareto_debug.Rd b/r-package/man/fareto_debug.Rd new file mode 100644 index 00000000..6c311f6f --- /dev/null +++ b/r-package/man/fareto_debug.Rd @@ -0,0 +1,157 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/fareto_debug.R +\name{fareto_debug} +\alias{fareto_debug} +\title{Output Fareto-format JSON for visualization with Fareto} +\usage{ +fareto_debug( + r5r_core, + origins, + destinations, + mode = c("WALK", "TRANSIT"), + mode_egress = "WALK", + departure_datetime = Sys.time(), + time_window = 10L, + percentiles = 50L, + max_walk_time = Inf, + max_bike_time = Inf, + max_car_time = Inf, + max_trip_duration = 120L, + fare_structure = NULL, + walk_speed = 3.6, + bike_speed = 12, + max_rides = 3, + max_lts = 2, + n_threads = Inf, + verbose = FALSE, + progress = FALSE +) +} +\arguments{ +\item{r5r_core}{An object to connect with the R5 routing engine, created with +\code{\link[=setup_r5]{setup_r5()}}.} + +\item{origins, destinations}{Either a \verb{POINT sf} object with WGS84 CRS, or a +\code{data.frame} containing the columns \code{id}, \code{lon} and \code{lat}.} + +\item{mode}{A character vector. The transport modes allowed for access, +transfer and vehicle legs of the trips. Defaults to \code{WALK}. Please see +details for other options.} + +\item{mode_egress}{A character vector. The transport mode used after egress +from the last public transport. It can be either \code{WALK}, \code{BICYCLE} or +\code{CAR}. Defaults to \code{WALK}. Ignored when public transport is not used.} + +\item{departure_datetime}{A POSIXct object. Please note that the departure +time only influences public transport legs. When working with public +transport networks, please check the \code{calendar.txt} within your GTFS feeds +for valid dates. Please see details for further information on how +datetimes are parsed.} + +\item{time_window}{An integer. The time window in minutes for which \code{r5r} +will calculate multiple travel time matrices departing each minute. +Defaults to 10 minutes. By default, the function returns the result based +on median travel times, but the user can set the \code{percentiles} parameter to +extract more results. Please read the time window vignette for more details +on its usage \code{vignette("time_window", package = "r5r")}} + +\item{percentiles}{An integer vector (max length of 5). Specifies the +percentile to use when returning travel time estimates within the given +time window. Please note that this parameter is applied to the travel time +estimates only (e.g. if the 25th percentile is specified, and the output +between A and B is 15 minutes and 10 dollars, 25\% of all trips cheaper +than 10 dollars taken between these points are shorter than 15 minutes). +Defaults to 50, returning the median travel time. If a vector with length +bigger than 1 is passed, the output contains an additional column that +specifies the percentile of each travel time and monetary cost +combination. Due to upstream restrictions, only 5 percentiles can be +specified at a time. For more details, please see R5 documentation at +\url{https://docs.conveyal.com/analysis/methodology#accounting-for-variability}.} + +\item{max_walk_time}{An integer. The maximum walking time (in minutes) to +access and egress the transit network, to make transfers within the network +or to complete walk-only trips. Defaults to no restrictions (numeric value +of \code{Inf}), as long as \code{max_trip_duration} is respected. When routing +transit trips, the max time is considered separately for each leg (e.g. if +you set \code{max_walk_time} to 15, you could get trips with an up to 15 minutes +walk leg to reach transit and another up to 15 minutes walk leg to reach +the destination after leaving transit. In walk-only trips, whenever +\code{max_walk_time} differs from \code{max_trip_duration}, the lowest value is +considered.} + +\item{max_bike_time}{An integer. The maximum cycling time (in minutes) to +access and egress the transit network, to make transfers within the network +or to complete bicycle-only trips. Defaults to no restrictions (numeric +value of \code{Inf}), as long as \code{max_trip_duration} is respected. When routing +transit trips, the max time is considered separately for each leg (e.g. if +you set \code{max_bike_time} to 15, you could get trips with an up to 15 minutes +cycle leg to reach transit and another up to 15 minutes cycle leg to reach +the destination after leaving transit. In bicycle-only trips, whenever +\code{max_bike_time} differs from \code{max_trip_duration}, the lowest value is +considered.} + +\item{max_car_time}{An integer. The maximum driving time (in minutes) to +access and egress the transit network. Defaults to no restrictions, as long +as \code{max_trip_duration} is respected. The max time is considered separately +for each leg (e.g. if you set \code{max_car_time} to 15 minutes, you could +potentially drive up to 15 minutes to reach transit, and up to \emph{another} 15 +minutes to reach the destination after leaving transit). Defaults to \code{Inf}, +no limit.} + +\item{max_trip_duration}{An integer. The maximum trip duration in minutes. +Defaults to 120 minutes (2 hours).} + +\item{fare_structure}{A fare structure object, following the convention +set in \code{\link[=setup_fare_structure]{setup_fare_structure()}}. This object describes how transit fares +should be calculated. Please see the fare structure vignette to +understand how this object is structured: +\code{vignette("fare_structure", package = "r5r")}.} + +\item{walk_speed}{A numeric. Average walk speed in km/h. Defaults to 3.6 +km/h.} + +\item{bike_speed}{A numeric. Average cycling speed in km/h. Defaults to 12 +km/h.} + +\item{max_rides}{An integer. The maximum number of public transport rides +allowed in the same trip. Defaults to 3.} + +\item{max_lts}{An integer between 1 and 4. The maximum level of traffic +stress that cyclists will tolerate. A value of 1 means cyclists will only +travel through the quietest streets, while a value of 4 indicates cyclists +can travel through any road. Defaults to 2. Please see details for more +information.} + +\item{n_threads}{An integer. The number of threads to use when running the +router in parallel. Defaults to use all available threads (Inf).} + +\item{verbose}{A logical. Whether to show \code{R5} informative messages when +running the function. Defaults to \code{FALSE} (please note that in such case +\code{R5} error messages are still shown). Setting \code{verbose} to \code{TRUE} shows +detailed output, which can be useful for debugging issues not caught by +\code{r5r}.} + +\item{progress}{A logical. Whether to show a progress counter when running +the router. Defaults to \code{FALSE}. Only works when \code{verbose} is set to +\code{FALSE}, so the progress counter does not interfere with \code{R5}'s output +messages. Setting \code{progress} to \code{TRUE} may impose a small penalty for +computation efficiency, because the progress counter must be synchronized +among all active threads.} + +\item{output_dir}{Either \code{NULL} or a path to an existing directory. When not +\code{NULL} (the default), the function will write one \code{.csv} file with the +results for each origin in the specified directory. In such case, the +function returns the path specified in this parameter. This parameter is +particularly useful when running on memory-constrained settings because +writing the results directly to disk prevents \code{r5r} from loading them to +RAM memory.} +} +\value{ +A JSON-formatted string. +} +\description{ +This is primarily intended for debugging the fare system code. Fareto is an +external tool that provides visualization for R5's McRAPTOR fare calculator. +To use this, run \code{fareto_debug(...)} like you would run \code{pareto_frontier(...)}. +Use \href{https://github.com/mattwigway/rfareto}{rfareto} to visualize the results. +}