mask_io.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial_tools.R
\name{mask_io}
\alias{mask_io}
\title{Implement \code{\link[raster]{mask}} using the inside or outside of the mask}
\usage{
mask_io(x, mask, mask_inside = FALSE, ...)
}
\arguments{
\item{x}{A Raster* (see \code{\link[raster]{mask}}).}

\item{mask}{A mask of class \code{\link[sp]{SpatialPolygonsDataFrame-class}}.}

\item{mask_inside}{A logical variable that defines whether or not to mask values in \code{x} outside (\code{FALSE}) or inside (\code{TRUE}) of the \code{mask}.}

\item{...}{Additional arguments passed to \code{\link[raster]{mask}}.}
}
\value{
The function returns a Raster* object in which values outside or inside of a supplied \code{\link[sp]{SpatialPolygonsDataFrame-class}} object have been masked.
}
\description{
This function implements \code{\link[raster]{mask}} using the inside or the outside of the mask. The function is implemented in the same way as \code{\link[raster]{mask}} but with an additional logical argument, \code{mask_inside}. If \code{mask_inside = FALSE} (the default), values beyond the mask are masked and the function simply implements \code{\link[raster]{mask}}. In contrast, if \code{mask_inside = TRUE}, values within the mask are masked.
}
\details{
This function was motivated by animal movement datasets from coastal environments. For example, consider the cost of movement over a surface between two points for an exclusively benthic marine animal versus an exclusively terrestrial animal. With a \code{mask} that represents the coastline, for the exclusively marine animal, it is necessary to mask values inside the coastline (i.e., on land), so \code{mask_inside = TRUE}, to prevent movement on land; while for a terrestrial animal, it is necessary to mask values beyond the coastline (i.e., in the sea), so \code{mask_inside = FALSE}, to prevent movement into the sea.
}
\examples{
#### Define an example raster
# We will use some bathymetry data from around Oban
# ... which we will mask using some coastline data. All values on land
# ... are currently NA so we'll set these to 10 m for demonstration purposes.
dat_gebco[is.na(dat_gebco[])] <- 10
dat_gebco <- raster::crop(dat_gebco, raster::extent(dat_coast))
raster::plot(dat_gebco)

#### Standard implementation with mask_inside = FALSE simply implements raster::mask()
m <- mask_io(dat_gebco, dat_coast)
raster::plot(dat_coast)
raster::plot(m, add = TRUE)

#### Implementation with mask_inside = TRUE implements the mask within the coastline
m <- mask_io(dat_gebco, dat_coast, mask_inside = TRUE)
raster::plot(dat_coast)
raster::plot(m, add = TRUE)

#### Additional arguments to raster::mask() can be passed via ... as usual
m <- mask_io(dat_gebco, dat_coast, mask_inside = TRUE, updatevalue = 1e5)
raster::plot(dat_coast)
raster::plot(m, add = TRUE)

}
\author{
Edward Lavender
}