% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/weight-streetnet.R
\name{weight_streetnet}
\alias{weight_streetnet}
\alias{weight_streetnet.default}
\alias{weight_streetnet.sf}
\alias{weight_streetnet.sc}
\title{weight_streetnet}
\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
)

\method{weight_streetnet}{default}(
  x,
  wt_profile = "bicycle",
  wt_profile_file = NULL,
  turn_penalty = FALSE,
  type_col = "highway",
  id_col = "osm_id",
  keep_cols = NULL,
  left_side = FALSE
)

\method{weight_streetnet}{sf}(
  x,
  wt_profile = "bicycle",
  wt_profile_file = NULL,
  turn_penalty = FALSE,
  type_col = "highway",
  id_col = "osm_id",
  keep_cols = NULL,
  left_side = FALSE
)

\method{weight_streetnet}{sc}(
  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{
\item{x}{A street network represented either as \code{sf} \code{LINESTRING}
objects, typically extracted with \link{dodgr_streetnet}, or as an \code{SC}
(\code{silicate}) object typically extracted with the \link{dodgr_streetnet_sc}.}

\item{wt_profile}{Name of weighting profile, or \code{data.frame} specifying
custom values (see Details)}

\item{wt_profile_file}{Name of locally-stored, \code{.json}-formatted version of
\code{dodgr::weighting_profiles}, created with \link{write_dodgr_wt_profile}, and
modified as desired.}

\item{turn_penalty}{Including time penalty on edges for turning across
oncoming traffic at intersections (see Note).}

\item{type_col}{Specify column of the \code{sf} \code{data.frame} object
which designates different types of highways to be used for weighting
(default works with \code{osmdata} objects).}

\item{id_col}{For \code{sf}-formatted data only: Specify column of the code{sf}
\code{data.frame} object which provides unique identifiers for each highway
(default works with \code{osmdata} objects).}

\item{keep_cols}{Vectors of columns from \code{x} to be kept in the resultant
\code{dodgr} network; vector can be either names or indices of desired columns
(see notes).}

\item{left_side}{Does traffic travel on the left side of the road (\code{TRUE}) or
the right side (\code{FALSE})? - only has effect on turn angle calculations for
edge times.}
}
\value{
A \code{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 \pkg{sf}-formatted street networks are only
approximate, and do not take into account traffic lights, turn angles, or
elevation changes. Times for \pkg{sc}-formatted street networks take into
account all of these factors, with elevation changes automatically taken into
account for networks generated with the \pkg{osmdata} function
\code{osm_elevation()}.
}
\description{
Weight (or re-weight) an \pkg{sf} or \code{SC} (\code{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.
}
\note{
Names for the \code{wt_profile} parameter are taken from
\link{weighting_profiles}, which is a list including a \code{data.frame} also
called \code{weighting_profiles} of weights for different modes of transport.
Values for \code{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 \link{weight_railway}. Alternatively, the entire
\code{weighting_profile} structures can be written to a local \code{.json}-formatted
file with \link{write_dodgr_wt_profile}, the values edited as desired, and
the name of this file passed as the \code{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 \code{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 \code{dodgr} network with the \code{keep_cols} argument. For example,
restrictions on access are generally specified by specifying a value for the
key of "access". Include "access" in \code{keep_cols} will ensure these values are
retained in the \code{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 \code{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 \code{turn_penalty = TRUE}. Setting \code{turn_penalty = TRUE} will
honour turn restrictions specified in Open Street Map (unless the "penalties"
table of \link{weighting_profiles} has \code{restrictions = FALSE} for a specified
\code{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 \code{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
\link{dodgr_contract_graph}, \strong{and} if the columns of the graph have been,
or will be, modified, then automatic caching must be switched off with
\link{dodgr_cache_off}. If not, the \link{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.
\dontrun{
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
)
}
}
\seealso{
\link{write_dodgr_wt_profile}, \link{dodgr_times}

Other extraction: 
\code{\link{dodgr_streetnet_sc}()},
\code{\link{dodgr_streetnet}()},
\code{\link{weight_railway}()}

Other extraction: 
\code{\link{dodgr_streetnet_sc}()},
\code{\link{dodgr_streetnet}()},
\code{\link{weight_railway}()}

Other extraction: 
\code{\link{dodgr_streetnet_sc}()},
\code{\link{dodgr_streetnet}()},
\code{\link{weight_railway}()}

Other extraction: 
\code{\link{dodgr_streetnet_sc}()},
\code{\link{dodgr_streetnet}()},
\code{\link{weight_railway}()}
}
\concept{extraction}
