update weightstreetnet docs to fix #245

R/weight-streetnet.R

@@ -1,9 +1,99 @@
 #' Weight a street network according to a specified weighting profile.
 #'
-#' Weight (or re-weight) an \pkg{sf} or `SC` (`silicate`)-formatted OSM street
-#' network according to a named profile, selected from (foot, horse, wheelchair,
-#' bicycle, moped, motorcycle, motorcar, goods, hgv, psv), or a customized
-#' version derived from those.
+#' Weight (or re-weight) an \pkg{sf} or \pkg{silicate} *("SC") formatted OSM
+#' street network according to a named profile, selected from (foot, horse,
+#' wheelchair, bicycle, moped, motorcycle, motorcar, goods, hgv, psv), or a
+#' customized version derived from those.
+#'
+#' @details The structure of networks generated by this function is dependent
+#' on many aspects of the input network, and in particular on specific
+#' key-value pairs defined in the underlying OpenStreetMap (OSM) data.
+#'
+#' Many key-value pairs influence the resultant network through being used in
+#' specified weighting profiles. Keys used in weighting profiles are always
+#' kept in the weighted networks, and are specified in
+#' \link{weighting_profiles} by the "way" column in the "weighting_profiles"
+#' item. These include:
+#'
+#' \itemize{
+#' \item "bridleway"
+#' \item "cycleway"
+#' \item "ferry"
+#' \item "footway"
+#' \item "living_street"
+#' \item "motorway"
+#' \item "motorway_link
+#' \item "path"
+#' \item "pedestrian"
+#' \item "primary"
+#' \item "primary_link"
+#' \item "residential"
+#' \item "secondary"
+#' \item "secondary_link
+#' \item "service"
+#' \item "steps"
+#' \item "tertiary"
+#' \item "tertiary_link"
+#' \item "track"
+#' \item "trunk"
+#' \item "trunk_link
+#' \item "unclassified"
+#' }
+#'
+#' Some of these are only optionally kept, dependent on the weighting profile
+#' chosen. For example, "cycleway" keys are only kept for bicycle weighting.
+#' Most of the specified keys also include all possible variations on those
+#' keys. For the example of "cycleway" again, key-value pairs are also kept for
+#' "cycleway:left" and "cycleway:right".
+#'
+#' The following additional keys are also automatically retained in weighted
+#' networks:
+#'
+#' \itemize{
+#' \item "highway"
+#' \item "junction"
+#' \item "lanes"
+#' \item "maxspeed"
+#' \item "oneway", including with all alternative forms such as "oneway.bicycle"
+#' \item "surface"
+#' }
+#'
+#' Realistic routing including factors such as access restrictions, turn
+#' penalties, and effects of incline, can only be implemented when the objects
+#' passed to `weight_streetnet` are of \pkg{sc} ("silicate") format, generated
+#' with \link{dodgr_streetnet_sc} (and possibly enhanced through applying the
+#' \pkg{osmdata} function `osm_elevation()`). Restrictions applied to ways (in
+#' OSM terminology) may be controlled by ensuring specific columns are retained
+#' in the `dodgr` network with the `keep_cols` argument. For example,
+#' restrictions on access are generally specified by specifying a value for the
+#' key of "access". Include "access" in `keep_cols` will ensure these values
+#' are retained in the `dodgr` version, from which ways with specified values
+#' can easily be removed or modified, as demonstrated in the examples.
+#'
+#' Restrictions and time-penalties on turns can be implemented by setting
+#' `turn_penalty = TRUE`, which will then honour turn restrictions specified in
+#' OSM (unless the "penalties" table of \link{weighting_profiles} has
+#' `restrictions = FALSE` for a specified `wt_profile`). Resultant graphs are
+#' fundamentally different from the default for distance-based routing. These
+#' graphs may be used directly in most 'dodgr' functions, but generally only if
+#' they have been created by calling this function in the same session, or if
+#' they have been saved and loaded with the \link{dodgr_save_streetnet} and
+#' \link{dodgr_load_streetnet} functions. (This is because the weighted
+#' streetnets also have accompanying data stored in a local temporary cache
+#' directory; attempting to pass a weighted street network without these
+#' accompanying cache files will generally error.)
+#'
+#' Some key-value pairs may also directly influence not just the value of the
+#' graph produced by this function, but also its size. Among these are "oneway"
+#' flags. Without these flags, each edge will be represented in *directed* form,
+#' and so as two rows of the graph: one for A -> B, and one for B -> A. If a
+#' way is tagged in OSM as "oneway" = "yes", and if oneway flags are respected
+#' for a chosen weighting profile (which, for example, they are generally not
+#' for pedestrian or "foot" weighting), then only one edge will be returned
+#' representing travel in the direction permitted within the OSM data. Thus
+#' weighting a network which includes "oneway" flags, and using a weighting
+#' profile which respects these, will generate a graph with fewer rows than a
+#' graph produced by ignoring those "oneway" flags.
 #'
 #' @param x A street network represented either as `sf` `LINESTRING`
 #' objects, typically extracted with \link{dodgr_streetnet}, or as an `SC`
@@ -48,47 +138,6 @@
 #' file with \link{write_dodgr_wt_profile}, the values edited as desired, and
 #' the name of this file passed as the `wt_profile_file` parameter.
 #'
-#' @note Realistic routing include factors such as access restrictions, turn
-#' penalties, and effects of incline, can only be implemented when the objects
-#' passed to `weight_streetnet` are of \pkg{sc} ("silicate") format, generated
-#' with \link{dodgr_streetnet_sc}. Restrictions applied to ways (in Open
-#' Streetmap Terminology) may be controlled by ensuring specific columns are
-#' retained in the `dodgr` network with the `keep_cols` argument. For example,
-#' restrictions on access are generally specified by specifying a value for the
-#' key of "access". Include "access" in `keep_cols` will ensure these values are
-#' retained in the `dodgr` version, from which ways with specified values can
-#' easily be removed or modified, as demonstrated in the examples.
-#'
-#' The additional Open Street Map (OSM) keys which can be used to specify
-#' restrictions are which are automatically extracted with
-#' \link{dodgr_streetnet_sc}, and so may be added to the `keep_cols` argument,
-#' include:
-#' \itemize{
-#' \item "access"
-#' \item "bicycle"
-#' \item "foot"
-#' \item "highway"
-#' \item "motorcar"
-#' \item "motor_vehicle"
-#' \item "restriction"
-#' \item "toll"
-#' \item "vehicle"
-#' }
-#'
-#' Restrictions and time-penalties on turns can be implemented from such
-#' objects by setting `turn_penalty = TRUE`. Setting `turn_penalty = TRUE` will
-#' honour turn restrictions specified in Open Street Map (unless the "penalties"
-#' table of \link{weighting_profiles} has `restrictions = FALSE` for a specified
-#' `wt_profile`). Resultant graphs are fundamentally different from the default
-#' for distance-based routing. These graphs may be used directly in the
-#' \link{dodgr_dists} function. Use in any other functions requires additional
-#' information obtained in a file in the temporary directory of the current R
-#' session with a name starting with "dodgr_junctions_", and including the
-#' value of `attr(graph, "hash")`. If graphs with turn penalties are to be used
-#' in subsequent R sessions, this "dodgr_junctions_" file will need to be moved
-#' to a more permanent storage location, and then replaced in the temporary
-#' directory of any subsequent R sessions.
-#'
 #' @note The resultant graph includes only those edges for which the given
 #' weighting profile specifies finite edge weights. Any edges of types not
 #' present in a given weighting profile are automatically removed from the