mapAdd: Append a spatial object to map

In PredictiveEcology/map: Defines a meta class of geographical objects, the 'map' class, and associated tools

Append a spatial object to map

Description

If isStudyArea = TRUE, then several things will be triggered:

1. This layer will be added to metadata with studyArea set to max(studyArea(map)) + 1.

2. update CRS slot to be the CRS of the study area.

Usage

mapAdd(obj, map, layerName, overwrite = getOption("map.overwrite", FALSE), ...)

## Default S3 method:
mapAdd(
  obj = NULL,
  map = new("map"),
  layerName = NULL,
  overwrite = getOption("map.overwrite"),
  columnNameForLabels = 1,
  leaflet = FALSE,
  isStudyArea = FALSE,
  isRasterToMatch = FALSE,
  envir = NULL,
  useCache = getOption("reproducible.useCache", TRUE),
  useParallel = getOption("map.useParallel", FALSE),
  ...
)

Arguments

obj	Optional spatial object, currently RasterLayer, SpatialPolygons.
map	Optional map object. If not provided, then one will be created. If provided, then the present obj or options passed to reproducible::prepInputs() (e.g., url), will be appended to this map.
layerName	Required. A label for this map layer. This can be the same as the object name.
overwrite	Logical. If TRUE and this layerName exists in the map, then it will replace the existing object. Default is getOption("map.overwrite").
...	Additional arguments passed to: reproducible::postProcess(), reproducible::projectInputs(), reproducible::fixErrors(), and reproducible::prepInputs().
columnNameForLabels	A character string indicating which column to use for labels. This is currently only used if the object is a sp::SpatialPolygonsDataFrame.
leaflet	Logical or Character vector of path(s) to write tiles. If TRUE or a character vector, then this layer will be added to a leaflet map. For RasterLayer object, this will trigger a call to gdal2tiles, making tiles. If path is not specified, it will be the current path. The tile base file path will be paste0(layerName, "_", rndstr(1, 6)).
isStudyArea	Logical. If TRUE, this will be assigned the label "StudyArea", and will be passed into reproducible::prepInputs() for any future layers added.
isRasterToMatch	Logical indicating whether the object to be added should be considered a rasterToMatch.
envir	An optional environment. If supplied, then the obj will not be placed "into" the maps slot, rather the environment label will be placed into the maps slot.
useCache	Logical. If TRUE, internal calls to reproducible::Cache() will be used.
useParallel	Logical. If TRUE, then if there is more than one calculation to do at any stage, it will create and use a parallel cluster via pemisc::makeOptimalCluster(). If running analyses in parallel, it may be useful to pass a function (via .clInit) to be run on each of the nodes immediately upon cluster creation (e.g., to set options).

Examples

withr::local_tempdir("example_mapAdd_") |>
  withr::local_dir()

StudyArea <- list(cbind(
  x = c(-122.98, -116.1, -99.2, -106, -122.98),
  y = c(59.9, 65.73, 63.58, 54.79, 59.9)
)) |>
  sf::st_polygon() |>
  sf::st_sfc() |>
  sf::st_sf(geometry = _, ID = 1L, shinyLabel = "zone2", crs = "epsg:4326")

ml <- mapAdd(StudyArea, isStudyArea = TRUE, layerName = "Small Study Area",
             poly = TRUE, analysisGroup2 = "Small Study Area")

if (require("SpaDES.tools", quietly = TRUE)) {
  withr::local_options(list(
    map.tilePath = withr::local_tempdir("tiles_"),
    map.useParallel = FALSE
  ))
  smallStudyArea <- SpaDES.tools::randomPolygon(studyArea(ml), 1e5)
  smallStudyArea$ID <- 1L
  smallStudyArea$shinyLabel <- "zone2"

  ml <- mapAdd(smallStudyArea, ml, isStudyArea = TRUE, filename2 = NULL,
               analysisGroup2 = "Smaller Study Area",
               poly = TRUE,
               layerName = "Smaller Study Area") # adds a second studyArea within 1st

  rasTemplate <- terra::rast(terra::ext(studyArea(ml)), resolution = 0.001)
  tsf <- SpaDES.tools::randomPolygons(rasTemplate, numTypes = 8)*30
  vtm <- SpaDES.tools::randomPolygons(tsf, numTypes = 4)
  levels(vtm) <- data.frame(
    ID = sort(unique(vtm[])),
    Factor = c("black spruce", "white spruce", "aspen", "fir")
  )

  ml <- mapAdd(tsf, ml, layerName = "tsf1",
               filename2 = "tsf1.tif", # to postProcess
               # to map object
               tsf = "tsf1.tif", # to column in map@metadata
               analysisGroup1 = "tsf1_vtm1",  # this is the label for analysisGroup1
               leaflet = TRUE, # to column in map@metadata; used for visualizing in leaflet
               overwrite = TRUE)
  ml <- mapAdd(vtm, ml, filename2 = "vtm1.grd",
               layerName = "vtm1",
               vtm = "vtm1.grd",
               analysisGroup1 = "tsf1_vtm1", leaflet = TRUE, overwrite = TRUE)

  ## these map analyses are in `LandWebUtils` package, which is reverse dependency of this one
  ageClasses <- c("Young", "Immature", "Mature", "Old")
  ageClassCutOffs <- c(0, 40, 80, 120)

  ## add an analysis -- this will trigger analyses because there are already objects in the map
  ##    This will trigger 2 analyses:
  ##    LeadingVegTypeByAgeClass on each raster x polygon combo (only 1 currently)
  ##    so there is 1 raster group, 2 polygon groups, 1 analyses - Total 2, 2 run now
  # ml <- mapAddAnalysis(ml, functionName = "LeadingVegTypeByAgeClass",
  #                      ageClasses = ageClasses, ageClassCutOffs = ageClassCutOffs)

  ## add an analysis -- this will trigger analyses because there are already objects in the map
  ##    This will trigger 2 more analyses:
  ##    largePatches on each raster x polygon combo (only 1 currently)
  ##    so there is 1 raster group, 2 polygon groups, 2 analyses - Total 4, only 2 run now
  # ml <- mapAddAnalysis(ml, functionName = "LargePatches", ageClasses = ageClasses,
  #                      id = "1", labelColumn = "shinyLabel",
  #                      ageClassCutOffs = ageClassCutOffs)

  ## Add a second polygon, trigger
  # smallStudyArea2 <- randomPolygon(studyArea(ml), 1e5)
  # smallStudyArea2$ID <- 1L
  # smallStudyArea2$shinyLabel <- "zone2"

  ## add a new layer -- this will trigger analyses because there are already analyese in the map
  ##    This will trigger 2 more analyses ... largePatches on each *new* raster x polygon combo
  ##    (now there are 2) -- so there is 1 raster group, 3 polygon groups, 2 analyses - Total 6
  # ml <- mapAdd(smallStudyArea2, ml, isStudyArea = FALSE, filename2 = NULL, overwrite = TRUE,
  #              analysisGroup2 = "Smaller Study Area 2",
  #              poly = TRUE,
  #              layerName = "Smaller Study Area 2") # adds a second studyArea within 1st

  ## Add a *different* second polygon, via overwrite. This should trigger new analyses.
  # smallStudyArea2 <- randomPolygon(studyArea(ml), 1e5)
  # smallStudyArea2$ID <- 1
  # smallStudyArea2$shinyLabel = "zone1"

  ## add a new layer -- this will trigger analyses because there are already analyses in the map
  ##    This will trigger 2 more analyses ... largePatches on each *new* raster x polygon combo
  ##    (now there are 2) -- so there is 1 raster group, 3 polygon groups, 2 analyses - Total 6
  # ml <- mapAdd(smallStudyArea2, ml, isStudyArea = FALSE, filename2 = NULL, overwrite = TRUE,
  #              analysisGroup2 = "Smaller Study Area 2",
  #              poly = TRUE,
  #              layerName = "Smaller Study Area 2") # adds a second studyArea within 1st

  ## Add a 2nd pair of rasters
  # rasTemplate <- rast(ext(studyArea(ml)), res = 0.001)
  # tsf2 <- randomPolygons(rasTemplate, numTypes = 8)*30
  # vtm2 <- randomPolygons(tsf2, numTypes = 4)
  # levels(vtm2) <- data.frame(
  #   ID = sort(unique(vtm2[])),
  #   Factor = c("black spruce", "white spruce", "aspen", "fir")
  # )

  # ml <- mapAdd(tsf2, ml, filename2 = "tsf2.tif", layerName = "tsf2",
  #              tsf = "tsf2.tif",
  #              analysisGroup1 = "tsf2_vtm2", leaflet = TRUE, overwrite = TRUE)
  # ml <- mapAdd(vtm2, ml, filename2 = "vtm2.grd", layerName = "vtm2",
  #              vtm = "vtm2.grd",
  #              analysisGroup1 = "tsf2_vtm2", leaflet = TRUE, overwrite = TRUE)

  ## post hoc analysis of data
  ##  use or create a specialized function that can handle the analysesData slot
  # ml <- mapAddPostHocAnalysis(map = ml, functionName = "rbindlistAG",
  #                             postHocAnalysisGroups = "analysisGroup2",
  #                             postHocAnalyses = "all")
}

## cleanup
withr::deferred_run()

PredictiveEcology/map documentation built on June 15, 2025, 6:15 a.m.