deprecate make_africa_mask for `make_mask

NAMESPACE

@@ -10,7 +10,9 @@ export(extract_covariates)
 export(import_rasts)
 export(inside_mask)
 export(make_africa_mask)
+export(make_mask)
 export(make_mpp_list)
+export(make_vector_mask)
 export(mask_all)
 export(mask_from_all)
 export(maskpointsdf)

R/make_africa_mask.R → R/make_mask.R

@@ -1,42 +1,57 @@
-#' @title Make Africa Mask
-#' @description
-#' Makes a `SpatRaster` or `SpatVector` mask layer of Africa, based on shapefiles for African nations from the `malaraAtlas` package.
+#' @title Make Mask
+#' @description Makes a `SpatRaster` or `SpatVector` mask layer of countries,
+#'   based on shapefiles for from the `malaraAtlas` package.
 #'
 #'
-#' @param filename Character of file path and name if  mask is to be written to disc.
-#' @param type Character `raster` or `vector`; to return mask as either `SpatRaster` or `SpatVector`.
-#' @param res Character `"high"` or `"low"`; corresponding to resolution of 0.008333333 or 0.04166667 decimal degrees
-#' @param countries Character of ISO3 country names. If `NULL` returns all countries in Africa.
+#' @param filename Character of file path and name if  mask is to be written to
+#'   disc.
+#' @param type Character `raster` or `vector`; to return mask as either
+#'   `SpatRaster` or `SpatVector`.
+#' @param res Character `"high"` or `"low"`; corresponding to resolution of
+#'   0.008333333 or 0.04166667 decimal degrees
+#' @param countries Character of ISO3 country names. If `NULL` returns all
+#'   countries in Africa.
+#' @param overwrite logical
+#'
+#' @aliases make_africa_mask make_vector_mask
 #'
 #' @return `SpatRaster` or `SpatVector` in WGS 84 (EPSG:4326).
 #' @export
 #'
-#' @details
-#' Raster layers creates with extent of `terra::ext(-18.0000019073486, 52.0416647593181, -34.9999987284343, 37.5416679382324)`
+#' @details # standard usage make_mask(filename = NULL, type = c("raster",
+#'   "vector"), res = c("high", "low"), countries = NULL)
+#'
+#'   `make_africa_mask` is deprecated, and is intended for backward
+#'   compatibility. It is a simple alias for `make_mask`:
+#'   `make_africa_mask(filename = NULL, type = c("raster", "vector"), res =
+#'   c("high", "low"), countries = NULL)`
 #'
+#'   `make_vector_mask` sets `type = "vector"`: `make_mask(filename = NULL, type
+#'   = "vector", res =' c("high", "low"), countries = NULL)`
 #' @examples
 #' \dontrun{
 #' # Create an object in workspace
-#' africa_mask_v <- make_africa_mask(type = "vector")
+#' africa_mask_v <- make_mask(type = "vector")
 #'
 #' # Save to disk
-#' make_africa_mask(filename = "africa_mask.tif", type = "raster")
+#' make_mask(filename = "africa_mask.tif", type = "raster")
 #'
 #' # or do both at once
 #' africa_mask_r <- make_africa_mask("africa_mask.tif")
 #' }
-make_africa_mask <- function(
+make_mask <- function(
     filename = NULL,
     type = c("raster", "vector"),
     res = c("high", "low"),
-    countries = NULL
+    countries = NULL,
+    overwrite = FALSE
   ){
 
   if(!is.null(filename)){
-    if(file.exists(filename)){
+    if(file.exists(filename) & !overwrite){
 
       warning(sprintf(
-        "%s exists\nUsing existing file\nto re-generate, delete existing %s",
+        "%s exists\nUsing existing file",
         filename,
         filename
       ))
@@ -51,19 +66,17 @@ make_africa_mask <- function(
     }
   }
 
-  type <- match.arg(type)
-
-  # get list of African countries
   if(is.null(countries)){
+    # get list of African countries
     countries <- sdmtools::global_regions %>%
       dplyr::filter(continent == "Africa") %>%
       dplyr::pull(iso3)
   }
 
+  type <- match.arg(type)
+
   # make using MAP data
   # has issue with validity, st_make_valid 'fixes' this however...?
-  #library(sf)
-  #library(malariaAtlas)
 
   afvect <- malariaAtlas::getShp(
     ISO = countries
@@ -88,31 +101,24 @@ make_africa_mask <- function(
   }
 
   res <- match.arg(res)
-  if(res == "high"){
-
-    afrast <- terra::rast(
-      nlyrs=1,
-      crs = terra::crs("EPSG:4326"),
-      #extent = ext(-25.3583333333333, 63.5, -40.3666666666667, 37.5416666666667),
-      extent = terra::ext(-18.0000019073486, 52.0416647593181, -34.9999987284343, 37.5416679382324), # extent based on malariaAtlas::getRaster("Explorer__2020_Africa_ITN_Use")
-      resolution = c(0.008333333, 0.008333333),
-      vals = 1,
-      names = "mask"
-    ) |>
-      terra::mask(afvect)
-
-  } else if (res == "low"){
-    afrast <- terra::rast(
-      nlyrs=1,
-      crs = terra::crs("EPSG:4326"),
-      #extent = ext(-25.3583333333333, 63.5, -40.3666666666667, 37.5416666666667),
-      extent = terra::ext(-18.0000019073486, 52.0416647593181, -34.9999987284343, 37.5416679382324),
-      resolution = c(0.04166667, 0.04166667),
-      vals = 1,
-      names = "mask"
-    ) |>
-      terra::mask(afvect)
-  }
+
+  resn <- ifelse(
+    res == "high",
+    0.008333333,
+    0.04166667
+  )
+
+  xt <- terra::ext(afvect)
+
+  afrast <- terra::rast(
+    nlyrs=1,
+    crs = terra::crs("EPSG:4326"),
+    extent = xt,
+    resolution = c(resn, resn),
+    vals = 1,
+    names = "mask"
+  ) |>
+    terra::mask(afvect)
 
   if(!is.null(filename)){
     terra::writeRaster(
@@ -131,6 +137,40 @@ make_africa_mask <- function(
 }
 
 
+#' @export
+make_africa_mask <- function(
+    filename = NULL,
+    type = c("raster", "vector"),
+    res = c("high", "low"),
+    countries = NULL
+){
+
+  make_mask(
+    filename = filename,
+    type = type,
+    res = res,
+    countries = countries
+  )
+
+}
+
+#' @export
+make_vector_mask <- function(
+    filename = NULL,
+    res = c("high", "low"),
+    countries = NULL
+){
+
+  make_mask(
+    filename = filename,
+    type = "vector",
+    res = res,
+    countries = countries
+  )
+
+}
+
+
 
 # small example to illustrate validity issue with MAP shapefiles
 # sf::sf_use_s2(FALSE)