weight_streetnet: Weight a street network according to a specified weighting profile.

Description

Weight (or re-weight) an sf or 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.

Usage

weight_streetnet(
  x,
  wt_profile = "bicycle",
  wt_profile_file = NULL,
  turn_penalty = FALSE,
  type_col = "highway",
  id_col = "osm_id",
  keep_cols = NULL,
  left_side = FALSE
)
# S3 method for default
weight_streetnet(
  x,
  wt_profile = "bicycle",
  wt_profile_file = NULL,
  turn_penalty = FALSE,
  type_col = "highway",
  id_col = "osm_id",
  keep_cols = NULL,
  left_side = FALSE
)
# S3 method for sf
weight_streetnet(
  x,
  wt_profile = "bicycle",
  wt_profile_file = NULL,
  turn_penalty = FALSE,
  type_col = "highway",
  id_col = "osm_id",
  keep_cols = NULL,
  left_side = FALSE
)
# S3 method for sc
weight_streetnet(
  x,
  wt_profile = "bicycle",
  wt_profile_file = NULL,
  turn_penalty = FALSE,
  type_col = "highway",
  id_col = "osm_id",
  keep_cols = NULL,
  left_side = FALSE
)
# S3 method for SC
weight_streetnet(
  x,
  wt_profile = "bicycle",
  wt_profile_file = NULL,
  turn_penalty = FALSE,
  type_col = "highway",
  id_col = "osm_id",
  keep_cols = NULL,
  left_side = FALSE
)

Value

A data.frame of edges representing the street network, with distances in metres and times in seconds, along with a column of graph component numbers. Times for sf-formatted street networks are only approximate, and do not take into account traffic lights, turn angles, or elevation changes. Times for sc-formatted street networks take into account all of these factors, with elevation changes automatically taken into account for networks generated with the osmdata function osm_elevation().

Arguments

x: A street network represented either as sf LINESTRING objects, typically extracted with dodgr_streetnet, or as an SC (silicate) object typically extracted with the dodgr_streetnet_sc.
wt_profile: Name of weighting profile, or data.frame specifying custom values (see Details)
wt_profile_file: Name of locally-stored, .json-formatted version of dodgr::weighting_profiles, created with write_dodgr_wt_profile, and modified as desired.
turn_penalty: Including time penalty on edges for turning across oncoming traffic at intersections (see Note).
type_col: Specify column of the sf data.frame object which designates different types of highways to be used for weighting (default works with osmdata objects).
id_col: For sf-formatted data only: Specify column of the sf data.frame object which provides unique identifiers for each highway (default works with osmdata objects).
keep_cols: Vectors of columns from x to be kept in the resultant dodgr network; vector can be either names, regex-patterns, or indices of desired columns (see notes).
left_side: Does traffic travel on the left side of the road (TRUE) or the right side (FALSE)? - only has effect on turn angle calculations for edge times.

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 weighting_profiles by the "way" column in the "weighting_profiles" item. These include:

"bridleway"
"cycleway"
"ferry"
"footway"
"living_street"
"motorway"
"motorway_link
"path"
"pedestrian"
"primary"
"primary_link"
"residential"
"secondary"
"secondary_link
"service"
"steps"
"tertiary"
"tertiary_link"
"track"
"trunk"
"trunk_link
"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:

"highway"
"junction"
"lanes"
"maxspeed"
"oneway", including with all alternative forms such as "oneway.bicycle"
"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 sc ("silicate") format, generated with dodgr_streetnet_sc (and possibly enhanced through applying the 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 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 dodgr_save_streetnet and 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.

Examples

Run this code

# hampi is included with package as an 'osmdata' sf-formatted street network
net <- weight_streetnet (hampi)
class (net) # data.frame
dim (net) # 6096  11; 6096 streets
# os_roads_bristol is also included as an sf data.frame, but in a different
# format requiring identification of columns and specification of custom
# weighting scheme.
colnm <- "formOfWay"
wts <- data.frame (
    name = "custom",
    way = unique (os_roads_bristol [[colnm]]),
    value = c (0.1, 0.2, 0.8, 1)
)
net <- weight_streetnet (
    os_roads_bristol,
    wt_profile = wts,
    type_col = colnm, id_col = "identifier"
)
dim (net) # 406 11; 406 streets

# An example for a generic (non-OSM) highway, represented as the
# `routes_fast` object of the \pkg{stplanr} package, which is a
# SpatialLinesDataFrame.
if (FALSE) {
library (stplanr)
# merge all of the 'routes_fast' lines into a single network
r <- overline (routes_fast, attrib = "length", buff_dist = 1)
r <- sf::st_as_sf (r, crs = 4326)
# We need to specify both a `type` and `id` column for the
# \link{weight_streetnet} function.
r$type <- 1
r$id <- seq (nrow (r))
graph <- weight_streetnet (
    r,
    type_col = "type",
    id_col = "id",
    wt_profile = 1
)
}