weight_streetnet: Weight a street network according to a specified weighting...
In dodgr: Distances on Directed Graphs

weight_streetnet

R Documentation

Weight a street network according to a specified weighting profile.

Description

Weight (or re-weight) an 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 cusstomized version dervied 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
)

## Default S3 method:
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 class '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 class '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 class '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
)

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.

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().

Note

Names for the wt_profile parameter are taken from weighting_profiles, which is a list including a data.frame also called weighting_profiles of weights for different modes of transport. Values for wt_profile are taken from current modes included there, which are "bicycle", "foot", "goods", "hgv", "horse", "moped", "motorcar", "motorcycle", "psv", and "wheelchair". Railway routing can be implemented with the separate function weight_railway. Alternatively, the entire weighting_profile structures can be written to a local .json-formatted file with write_dodgr_wt_profile, the values edited as desired, and the name of this file passed as the wt_profile_file parameter.

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 sc ("silicate") format, generated with 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 dodgr_streetnet_sc, and so may be added to the keep_cols argument, include:

"access"
"bicycle"
"foot"
"highway"
"motorcar"
"motor_vehicle"
"restriction"
"toll"
"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 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 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.

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 weighted streetnet.

If the resultant graph is to be contracted via dodgr_contract_graph, and if the columns of the graph have been, or will be, modified, then automatic caching must be switched off with dodgr_cache_off. If not, the dodgr_contract_graph function will return the automatically cached version, which is the contracted version of the full graph prior to any modification of columns.

Examples

# 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.
## Not run: 
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
)

## End(Not run)

dodgr documentation built on Sept. 11, 2024, 7:52 p.m.