dodgr: dodgr_dists_categorical – R documentation

Pricing

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Get Started for Free

Documentation

dodgr

dodgr_dists_categorical

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,
  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.
`dlimit`	If `TRUE`, and 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). The `proportions_only` argument has no effect when `dlimit = TRUE`.
`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 dlimit = FALSE, 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. If dlimit = TRUE, a single matrix of total distances along all ways from each point, 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.