mc_comp: Compare least-cost paths produced by different cost functions

Description

Computes, for the same origin and destination(s), the least-cost paths produced by two or more cost functions, so that route choice and cost can be compared across cost models. One cost surface is built per function (this is unavoidable, since each function defines its own graph weights), but each is built once and all the remaining computation reuses it.

Usage

mc_comp(
  dtm,
  origin,
  destin,
  functs,
  move = 16,
  return.base = FALSE,
  time = "h",
  ...
)

Value

An object of class movecost_comp, a list with components

paths: sf lines for all functions, with funct, destination, cost, cost_unit, and length attributes;
paths.back: return paths (NULL unless return.base = TRUE);
cost.table: data frame summarising cost and length per function and destination;
origin, destin: the input locations (sf);
metadata used by the plot method.

Plot it at any time with plot() (see plot.movecost_comp); plot(x, type = "chart") compares the path length and the cost across functions, as boxplots of their distribution across destinations when three or more destinations are used (the add.chart output of movecost <= 2.x), or as bars otherwise.

Arguments

dtm: Digital Terrain Model (SpatRaster, RasterLayer, or file path), as in mc_surface.
origin: single origin location (sf points, SpatVector, or legacy SpatialPointsDataFrame).
destin: destination location(s) (same accepted classes).
functs: character vector of cost-function codes to compare (see mc_cost_functions), e.g. c("t", "ks", "hrz").
move: number of directions in which cells are connected (4, 8, or 16; default 16).
return.base: TRUE or FALSE (default): also compute the paths back to the origin for each cost function.
time: unit for time-based cost functions: "h" (hours, default) or "m" (minutes).
...: further parameters passed to mc_surface (N, W, L, V, sl.crit, barrier, field, cogn.slp, topo.dist).

Details

Note that costs produced by functions of different families (walking time, energy, abstract) are expressed in different units and are comparable in terms of route geometry, not of cost magnitude; the cost table returned reports the unit alongside each value.

Examples

Run this code

dtm <- mc_volc()
start <- mc_volc_loc()
destin <- mc_destin_loc()

cmp <- mc_comp(dtm, origin = start, destin = destin[2, ],
               functs = c("t", "ks", "mp"), move = 8)

cmp$cost.table
plot(cmp)                  # routes on the terrain
plot(cmp, type = "chart")  # comparative bar chart