R: R function for calculating sub-optimal least-cost paths...

moverank {movecost}

R Documentation

R function for calculating sub-optimal least-cost paths bewteen an origin and a destination location

Description

The function provides the facility to calculate the LCP between an origin and a destination location and (more importantly) to work out the first five sub-optimal LCPs between those locations. The underlying idea is the following: given two locations, we can calculate the least-costly path between them; but, if we disregard that LCP, what path would be the second least costly? And if we in turn disregard those first two, what the third least costly path would be? The same reasoning holds for all the subsequent n-th LCPs. Under the hood, moverank() rests on movecost and implements the same cost functions. See the help documentation of movecost() for further details.
Visit this LINK to access the package's vignette.

Usage

moverank(
  dtm = NULL,
  origin,
  destin,
  studyplot = NULL,
  barrier = NULL,
  plot.barrier = FALSE,
  irregular.dtm = FALSE,
  funct = "t",
  time = "h",
  lcp.n = 3,
  move = 16,
  cogn.slp = FALSE,
  sl.crit = 10,
  W = 70,
  L = 0,
  N = 1,
  V = 1.2,
  z = 9,
  use.corr = FALSE,
  leg.pos = "topright",
  leg.cex = 0.55,
  add.chart = FALSE,
  bubble.cex = 0.5,
  transp = 0.5,
  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`).
`origin`	location from which least-cost path(s) is calculated (SpatialPointsDataFrame class).
`destin`	location(s) to which least-cost path(s) is calculated (SpatialPointsDataFrame class).
`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.
`lcp.n`	number of LCPs rendered in the output plot (min=1, max=6; 3 by default; the 1st LCP is the optimal one, while the LCPs from the 2nd to the 6th are the sub-optimal ones).
`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).
`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`).
`use.corr`	TRUE or FALSE (default) is the user wants or does not want the least-cost corridor raster to be rendered in place of the input DTM.
`leg.pos`	set the position of the legend in rendered plot; 'topright' by default (other options: "bottomright", "bottom", "bottomleft", "left", "topleft", "top", "topright", "right", "center").
`leg.cex`	set the size of the labels used in the legend displayed in the rendered plot (0.55 by default).
`add.chart`	TRUE or FALSE (default) is the user wants or does not want a bubble chart visualising LCPs length vs rank vs cost to be rendered.
`bubble.cex`	set the size of the labels reporting the LCPs cost in the bubble chart (0.5 by default).
`transp`	set the transparency of the slopeshade raster that is plotted over the least-cost corridor raster (0.5 by default).
`export`	TRUE or FALSE (default) if the user wants or does not want the output to be exported; if TRUE, the least-cost corridor and the DTM (if not provided by the user but acquired online) are expoerted as a GeoTiff file, while the LCPs as a shapefile layer. All the exported files (excluding the DTM) will bear a suffix corresponding to the cost function selected by the user.

Details

Internally, moverank() uses movecost() to generate the first (optimal) LCP. In a second iteration, the optimal LCP is internally used as barrier (see movecost) when calculating the 2nd LCPs. Then, in a third iteration, the two previously generated LCPs are used as barriers when working out the 3rd LCPs. The process repeats along the same lines until the 6th LCP is calculated. The 1st LCP is deemed to represent the optimal path (cost-wise) between the two locations, while the 2nd-to-5th LCPs are deemed to represent progressively sub-optimal paths.

It is worth noting that it may happen that some LCP will cross another one; this cannot be anticipated and is context dependent. In those cases, the user may want to set the move parameter to 8 (see the section about inhibition of movement in the help documentation of movecost).

The function provides the facility to render the LCPs either on the input DTM or on the least-cost corridor between the two locations. The second option can be obtained by setting the use.corr parameter to TRUE. Also, by setting the add.chart parameter to TRUE, the function renders a bubble chart that plots the LCPs length against their rank, while the size of the bubbles is proportional to the cost. All the LCPs will be plotted.

By setting the export parameter to TRUE, the LCPs, the DTM (if acquired online), and the least-cost corridor (if obtained by setting the use.corr parameter to TRUE), will be exported: the DTM and least-cost corridor as a raster layer, the LCPs as shapefile layer. The LCPs and the least-cost corridor files will be given a suffix indicating which cost function has been used.

Value

The function returns a list storing the following components

dtm: Digital Terrain Model ('RasterLayer' class); returned only if not provided by the user and acquired online instead
LCPs: least-cost paths ('SpatialLinesDataFrame' class) ranked from 1 (optimal) to 6 (sub-optimal LCPs)
lc.corr: least-cost corridor between the origin and destination location ('RasterLayer' class); returned if the use.corr parameter is set to TRUE

Examples

# load a sample Digital Terrain Model
data(volc)


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

# calculate the optimal and sub-optimals LCPs between two locations
#result <- moverank(volc, destin.loc[1,], destin.loc[4,], move=8, funct="t")

[Package movecost version 2.1 Index]