defineWorld: Define the topographic landscape

In andresgmejiar/lbmech: A Package to Study the Mechanics of Landscape and Behavior

Define the topographic landscape

Description

Function that defines the grid that can be traversed–the "world"–as well as the cells that can be accessed from each individual cell. This is the most time-intensive function.

Usage

defineWorld(
  source,
  source_id = "TILEID",
  z_min = NULL,
  grid = NULL,
  proj = NULL,
  grid_id = "TILEID",
  cut_slope = Inf,
  directions = 16,
  neighbor_distance = 10,
  z_fix = NULL,
  unit = "m",
  vals = "location",
  precision = 2,
  dist = "proj",
  r = 6378137,
  f = 1/298.257223563,
  b = 6356752.3142,
  FUN = NULL,
  sampling = "bilinear",
  water = FALSE,
  water_speed = "speed",
  uv = TRUE,
  priority = "water",
  overwrite = FALSE,
  filt = 0,
  dir = tempdir(),
  cols = c("x_i", "y_i", "dz", "dl", "dr"),
  ...
)

Arguments

source	An object of class SpatVector, or potential inputs to makeGrid that define the paths to the original source files of the desired rasters in the same format as the output of the makeGrid(sources = TRUE). If the object is NOT a already a polygon of the appropriate format, set source_id = NULL and add the necessary makeGrid parameter
source_id	A character string representing the name of the column in the source polygon containing the unique Tile IDs. Default is source_id = 'TILEID'
z_min	The minimum allowable elevation. Useful if DEM source includes ocean bathymetry as does the SRTM data from AWS. Default is z_min = NULL, but set to 0 for SRTM data.
grid	An object of class SpatVector representing the partitioning grid for the maximum possible travel area. Smaller grids increase the amount of area that can be read into the memory, but require more I/O operations. Default is grid = source.
proj	A crs object or character string representing the output projection. Default projection is proj = crs(polys) unless a 'z_fix' or 'proj' is provided, in which case the latter is ignored. Great care should be employed to ensure that the projection is conformal and in meters.
grid_id	A character string representing the name of the column in the grid polygon containing the unique Tile IDs. Default is tile_id = 'TILEID'
cut_slope	A number representing the dimensionless maximum slope of ascent/descent. To ignore, set cut_slope = Inf.
directions	One of the integers c(4, 8, 16), the character string 'bishop',or a neighborhood matrix. Default is directions = 16, implying that all 'knight and one-cell queen moves' are permissible movements on the grid. See adjacent.
neighbor_distance	An integer representing the distance in meters that tiles are buffered. In other words, to ensure that all transitions in the 'world' are recorded, files for each tile will contain a number of observations that fall outside of the tile in other ones. Default is 100 m, but adjust on raster size.
z_fix	A SpatRaster or Raster* that will define the resolution, origin, and projection information for the entire "world" of possible movement. Note that it does NOT need the same extent. Default resolution is 5, and offset is 0. Default projection is proj = crs(polys) unless a 'z_fix' or 'proj' is provided, in which case the latter is ignored. Great care should be employed to ensure that the projection is conformal and in meters.
unit	One of c("m", "km", "ft", "mi"), representing the unit of the DEM. All will be converted to meters, which is the default.
vals	A character string or a SpatRaster or Raster* object. Ignored unless the polys parameter is a polygon NOT the output of the makeGrid function as the default is the character string 'location', AND the appropriate world .gz file is NOT present in the workspace directory. In which case it must represent either the original DEM or a character string with the column representing the DEM filepath or URL.
precision	An integer representing the number of decimals to retain in the x and y directions. For grid sizes with nice, round numbers precisions can be low. This factor is controled by rast. Default is 2.
dist	A character string representing the way distances should be calculated. Default is dist = 'proj' for the default projection units, but the following geodesic methods are also available: c('haversine','cosine','karney','meeus','vincentyEllipsoid','vincentySphere'). The developer recommends 'karney'.
r	The earth's radius. Employed only if one of the geodesic methods is used. Default is r = 6378137 for WGS1984.
f	The earth's ellipsoidal flattening. Employed only if dist %in% c('karney','meeus','vincentyEllipsoid'). Default is f=1/298.257223563 for WGS1984
b	The earth's semiminor axis. Employed only if dist = 'vincentyEllipsoid'. Default is b=6356752.3142 for WGS1984.
FUN	Function to deal with overlapping values for overlapping sectors. Default is NA, which uses merge. To use mosaic, provide a compatible function.
sampling	How to resample rasters. Default is 'bilinear' interpolation, although 'ngb' nearest neighbor is available for categorical rasters.
water	Optional. One of (1) SpatialPolygon* or SpatVector polygon representing the area covered by water, in which case water_speed must also be provided; (2) A RasterLayer or single-layer SpatRaster representing the speed of water at a given location. Flow direction will be calculated from the world's DEM; or (3) A two layer SpatRaster or Raster* object, representing either the horizontal/vertical components of water velocity (in m/s) or the absolute water speed and flow direction (in that order; see uv).
water_speed	A character representing the column name in water that contains the average speed of the water in m/s. Required if water is a polygon.
uv	Logical. If TRUE (the default), a two-layer raster input for water is taken to be the horizontal and vertical components of water velocity. If false, a two-layer raster input for water is taken to be the water speed and flow direction.
priority	One of 'water' (the default), or 'land', indicating whether land values or water values should take precedence when values for a given location exist in both datasets.
overwrite	If a directory with a World subdirectory already exists, should the latter be overwritten? Default is overwrite = FALSE.
filt	Numeric. Size of moving window to apply a low-pass filter. Default is filt = 0. Ignored unless the tiles need to be generated from the raw source files.
dir	A filepath to the directory being used as the workspace. Default is tempdir() but unless the analyses will only be performed a few times it is highly recommended to define a permanent workspace.
cols	A character vector. Default is c("x_i","y_i","dz","dl","dr"), and dictates which columns are returned but final values for x and y and final/initial z values are also available
...	Additional arguments to pass to fix_z.

Details

It first checks to see if the required files contained within a '/World/' directory have already been created in the dir workspace. If not it creates them; if the '/World/' directory exists though, then an error is thrown (default) OR the user has the option to overwrite the directory.

The default parameters are sufficient for a workflow involving calculating costs with the calculateCosts function.

Value

A /World/ directory, containing /Loc/, /Diff/, and /Raw/, directories where cropped and transformed files will be stored, and /callVars.gz/, /z_sources/, /z_grid/, /z_fix.fst/, and /z_fix.fstproj/ files defining the world.

Examples

# Generate a DEM
n <- 5
dem <- expand.grid(list(x = 1:(n * 100),
                        y = 1:(n * 100))) / 100
dem <- as.data.table(dem)
dem[, z := 250 * exp(-(x - n/2)^2) + 
      250 * exp(-(y - n/2)^2)]
dem <- rast(dem)
ext(dem) <- c(10000, 20000, 30000, 40000)
crs(dem) <- "+proj=lcc +lat_1=48 +lat_2=33 +lon_0=-100 +datum=WGS84"

# Export it so it doesn't just exist on the memory
dir <- tempdir()
writeRaster(dem, paste0(dir,"/DEM.tif"),overwrite=TRUE)


# Import raster, get the grid
dem <- rast(paste0(dir,"/DEM.tif"))
grid <- makeGrid(dem = dem, nx = n, ny = n, sources = TRUE)

# Select all tiles that exist between x = (12000,16000) and y = (32000,36000)
tiles <- ext(c(12000,16000,32000,36000))
tiles <- as.polygons(tiles)
crs(tiles) <- crs(grid)
tiles <- whichTiles(region = tiles, polys = grid)

# Make a world but limit it to the DEM grid size
defineWorld(source = grid, cut_slope = 0.5, 
            res = res(dem), dir = dir, overwrite=TRUE)

andresgmejiar/lbmech documentation built on Feb. 2, 2025, 12:37 a.m.