% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/arrival_travel_time_matrix.R
\name{arrival_travel_time_matrix}
\alias{arrival_travel_time_matrix}
\title{Calculate travel time matrix between origin destination pairs considering a
time of arrival}
\usage{
arrival_travel_time_matrix(
  r5r_network,
  r5r_core = deprecated(),
  origins,
  destinations,
  mode = "WALK",
  mode_egress = "WALK",
  arrival_datetime = Sys.time(),
  breakdown = FALSE,
  max_walk_time = Inf,
  max_bike_time = Inf,
  max_car_time = Inf,
  max_trip_duration = 120L,
  walk_speed = 3.6,
  bike_speed = 12,
  max_rides = 3,
  max_lts = 2,
  new_carspeeds = NULL,
  carspeed_scale = 1,
  new_lts = NULL,
  draws_per_minute = 5L,
  n_threads = Inf,
  verbose = FALSE,
  progress = FALSE,
  output_dir = NULL
)
}
\arguments{
\item{r5r_network}{A routable transport network created with \code{\link[=build_network]{build_network()}}.}

\item{r5r_core}{The \code{r5r_core} argument is deprecated as of r5r v2.3.0.
Please use the \code{r5r_network} argument instead.}

\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{arrival_datetime}{A POSIXct object.}

\item{breakdown}{A logical. Whether to include detailed information about
each trip in the output. If \code{FALSE} (the default), the output lists the
total time between each origin-destination pair and the routes used to
complete the trip for each minute of the specified time window. If \code{TRUE},
the output includes the total access, waiting, in-vehicle and transfer
time of each trip. Please note that setting this parameter to \code{TRUE} makes
the function significantly slower.}

\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{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{new_carspeeds}{A \code{data.frame} specifying the new car speed for each OSM
edge id. This table must contain columns \code{osm_id}, \code{max_speed}
and \code{speed_type}. The \code{"speed_type"} column is of class character
and it indicates whether the values in \code{"max_speed"} should be
interpreted as percentages of original speeds (\code{"scale"}) or as absolute
speeds (\code{"km/h"}). Alternatively, the \code{new_carspeeds} parameter can
receive an \verb{sf data.frame} with POLYGON geometry that indicates the new
car speed for all the roads that fall within each polygon. In this case,
the table must contain the columns \code{poly_id} with a unique id for
each polygon, \code{scale} with the new speed scaling factors and
\code{priority}, which is a number ranking which polygon should be
considered in case of overlapping polygons. See more into in the
\verb{link to congestion vignette}.}

\item{carspeed_scale}{Numeric. The default car speed to use for road segments
not specified in \code{new_carspeeds}. By default, it is \code{NULL} and the speeds
of the unlisted roads are kept unchanged.}

\item{new_lts}{A \code{data.frame} specifying the new LTS levels for each OSM edge
id. The table must contain columns \code{osm_id} and \code{lts}.
Alternatively, the \code{new_lts} parameter can receive an \verb{sf data.frame}
with LINESTRING geometry. R5 will then find the nearest road for each
LINESTRING and update its LTS value accordingly.}

\item{draws_per_minute}{An integer. The number of Monte Carlo draws to
perform per time window minute when calculating travel time matrices and
when estimating accessibility. Defaults to 5. This would mean 300 draws in
a 60-minute time window, for example. This parameter only affects the
results when the GTFS feeds contain a \code{frequencies.txt} table. If the GTFS
feed does not have a frequency table, r5r still allows for multiple runs
over the set \code{time_window} but in a deterministic way.}

\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 \code{data.table} with travel time estimates (in minutes) and the
routes used in each trip between origin and destination pairs, for each
minute of the specified time window. Each set of origin, destination and
departure minute can appear up to N times, where N is the number of Monte
Carlo draws specified in the function arguments (please note that this
only applies when the GTFS feeds that describe the transit network include
a frequencies table, otherwise only a single draw is performed). A pair is
completely absent from the final output if no trips could be completed in
any of the minutes of the time window. If for a single pair trips could be
completed in some of the minutes of the time window, but not for all of
them, the minutes in which trips couldn't be completed will have \code{NA}
travel time and routes used. If \code{output_dir} is not \code{NULL}, the function
returns the path specified in that parameter, in which the \code{.csv} files
containing the results are saved.
}
\description{
Computation of travel time estimates between one or multiple origin
destination pairs considering a time of arrival. This function considers a
time of arrival set by the user. The function returns the travel time of the
trip with the latest departure time that arrives before the arrival time set
by the user. If you want to calculate travel times considering a departure
time, have a' look at the \code{\link[=travel_time_matrix]{travel_time_matrix()}} function. This function is a
wrapper around \code{\link[=expanded_travel_time_matrix]{expanded_travel_time_matrix()}}. On one hand, this means this
the output of this function has more columns (more info) compared the output
of \code{\link[=travel_time_matrix]{travel_time_matrix()}}. On the other hand, this function can be very memory
intensive if the user allows for really long max trip duration.
}
\section{Transport modes}{


\code{R5} allows for multiple combinations of transport modes. The options
include:
\itemize{
\item \strong{Transit modes:} \code{TRAM}, \code{SUBWAY}, \code{RAIL}, \code{BUS}, \code{FERRY}, \code{CABLE_CAR},
\code{GONDOLA}, \code{FUNICULAR}. The option \code{TRANSIT} automatically considers all
public transport modes available.
\item \strong{Non transit modes:} \code{WALK}, \code{BICYCLE}, \code{CAR}, \code{BICYCLE_RENT},
\code{CAR_PARK}.
}
}

\section{Level of Traffic Stress (LTS)}{


When cycling is enabled in \code{R5} (by passing the value \code{BIKE} to either
\code{mode} or \code{mode_egress}), setting \code{max_lts} will allow cycling only on
streets with a given level of danger/stress. Setting \code{max_lts} to 1, for
example, will allow cycling only on separated bicycle infrastructure or
low-traffic streets and routing will revert to walking when traversing any
links with LTS exceeding 1. Setting \code{max_lts} to 3 will allow cycling on
links with LTS 1, 2 or 3. Routing also reverts to walking if the street
segment is tagged as non-bikable in OSM (e.g. a staircase), independently of
the specified max LTS.

The default methodology for assigning LTS values to network edges is based
on commonly tagged attributes of OSM ways. See more info about LTS in the
original documentation of R5 from Conveyal at
\url{https://docs.conveyal.com/learn-more/traffic-stress}. In summary:
\itemize{
\item \strong{LTS 1}: Tolerable for children. This includes low-speed, low-volume
streets, as well as those with separated bicycle facilities (such as
parking-protected lanes or cycle tracks).
\item \strong{LTS 2}: Tolerable for the mainstream adult population. This includes
streets where cyclists have dedicated lanes and only have to interact with
traffic at formal crossing.
\item \strong{LTS 3}: Tolerable for "enthused and confident" cyclists. This includes
streets which may involve close proximity to moderate- or high-speed
vehicular traffic.
\item \strong{LTS 4}: Tolerable only for "strong and fearless" cyclists. This
includes streets where cyclists are required to mix with moderate- to
high-speed vehicular traffic.
}

For advanced users, you can provide custom LTS values by adding a tag \verb{<key = "lts">} to the \code{osm.pbf} file.
}

\section{Datetime parsing}{


\code{r5r} ignores the timezone attribute of datetime objects when parsing dates
and times, using the study area's timezone instead. For example, let's say
you are running some calculations using Rio de Janeiro, Brazil, as your study
area. The datetime \code{as.POSIXct("13-05-2019 14:00:00", format = "\%d-\%m-\%Y \%H:\%M:\%S")} will be parsed as May 13th, 2019, 14:00h in
Rio's local time, as expected. But \code{as.POSIXct("13-05-2019 14:00:00", format = "\%d-\%m-\%Y \%H:\%M:\%S", tz = "Europe/Paris")} will also be parsed as
the exact same date and time in Rio's local time, perhaps surprisingly,
ignoring the timezone attribute.
}

\section{Routing algorithm}{


The \code{\link[=travel_time_matrix]{travel_time_matrix()}}, \code{\link[=expanded_travel_time_matrix]{expanded_travel_time_matrix()}},
\code{\link[=arrival_travel_time_matrix]{arrival_travel_time_matrix()}}  and \code{\link[=accessibility]{accessibility()}} functions use an
\code{R5}-specific extension to the RAPTOR routing algorithm (see Conway et al.,
2017). This RAPTOR extension uses a systematic sample of one departure per
minute over the time window set by the user in the 'time_window' parameter.
A detailed description of base RAPTOR can be found in Delling et al (2015).
However, whenever the user includes transit fares inputs to these functions,
they automatically switch to use an \code{R5}-specific extension to the McRAPTOR
routing algorithm.
\itemize{
\item Conway, M. W., Byrd, A., & van der Linden, M. (2017). Evidence-based
transit and land use sketch planning using interactive accessibility methods
on combined schedule and headway-based networks. Transportation Research
Record, 2653(1), 45-53. \doi{10.3141/2653-06}
\item Delling, D., Pajor, T., & Werneck, R. F. (2015). Round-based public
transit routing. Transportation Science, 49(3), 591-604.
\doi{10.1287/trsc.2014.0534}
}
}

\examples{
\dontshow{if (identical(tolower(Sys.getenv("NOT_CRAN")), "true")) withAutoprint(\{ # examplesIf}
library(r5r)

# build transport network
data_path <- system.file("extdata/poa", package = "r5r")
r5r_network <- build_network(data_path )

# load origin/destination points
points <- read.csv(file.path(data_path, "poa_points_of_interest.csv"))

arrival_datetime <- as.POSIXct(
  "13-05-2019 14:00:00",
  format = "\%d-\%m-\%Y \%H:\%M:\%S"
)

# by default only returns the total time between each pair in each minute of
# the specified time window
arrival_ttm <- arrival_travel_time_matrix(
  r5r_network,
  origins = points,
  destinations = points,
  mode = c("WALK", "TRANSIT"),
  arrival_datetime = arrival_datetime,
  max_trip_duration = 60
)

head(arrival_ttm)

# when breakdown = TRUE the output contains much more information
arrival_ttm2 <- arrival_travel_time_matrix(
  r5r_network,
  origins = points,
  destinations = points,
  mode = c("WALK", "TRANSIT"),
  arrival_datetime = arrival_datetime,
  max_trip_duration = 60,
  breakdown = TRUE
)

head(arrival_ttm2)

stop_r5(r5r_network)
\dontshow{\}) # examplesIf}
}
\seealso{
Other routing: 
\code{\link{detailed_itineraries}()},
\code{\link{expanded_travel_time_matrix}()},
\code{\link{pareto_frontier}()},
\code{\link{travel_time_matrix}()}
}
\concept{routing}
