sim_surface.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial_tools.R
\name{sim_surface}
\alias{sim_surface}
\title{Populate a raster with simulated values}
\usage{
sim_surface(
  blank,
  n = 1L,
  sim_values,
  mask = NULL,
  mask_inside = FALSE,
  plot = 1:2L
)
}
\arguments{
\item{blank}{A \code{\link[raster]{raster}}.}

\item{n}{An integer that defines the number of (approximately equal area) pieces into which to split \code{blank}.}

\item{sim_values}{A function or, if \code{n > 1L}, a list of functions, that, for a given number of cells, simulate new values for those cells.}

\item{mask, mask_inside}{Arguments required to implement a spatial mask via \code{\link[flapper]{mask_io}}.}

\item{plot}{An integer that defines whether or not to plot a histogram of simulated values (\code{1L}), a heat map of the simulated raster (\code{2L}) or both (\code{1:2L}).}
}
\value{
The function returns a \code{\link[raster]{raster}}, with the same properties as \code{blank}, with values generated from the \code{sim_values} function(s).
}
\description{
This function is designed to populate a raster with simulated values. To implement the function, a (blank) raster should be supplied. A user-defined function, or list of functions, is evaluated across this raster, or across sub-regions of this raster, to generate a new raster with simulated values.
}
\examples{
#### Example (1): Simulate values across the whole raster
sim_surface(dat_gebco,
  sim_values = function(n) stats::runif(n = n, 0, 1)
)
sim_surface(dat_gebco,
  sim_values = function(n) stats::rnorm(n = n, 0, 1)
)

#### Example (2): Simulate values differently across different areas
# .. by defining the number of areas into which to split the raster
# .. and a list of function(s)
sim_surface(dat_gebco,
  n = 2, sim_values = list(
    function(n) stats::runif(n = n, 0, 1),
    function(n) stats::runif(n = n, 10, 11)
  )
)

#### Example (3): Include a spatial mask
sim_surface(dat_gebco,
  n = 2, sim_values = list(
    function(n) stats::runif(n = n, 9, 10),
    function(n) stats::runif(n = n, 10, 11)
  ),
  mask = dat_coast, mask_inside = TRUE
)

}
\author{
Edward Lavender
}