R/hf_efficiency.R

In kbvernon/rHike: Functions for Computing Hiking Efficiency and Velocity

#' General hiking function for efficiency
#'
#' A convenience wrapper for generating an efficiency (energy per unit distance)
#' raster based on various hiking functions.
#'
#' @usage hf_efficiency(x, hf = "herzog", ...)
#'
#' @param x A \code{RasterLayer} with slope values, assumed to be in degrees.
#' @param hf \code{Character} The hiking function with which to compute efficiency, either "herzog" (default) or "flerp."
#' @param ... Arguments to be passed to individual hiking functions.
#'
#' @return A \code{raster*} of velocity values in J/kg/m.
#'
#' @export
#'
#' @examples
#' \dontrun{
#'
#' library(raster)
#'
#' dem <- raster(system.file("extdata/slc.grd", package = "rHike"))
#'
#' slope <- hf_slope(dem)
#'
#' efficiency <- hf_efficiency(slope, hf = "herzog")
#'
#' plot(efficiency)
#'
#' }
#'
hf_efficiency <- function(x, hf = "herzog", ...) {

  if(!inherits(x, "RasterLayer")) stop("x must be a raster.")

  if(!(hf %in% c("herzog", "flerp"))) stop("Unknown hiking function.")

  if(identical(hf, "herzog")) e <- raster::calc(x, fun = function(x) rHike::hf_herzog(x = x))

  return(e)

}