R/data.R

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

#' movecost: slope-dependent movement cost analysis across the landscape
#'
#' movecost 3.0 calculates anisotropic accumulated cost surfaces, least-cost
#' paths, corridors, networks, ranked alternative routes, cost allocations and
#' cost boundaries from a Digital Terrain Model, using 26 human-movement-related
#' cost functions.\cr
#'
#' \strong{Workflow}: build a cost surface once with \code{\link{mc_surface}},
#' then reuse it with \code{\link{mc_accum}}, \code{\link{mc_paths}},
#' \code{\link{mc_corridor}}, \code{\link{mc_boundary}}, \code{\link{mc_alloc}},
#' \code{\link{mc_network}}, and \code{\link{mc_rank}}; compare cost functions
#' with \code{\link{mc_comp}}. All results are plotted on demand with
#' \code{plot()} (ggplot2), saved with \code{\link{mc_save}}, and exported to
#' GIS formats with \code{\link{mc_export}}. The complete annotated list of
#' cost functions is returned by \code{\link{mc_cost_functions}}.\cr
#'
#' Besides citing this package, you may want to refer to: Alberti (2019)
#' <doi:10.1016/j.softx.2019.100331>, where an earlier version of the package
#' is described.
#'
#' @section Function reference by category:
#' The package's "Help Pages" index is alphabetical (this is generated by R and
#' cannot be reordered); the grouping below is provided as a map.\cr
#'
#' \strong{Core (build the cost surface once)}:\cr
#' \code{\link{mc_surface}}, \code{\link{mc_cost_functions}},
#' \code{\link{mc_dtm}}.\cr
#'
#' \strong{Analyses (reuse the surface)}:\cr
#' \code{\link{mc_accum}} (accumulated cost surface and isochrones),
#' \code{\link{mc_paths}} (least-cost paths),
#' \code{\link{mc_corridor}} (least-cost corridor),
#' \code{\link{mc_boundary}} (cost-limit boundaries),
#' \code{\link{mc_alloc}} (cost allocation),
#' \code{\link{mc_network}} (least-cost network),
#' \code{\link{mc_rank}} (ranked alternative paths),
#' \code{\link{mc_comp}} (compare cost functions).\cr
#'
#' \strong{Visualisation} (ggplot2 \code{plot()} methods, called as
#' \code{plot(x)} on a result object):\cr
#' \code{\link{plot.movecost_surface}}, \code{\link{plot.movecost_accum}},
#' \code{\link{plot.movecost_paths}}, \code{\link{plot.movecost_corridor}},
#' \code{\link{plot.movecost_boundary}}, \code{\link{plot.movecost_alloc}},
#' \code{\link{plot.movecost_network}}, \code{\link{plot.movecost_rank}},
#' \code{\link{plot.movecost_comp}}.\cr
#'
#' \strong{Input/output}:\cr
#' \code{\link{mc_save}}, \code{\link{mc_load}}, \code{\link{mc_export}}.\cr
#'
#' \strong{Sample data} (see \code{\link{movecost-data}}):\cr
#' \code{\link{mc_volc}}, \code{\link{mc_malta_dtm}}, \code{\link{mc_volc_loc}},
#' \code{\link{mc_destin_loc}}, \code{\link{mc_springs}},
#' \code{\link{mc_etna_start}}, \code{\link{mc_etna_end}},
#' \code{\link{mc_etna_boundary}}.
#'
#' @name movecost-package
#' @keywords internal
#' @importFrom ggplot2 autoplot
"_PACKAGE"

#' Internal: read a sample vector dataset shipped in inst/extdata
#' @keywords internal
#' @noRd
.mc_sample_vector <- function(layer) {
  f <- system.file("extdata", paste0(layer, ".gpkg"), package = "movecost")
  if (f == "") stop(layer, ".gpkg not found; reinstall the package.", call. = FALSE)
  sf::st_read(f, quiet = TRUE)
}

#' Sample data bundled with movecost
#'
#' movecost 3.0 ships its sample datasets as standard GIS files (GeoTIFF and
#' GeoPackage) read on demand by the accessor functions documented here. This
#' frees the package data from any dependency on the retiring
#' \emph{raster}/\emph{sp} stack used by movecost <= 2.x (whose .rda data files
#' could not be loaded without those packages installed).\cr
#'
#' Available accessors:
#' \itemize{
#'   \item \code{mc_volc()}: sample DTM (a volcano, Maungawhau/Mt Eden area;
#'     projected CRS, about 10 m resolution); \code{SpatRaster}.
#'   \item \code{mc_malta_dtm()}: DTM of Malta (40 m resolution); its
#'     coastline NoData margin makes it the reference dataset for analyses on
#'     irregular DTMs; \code{SpatRaster}.
#'   \item \code{mc_volc_loc()}: one start location on the volc DTM; \code{sf}.
#'   \item \code{mc_destin_loc()}: nine destination locations on the volc DTM;
#'     \code{sf}.
#'   \item \code{mc_springs()}: 49 springs on the Malta DTM; \code{sf}.
#'   \item \code{mc_etna_start()}, \code{mc_etna_end()}: start and end
#'     locations in the Mt Etna area (Sicily), for use with online elevation
#'     download (\code{\link{mc_dtm}}); \code{sf}.
#'   \item \code{mc_etna_boundary()}: study-area polygon for the Mt Etna area;
#'     \code{sf}.
#' }
#'
#' \strong{Note on irregular DTMs}: in movecost 3.0, NoData cells are excluded
#' from the cost graph automatically, so least-cost paths on
#' \code{mc_malta_dtm()} follow the coastline without any special setting (the
#' \code{irregular.dtm} workaround of movecost <= 2.x is no longer needed).\cr
#'
#' \strong{Note on coordinate reference systems}: the movecost <= 2.x datasets
#' carried legacy proj4 definitions without authority codes; for version 3.0
#' they have been assigned the corresponding EPSG codes, which survive file
#' round-trips identically across formats: volc and its locations EPSG:27200
#' (NZGD49 / New Zealand Map Grid), the Malta DTM and springs EPSG:23033
#' (ED50 / UTM 33N, matching the original International-ellipsoid UTM
#' definition), the Etna datasets EPSG:23032 (ED50 / UTM 32N, as in the
#' original definition). Coordinates are unchanged.
#'
#' @return \code{mc_volc()} and \code{mc_malta_dtm()} return a
#'   \code{SpatRaster}; all other accessors return an \code{sf} object.
#'
#' @examples
#' dtm <- mc_volc()
#' origin <- mc_volc_loc()
#' destinations <- mc_destin_loc()
#'
#' \donttest{
#' # the Malta DTM: paths cannot cross the sea (NoData cells)
#' malta <- mc_malta_dtm()
#' springs <- mc_springs()
#' surf <- mc_surface(malta, funct = "t", move = 8)
#' lcp <- mc_paths(surf, origin = springs[5, ], destin = springs[15, ])
#' plot(lcp)
#' }
#'
#' @seealso \code{\link{mc_surface}}, \code{\link{mc_dtm}}
#' @name movecost-data
#' @aliases mc_volc mc_malta_dtm mc_volc_loc mc_destin_loc mc_springs mc_etna_start mc_etna_end mc_etna_boundary
NULL

#' @rdname movecost-data
#' @export
mc_volc <- function() {
  f <- system.file("extdata", "volc.tif", package = "movecost")
  if (f == "") stop("volc.tif not found; reinstall the package.", call. = FALSE)
  terra::rast(f)
}

#' @rdname movecost-data
#' @export
mc_malta_dtm <- function() {
  f <- system.file("extdata", "malta_dtm_40.tif", package = "movecost")
  if (f == "") stop("malta_dtm_40.tif not found; reinstall the package.", call. = FALSE)
  terra::rast(f)
}

#' @rdname movecost-data
#' @export
mc_volc_loc <- function() .mc_sample_vector("volc_loc")

#' @rdname movecost-data
#' @export
mc_destin_loc <- function() .mc_sample_vector("destin_loc")

#' @rdname movecost-data
#' @export
mc_springs <- function() .mc_sample_vector("springs")

#' @rdname movecost-data
#' @export
mc_etna_start <- function() .mc_sample_vector("etna_start")

#' @rdname movecost-data
#' @export
mc_etna_end <- function() .mc_sample_vector("etna_end")

#' @rdname movecost-data
#' @export
mc_etna_boundary <- function() .mc_sample_vector("etna_boundary")