Add mask_io() function.

NAMESPACE

@@ -11,6 +11,7 @@ export(dist_btw_receivers)
 export(dist_over_surface)
 export(false_detections_sf)
 export(lcp_over_surface)
+export(mask_io)
 export(pythagoras_3d)
 export(quality_check)
 export(setup_acdc)

R/spatial_tools.R

@@ -140,6 +140,64 @@ cells_from_val <- function(x, y, interval = 1L, cells = TRUE, na.rm = TRUE,...){
 }
 
 
+######################################
+######################################
+#### mask_io()
+
+#' @title Implement \code{\link[raster]{mask}} using the inside or outside of the mask
+#' @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.
+#'
+#' @param x A Raster* (see \code{\link[raster]{mask}}).
+#' @param mask A mask of class \code{\link[sp]{SpatialPolygonsDataFrame-class}}.
+#' @param 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}.
+#' @param ... Additional arguments passed to \code{\link[raster]{mask}}.
+#'
+#' @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.
+#' @return The function returns a Raster* object in which values outside or inside of a supplied \code{\link[sp]{SpatialPolygonsDataFrame-class}} object have been masked.
+#'
+#' @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
+#' @export
+#'
+
+mask_io <- function(x, mask, mask_inside = FALSE,...){
+  # Re-define mask if we are masking points inside the mask:
+  if(mask_inside){
+    area <- raster::extent(x)
+    area <- sp::Polygon(raster::coordinates(area))
+    area <- sp::SpatialPolygons(list(sp::Polygons(list(area), ID = 1)))
+    raster::crs(area) <- raster::crs(x)
+    mask <- rgeos::gDifference(area, mask)
+  }
+  # Mask raster
+  x_masked <- raster::mask(x = x, mask = mask,...)
+  return(x_masked)
+}
+
+
 ######################################
 ######################################
 #### pythagoras_3d()

README.Rmd

@@ -70,7 +70,7 @@ A number of functions facilitate the assembly, processing and checking of passiv
 
 A number of other functions facilitate spatial operations, which support ecological investigations and space use algorithms.
 
-* **Spatial manipulations.** Some functions provide simple wrappers for common spatial operations. For instance, `buffer_and_crop()` buffers a spatial object (e.g., receiver locations) and uses this buffered object to crop another (e.g., the local bathymetry). `update_extent()` shrinks or inflates an extent object. `cells_from_val()` returns the cells or a raster of the cells of a raster that are equal to a specified value or lie within a specified range of values. 
+* **Spatial manipulations.** Some functions provide simple wrappers for common spatial operations. For instance, `buffer_and_crop()` buffers a spatial object (e.g., receiver locations) and uses this buffered object to crop another (e.g., the local bathymetry). `update_extent()` shrinks or inflates an extent object. `mask_io()` masks values in a raster that lie inside or outside of a spatial mask. `cells_from_val()` returns the cells or a raster of the cells of a raster that are equal to a specified value or lie within a specified range of values. 
 * **Euclidean distances.** Some functions facilitate distance calculations. For instance, `dist_btw_receivers()` calculates Euclidean distances between all receiver combinations and `pythagoras_3d()` and `dist_over_surface()` calculate the distances between points or along a path over a three-dimensional surface. 
 * **Shortest pathways/distances.** Often, Euclidean distances may not be a suitable representation of distance. This is especially the case for coastal benthic/demersal species in bathymetrically complex environments, for which navigation between locations may require movement over hilly terrain and around coastline. Thus, `lcp_over_surface()` calculates shortest pathways and/or the distances of the shortest pathways over a surface between origin and destination coordinates. 
 

README.md

@@ -153,10 +153,11 @@ ecological investigations and space use algorithms.
     for common spatial operations. For instance, `buffer_and_crop()`
     buffers a spatial object (e.g., receiver locations) and uses this
     buffered object to crop another (e.g., the local bathymetry).
-    `update_extent()` shrinks or inflates an extent object.
-    `cells_from_val()` returns the cells or a raster of the cells of a
-    raster that are equal to a specified value or lie within a specified
-    range of values.
+    `update_extent()` shrinks or inflates an extent object. `mask_io()`
+    masks values in a raster that lie inside or outside of a spatial
+    mask. `cells_from_val()` returns the cells or a raster of the cells
+    of a raster that are equal to a specified value or lie within a
+    specified range of values.
   - **Euclidean distances.** Some functions facilitate distance
     calculations. For instance, `dist_btw_receivers()` calculates
     Euclidean distances between all receiver combinations and