dodgr_dists_categorical: Cumulative distances along different edge categories

In dodgr: Distances on Directed Graphs

Cumulative distances along different edge categories

Description

Cumulative distances along different edge categories

Usage

dodgr_dists_categorical(
  graph,
  from = NULL,
  to = NULL,
  proportions_only = FALSE,
  pairwise = FALSE,
  dlimit = NULL,
  heap = "BHeap",
  quiet = TRUE
)

Arguments

graph	data.frame or equivalent object representing the network graph which must have a column named "edge_type" which labels categories of edge types along which categorical distances are to be aggregated (see Note).
from	Vector or matrix of points from which route distances are to be calculated (see Notes)
to	Vector or matrix of points to which route distances are to be calculated (see Notes)
proportions_only	If FALSE, return distance matrices for full distances and for each edge category; if TRUE, return single vector of proportional distances, like the summary function applied to full results. See Note.
pairwise	If TRUE, calculate distances only between the ordered pairs of from and to. In this case, neither the proportions_only nor dlimit parameters have any effect, and the result is a single matrix with one row for each pair of from-to points, and one column for each category.
dlimit	If no value to to is given, distances are aggregated from each from point out to the specified distance limit (in the same units as the edge distances of the input graph). dlimit only has any effect if to is not specified, in which case the proportions_only argument has no effect.
heap	Type of heap to use in priority queue. Options include Fibonacci Heap (default; FHeap), Binary Heap (BHeap), ⁠Trinomial Heap (⁠TriHeap⁠), Extended Trinomial Heap (⁠TriHeapExt⁠, and 2-3 Heap (⁠Heap23').
quiet	If FALSE, display progress messages on screen.

Value

If to is specified, a list of distance matrices of equal dimensions (length(from), length(to)), the first of which ("distance") holds the final distances, while the rest are one matrix for each unique value of "edge_type", holding the distances traversed along those types of edges only. Otherwise, a single matrix of total distances along all ways from each point out to the specified value of dlimit, along with distances along each of the different kinds of ways specified in the "edge_type" column of the input graph.

Note

The "edge_type" column in the graph can contain any kind of discrete or categorical values, although integer values of 0 are not permissible. NA values are ignored. The function requires one full distance matrix to be stored for each category of "edge_type" (unless proportions_only = TRUE). It is wise to keep numbers of discrete types as low as possible, especially for large distance matrices.

Setting the proportions_only flag to TRUE may be advantageous for large jobs, because this avoids construction of the full matrices. This may speed up calculations, but perhaps more importantly it may make possible calculations which would otherwise require distance matrices too large to be directly stored.

Calculations are not able to be interrupted (for example, by Ctrl-C), and can only be stopped by killing the R process.

See Also

Other distances: dodgr_distances(), dodgr_dists_nearest(), dodgr_dists(), dodgr_flows_aggregate(), dodgr_flows_disperse(), dodgr_flows_si(), dodgr_isochrones(), dodgr_isodists(), dodgr_isoverts(), dodgr_paths(), dodgr_times()

Examples

# Prepare a graph for categorical routing by including an "edge_type" column
graph <- weight_streetnet (hampi, wt_profile = "foot")
graph <- graph [graph$component == 1, ]
graph$edge_type <- graph$highway
# Define start and end points for categorical distances; using all vertices
# here.
length (unique (graph$edge_type)) # Number of categories
v <- dodgr_vertices (graph)
from <- to <- v$id [1:100]
d <- dodgr_dists_categorical (graph, from, to)
class (d)
length (d)
sapply (d, dim)
# 9 distance matrices, all of same dimensions, first of which is standard
# distance matrix
s <- summary (d) # print summary as proportions along each "edge_type"
# or directly calculate proportions only
dodgr_dists_categorical (graph, from, to,
    proportions_only = TRUE
)

# Pairwise distances return single matrix with number of rows equal to 'from'
# / 'to', and number of columns equal to number of edge types plus one for
# total distances.
d <- dodgr_dists_categorical (graph, from, to, pairwise = TRUE)
class (d)
dim (d)

# The 'dlimit' parameter can be used to calculate total distances along each
# category of edges from a set of points out to specified threshold:
dlimit <- 2000 # in metres
d <- dodgr_dists_categorical (graph, from, dlimit = dlimit)
dim (d) # length(from), length(unique(edge_type)) + 1

dodgr documentation built on June 7, 2023, 5:44 p.m.