movecorr: R function for calculating least-cost corridor between point...

In movecost: Calculation of Slope-Dependant Accumulated Cost Surface, Least-Cost Paths, Least-Cost Corridors, Least-Cost Networks Related to Human Movement Across the Landscape

R function for calculating least-cost corridor between point locations

Description

The function provides the facility to calculate the least-cost corridor between point locations. It just requires an input DTM and at least two point locations ('SpatialPointsDataFrame' class) representing the locations between which the corridor is calculated. Under the hood, movecorr() relies on the movecost function and, needless to say, implements the same cost functions. See the help documentation of 'movecost()' for further details.
Visit this LINK to access the package's vignette.

Usage

movecorr(
  dtm = NULL,
  a,
  b,
  lab.a = "A",
  lab.b = "B",
  cex.labs = 0.8,
  studyplot = NULL,
  barrier = NULL,
  plot.barrier = FALSE,
  irregular.dtm = FALSE,
  funct = "t",
  time = "h",
  move = 16,
  field = 0,
  cogn.slp = FALSE,
  sl.crit = 10,
  W = 70,
  L = 0,
  N = 1,
  V = 1.2,
  z = 9,
  rescale = FALSE,
  transp = 0.5,
  graph.out = TRUE,
  export = FALSE
)

Arguments

dtm	Digital Terrain Model (RasterLayer class); if not provided, elevation data will be acquired online for the area enclosed by the 'studyplot' parameter (see movecost).
a	first location from which the least-cost corridor is calculated (SpatialPointsDataFrame class); if it contains more than two locations, see the 'Description' section above.
b	second location from which the least-cost corridor is calculated (SpatialPointsDataFrame class); if parameter 'a' stores more than two locations, this parameter is disregarded; see the 'Description' section above.
lab.a	string to be used to label point a on the outplut plot (A is the default)
lab.b	string to be used to label point a on the outplut plot (B is the default).
cex.labs	scaling factor for the size of the points' labels (0.8 by default)
studyplot	polygon (SpatialPolygonDataFrame class) representing the study area for which online elevation data are acquired (see movecost); NULL is default.
barrier	area where the movement is inhibited (SpatialLineDataFrame or SpatialPolygonDataFrame class) (see movecost).
plot.barrier	TRUE or FALSE (default) if the user wants or does not want the barrier to be plotted (see movecost).
irregular.dtm	TRUE or FALSE (default) if the input DTM features irregular margins (see movecost).
funct	cost function to be used (for details on each of the following, see movecost): -functions expressing cost as walking time- t (default) uses the on-path Tobler's hiking function; tofp uses the off-path Tobler's hiking function; mp uses the Marquez-Perez et al.'s modified Tobler's function; icmonp uses the Irmischer-Clarke's hiking function (male, on-path); icmoffp uses the Irmischer-Clarke's hiking function (male, off-path); icfonp uses the Irmischer-Clarke's hiking function (female, on-path); icfoffp uses the Irmischer-Clarke's hiking function (female, off-path); ug uses the Uriarte Gonzalez's walking-time cost function; ma uses the Marin Arroyo's walking-time cost function; alb uses the Alberti's Tobler hiking function modified for pastoral foraging excursions; gkrs uses the Garmy, Kaddouri, Rozenblat, and Schneider's hiking function; r uses the Rees' hiking function; ks uses the Kondo-Seino's hiking function; trp uses the Tripcevich's hiking function; -functions for wheeled-vehicles- wcs uses the wheeled-vehicle critical slope cost function; -functions expressing abstract cost- ree uses the relative energetic expenditure cost function; b uses the Bellavia's cost function; e uses the Eastman's cost function; -functions expressing cost as metabolic energy expenditure- p uses the Pandolf et al.'s metabolic energy expenditure cost function; pcf uses the Pandolf et al.'s cost function with correction factor for downhill movements; m uses the Minetti et al.'s metabolic energy expenditure cost function; hrz uses the Herzog's metabolic energy expenditure cost function; vl uses the Van Leusen's metabolic energy expenditure cost function; ls uses the Llobera-Sluckin's metabolic energy expenditure cost function; a uses the Ardigo et al.'s metabolic energy expenditure cost function; h uses the Hare's metabolic energy expenditure cost function (for all the mentioned cost functions, see movecost).
time	time-unit expressed by the accumulated raster if Tobler's and other time-related cost functions are used; h' for hour, 'm' for minutes.
move	number of directions in which cells are connected: 4 (rook's case), 8 (queen's case), 16 (knight and one-cell queen moves; default).
field	value assigned to the cells coinciding with the barrier (0 by default) (see movecost.
cogn.slp	TRUE or FALSE (default) if the user wants or does not want the 'cognitive slope' to be used in place of the real slope (see movecost).
sl.crit	critical slope (in percent), typically in the range 8-16 (10 by default) (used by the wheeled-vehicle cost function; see movecost).
W	walker's body weight (in Kg; 70 by default; used by the Pandolf's and Van Leusen's cost function; see movecost).
L	carried load weight (in Kg; 0 by default; used by the Pandolf's and Van Leusen's cost function; see movecost).
N	coefficient representing ease of movement (1 by default) (see movecost).
V	speed in m/s (1.2 by default) (used by the Pandolf et al.'s, Pandolf et al.s with correction factor, Van Leusen's, and Ardigo et al.'s cost function; if set to 0, it is internally worked out on the basis of Tobler on-path hiking function (see movecost).
z	zoom level for the elevation data downloaded from online sources (from 0 to 15; 9 by default) (see movecost and get_elev_raster).
rescale	TRUE or FALSE (default) if the user wants or does not want the output least-coast corridor raster to be rescaled between 0 and 1.
transp	set the transparency of the slopeshade raster that is plotted over the least-cost corridor raster (0.5 by default).
graph.out	TRUE (default) or FALSE if the user wants or does not want a graphical output to be generated.
export	TRUE or FALSE (default) if the user wants or does not want the output to be exported; if TRUE, the least-cost corridor, the dtm (if not provided by the user but acquired online), and the accumulated cost surface around a and b are exported as a GeoTiff file, while the two LCPs (from a to b, and from b to a) as individual shapefiles. If multiple locations are analysed, only the least-cost corridor (and the DTM if originally not provided) will be exported. All the exported files (excluding the DTM) will bear a suffix corresponding to the cost function selected by the user.

Details

If only two locations are provided (one via parameter a, one via parameter b), the function renders a raster representing the least cost corridor (which can be optionally exported as GeoTiff) with least-cost paths superimposed. If more than 2 locations are fed into the function via the 'a' parameter, the function calculates the least-cost corridor between pairs of locations. All the pair-wise corridor rasters are returned (but not individually plotted) in a list. All those rasters will be summed, and the resulting raster will be plotted (and can be, optionally, exported as GeoTiff).

The function returns a list containing a number of components (see 'Value' below). For more details about exporting the function's outputs, see 'Arguments' below.

If the user wants to calculate the least-cost corridor between two locations only, (s)he may want to use parameter a and b to indicate the two locations of interest respectively. For example, using the datasets provided by this package:

result <- movecorr(a=Etna_start_location, b=Etna_end_location[1,], studyplot=Etna_boundary, funct="tofp")

The above will produce the least-cost corridor between two locations close to Mt Etna (Sicily, Italy), using the Tobler's cost function (for off-path hiking). Side note: the elevation data will be acquired online.

If the interest lies in using more than 2 locations, the user may want to feed the dataset storing all the locations into parameter a (disregarding b). As explained above, in this case the function calculates the least-cost corridor between pairs of locations. All the pair-wise corridor rasters are returned in a list. Those rasters will be summed, and the resulting raster will be plotted (and can be, optionally, exported as GeoTiff). For example, to calculate the least-cost corridors between every individual unique pair of the 9 locations stored in the destin.loc dataset:

volc <- raster::raster(system.file("external/maungawhau.grd", package="gdistance"))

result <- movecorr(dtm=volc, a=destin.loc, funct="ree", rescale=TRUE)

Note that only parameter a has been used. The function returns and plots the sum of the 36 individual corridors; the latter are not plotted, but are stored in a list. If the user wants to plot the least-cost corridor, say, n 4, and then add the two locations between which the corridor has been calculated, (s)he can first plot the corridor raster n 4:

raster::plot(result$corridors[[4]])

Then, identifying which locations are related to corridor n 4 can be easily accomplished by looking up the values stored in the 4th column of the returned matrix:

result$locations.matrix

The locations are the n 1 and n 5, so the user can add them to the plot previosly produced using:

raster::plot(destin.loc[1,], pch=20, add=T)
raster::plot(destin.loc[5,], pch=20, add=T)

Note that the resulting plot can be produced (with a nicer outlook) directly by 'movecorr()' by feeding those two locations in the parameter 'a' and 'b' respectively:

result <- movecorr(dtm=volc, a=destin.loc[1,], b=destin.loc[5,], funct="ree")

Overall, what movecorr() does is to calculate (via the movecost function) the accumulated cost surface around each location. Those are eventually summed to produce the least-cost corridor between locations. On the produced corridor raster, the cost of a cell is the total cost to reach it from all the analysed locations. About least-cost corridors between pairs of locations, see for instance:
Mitchell A. (2012), "The ESRI Guide to GIS Analysis. Vol 3. Modelling Suitability, Movement, and Interaction", New York: Esri Press (257-259).

Value

The function returns a list storing the following components

• dtm: Digital Terrain Model ('RasterLayer' class)

• lc.corridor: raster of the least-cost corridor ('RasterLayer' class); if more than two locations are analysed, this raster is the sum of all the corridors between all the pairs of locations

• lcp_a_to_b: least-cost past from a to b ('SpatialLinesDataFrame' class); returned only when the corridor is calculated between two locations

• lcp_b_to_a: least-cost past from b to a ('SpatialLinesDataFrame' class); returned only when the corridor is calculated between two locations

• accum_cost_surf_a: accumulated cost-surface around a ('RasterLayer' class); returned only when the corridor is calculated between two locations

• accum_cost_surf_b: accumulated cost-surface around b ('RasterLayer' class); returned only when the corridor is calculated between two locations

• corridors: list of rasters ('RasterLayer' class) representing the least-cost corridor between all the unique pairs of locations; returned only when more than two locations are analysed

• locations.matrix: matrix whose columns indicate the identifiers for all the unique pairs of locations for which each corridor is calculated; returned only when more than two locations are analysed

See Also

movecost

Examples

# load a sample Digital Terrain Model
data(volc)


# load the sample destination locations on the above DTM
data(destin.loc)


# calculate the least-cost corridor between two locations, using the
# relative energetic expenditure cost function, and store the results
# in the 'result' object

result <- movecorr(dtm=volc, a=destin.loc[1,], b=destin.loc[3,], funct="ree", move=8)


#same as above, but using the 'cognitive slope'

# result <- movecorr(dtm=volc, a=destin.loc[1,], b=destin.loc[3,],
# funct="ree", move=8, cogn.slp=TRUE)

movecost documentation built on April 12, 2023, 12:37 p.m.