documentation of level of stress LTS

r-package/R/travel_time_matrix.R

@@ -43,7 +43,8 @@
 #' @param max_lts  numeric (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.
+#'                 indicates cyclists can travel through any road. Deafaults to 2.
+#'                 See details for more information.
 #' @param n_threads numeric. The number of threads to use in parallel computing.
 #'                  Defaults to use all available threads (Inf).
 #' @param verbose logical. TRUE to show detailed output messages (the default)
@@ -54,8 +55,9 @@
 #' that were beyond the maximum travel time, and/or origins that were far from
 #' the street network are not returned in the data.table.
 #'
-#' @details R5 allows for multiple combinations of transport modes. The options
-#'          include:
+#' @details
+#'  # Transpor modes:
+#'  R5 allows for multiple combinations of transport modes. The options include:
 #'
 #'   ## Transit modes
 #'   TRAM, SUBWAY, RAIL, BUS, FERRY, CABLE_CAR, GONDOLA, FUNICULAR. The option
@@ -64,6 +66,28 @@
 #'   ## Non transit modes
 #'   WALK, BICYCLE, CAR, BICYCLE_RENT, CAR_PARK
 #'
+#' # max_lts, Maximum Level of Traffic Stress:
+#' When cycling is enabled in R5, setting `max_lts` will allow cycling only on
+#' streets with a given level of danger/stress. Setting `max_lts` to 1, for example,
+#' will allow cycling only on separated bicycle infrastructure or low-traffic
+#' streets; routing will revert to walking when traversing any links with LTS
+#' exceeding 1. Setting `max_lts` to 3 will allow cycling on links with LTS 1, 2,
+#' or 3.
+#'
+#' The default methodology for assigning LTS values to network edges is based on
+#' commonly tagged attributes of OSM ways. See more info about LTS at
+#' \url{https://docs.conveyal.com/learn-more/traffic-stress}. In summary:
+#'
+#'- **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).
+#'- **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.
+#'- **LTS 3**: Tolerable for “enthused and confident” cyclists. This includes streets
+#'  which may involve close proximity to moderate- or high-speed vehicular traffic.
+#'- **LTS 4**: Tolerable for only “strong and fearless” cyclists. This includes streets
+#'  where cyclists are required to mix with moderate- to high-speed vehicular traffic.
 #'
 #' # Routing algorithm:
 #' The travel_time_matrix function uses an R5-specific extension to the RAPTOR