Wrapper around `distances`

to calculate costs of
pairwise shortest paths between points in a spatial network. It allows to
provide any set of geospatial point as `from`

and `to`

arguments.
If such a geospatial point is not equal to a node in the network, it will
be snapped to its nearest node before calculating costs.

- x
An object of class

`sfnetwork`

.- from
The (set of) geospatial point(s) from which the shortest paths will be calculated. Can be an object of class

`sf`

or`sfc`

. Alternatively it can be a numeric vector containing the indices of the nodes from which the shortest paths will be calculated, or a character vector containing the names of the nodes from which the shortest paths will be calculated. By default, all nodes in the network are included.- to
The (set of) geospatial point(s) to which the shortest paths will be calculated. Can be an object of class

`sf`

or`sfc`

. Alternatively it can be a numeric vector containing the indices of the nodes to which the shortest paths will be calculated, or a character vector containing the names of the nodes to which the shortest paths will be calculated. Duplicated values will be removed before calculating the cost matrix. By default, all nodes in the network are included.- weights
The edge weights to be used in the shortest path calculation. Can be a numeric vector giving edge weights, or a column name referring to an attribute column in the edges table containing those weights. If set to

`NULL`

, the values of a column named`weight`

in the edges table will be used automatically, as long as this column is present. If not, the geographic edge lengths will be calculated internally and used as weights. If set to`NA`

, no weights are used, even if the edges have a`weight`

column.- direction
The direction of travel. Defaults to

`'out'`

, meaning that the direction given by the network is followed and costs are calculated from the points given as argument`from`

. May be set to`'in'`

, meaning that the opposite direction is followed an costs are calculated towards the points given as argument`from`

. May also be set to`'all'`

, meaning that the network is considered to be undirected. This argument is ignored for undirected networks.- Inf_as_NaN
Should the cost values of unconnected nodes be stored as

`NaN`

instead of`Inf`

? Defaults to`FALSE`

.- ...
Arguments passed on to

`distances`

. Argument`mode`

is ignored. Use`direction`

instead.

An n times m numeric matrix where n is the length of the `from`

argument, and m is the length of the `to`

argument.

Spatial features provided to the `from`

and/or
`to`

argument don't necessarily have to be points. Internally, the
nearest node to each feature is found by calling
`st_nearest_feature`

, so any feature with a geometry type
that is accepted by that function can be provided as `from`

and/or
`to`

argument.

When directly providing integer node indices or character node names to the
`from`

and/or `to`

argument, keep the following in mind. A node
index should correspond to a row-number of the nodes table of the network.
A node name should correspond to a value of a column in the nodes table
named `name`

. This column should contain character values without
duplicates.

For more details on the wrapped function from `igraph`

see the `distances`

documentation page.

```
library(sf, quietly = TRUE)
library(tidygraph, quietly = TRUE)
# Create a network with edge lengths as weights.
# These weights will be used automatically in shortest paths calculation.
net = as_sfnetwork(roxel, directed = FALSE) %>%
st_transform(3035) %>%
activate("edges") %>%
mutate(weight = edge_length())
# Providing node indices.
st_network_cost(net, from = c(495, 121), to = c(495, 121))
#> Units: [m]
#> [,1] [,2]
#> [1,] 0.000 2094.555
#> [2,] 2094.555 0.000
# Providing nodes as spatial points.
# Points that don't equal a node will be snapped to their nearest node.
p1 = st_geometry(net, "nodes")[495] + st_sfc(st_point(c(50, -50)))
st_crs(p1) = st_crs(net)
p2 = st_geometry(net, "nodes")[121] + st_sfc(st_point(c(-10, 100)))
st_crs(p2) = st_crs(net)
st_network_cost(net, from = c(p1, p2), to = c(p1, p2))
#> Units: [m]
#> [,1] [,2]
#> [1,] 0.000 2094.555
#> [2,] 2094.555 0.000
# Using another column for weights.
net %>%
activate("edges") %>%
mutate(foo = runif(n(), min = 0, max = 1)) %>%
st_network_cost(c(p1, p2), c(p1, p2), weights = "foo")
#> [,1] [,2]
#> [1,] 0.00000 10.29983
#> [2,] 10.29983 0.00000
# Not providing any from or to points includes all nodes by default.
with_graph(net, graph_order()) # Our network has 701 nodes.
#> [1] 701
cost_matrix = st_network_cost(net)
dim(cost_matrix)
#> [1] 701 701
```