Resolve a study area from a studyArea spec via geodata::gadm()

Source: R/setupProject.R

Convenience wrapper that returns an sf polygon for the requested country / subregion using geodata::gadm().

setupStudyArea(
  studyArea,
  paths,
  envir = parent.frame(),
  callingEnv = sys.frame(-2),
  verbose = getOption("Require.verbose", 1L)
)

Arguments

studyArea

Optional. If a list, it will be passed to geodata::gadm. To specify a country other than the default "CAN", the list must have a named element, "country". All other named elements will be passed to gadm. 2 additional named elements can be passed for convenience, subregion = "...", which will be grepped with the column NAME_1, and epsg = "...", so a user can pass an epsg.io code to reproject the studyArea. See examples.

paths

a list with named elements, specifically, modulePath, projectPath, packagePath and all others that are in SpaDES.core::setPaths() (i.e., inputPath, outputPath, scratchPath, cachePath, rasterTmpDir). Each of these has a sensible default, which will be overridden but any user supplied values. See setup.

envir

The environment where setupProject is called from. Defaults to parent.frame() which should be fine in most cases and user shouldn't need to set this

callingEnv

The environment from which the function was called. Defaults to sys.frame(-2) which represents the case where the inner setup* functions are called inside setupProject, which was called by a user.

verbose

Numeric or logical indicating how verbose should the function be. If -1 or -2, then as little verbosity as possible. If 0 or FALSE, then minimal outputs; if 1 or TRUE, more outputs; 2 even more. NOTE: in Require function, when verbose >= 2, also returns details as if returnDetails = TRUE (for backwards compatibility).

Value

setupStudyArea will return an sf class object coming from geodata::gadm, with subregion specification as described in the studyArea argument.

Details

setupStudyArea calls [geodata::gadm()] to get an sf polygon or set of polygons of a country or a subdivision of a country. The user can pass a named list of character elements that match entries in the columns "NAME_1" and "NAME_2" of the sf object. If passing NAME_2, the user must pass level = 2. If passing NAME_1 and level = 2 all subdivision polygons under NAME_1 will be returned, which can be useful to explore subdivision names. setupStudyArea only uses inputPath within its paths argument, which will be passed to path argument of gadm.

setupStudyArea(list(NAME_1 = "Alberta", "NAME_2" = "Division No. 17", level = 2))

See also

setupProject() for the high-level wrapper, setup_family for an overview.