This function provides a single step to achieve the GIS operations "crop", "project", "mask" and possibly "write". This is intended to completely replace postProcess() (which primarily used GDAL, Raster and sp). It uses primarily the terra package internally (with some minor functions from sf and raster) in an attempt to be as efficient as possible. For this function, Gridded means a Raster* class object from raster or a SpatRaster class object from terra. Vector means a Spatial* class object from sp, a sf class object from sf, or a SpatVector class object from terra. This function is currently part of the internals for some cases encountered by postProcess().

postProcessTerra(
  from,
  to,
  cropTo = NULL,
  projectTo = NULL,
  maskTo = NULL,
  writeTo = NULL,
  method = NULL,
  datatype = "FLT4S",
  overwrite = TRUE,
  ...
)

maskTo(
  from,
  maskTo,
  touches = FALSE,
  overwrite = FALSE,
  verbose = getOption("reproducible.verbose")
)

projectTo(from, projectTo, method, overwrite = FALSE)

cropTo(
  from,
  cropTo = NULL,
  needBuffer = TRUE,
  overwrite = FALSE,
  verbose = getOption("reproducible.verbose")
)

writeTo(
  from,
  writeTo,
  overwrite,
  isStack = FALSE,
  isBrick = FALSE,
  isRaster = FALSE,
  isSpatRaster = FALSE,
  datatype = "FLT4S"
)

Arguments

from

A Gridded or Vector dataset on which to do one or more of: crop, project, mask, and write

to

A Gridded or Vector dataset which is the object whose metadata will be the target for cropping, projecting, and masking of from.

cropTo

Optional Gridded or Vector dataset which, if supplied, will supply the extent with which to crop from. To omit cropping completely, set this to NA. If supplied, this will override to for the cropping step. Defaults to NULL, which means use to

projectTo

Optional Gridded or Vector dataset, or crs object (e.g., sf::st_crs). If Gridded it will supply the crs, extent, res, and origin to project the from to. If Vector, it will provide the crs only. The resolution and extent will be taken from res(from) (i.e. ncol(from)*nrow(from)). If a Vector, the extent of the projectTo is not used (unless it is also passed to cropTo. To omit projecting, set this to NA. If supplied, this will override to for the projecting step. Defaults to NULL, which means use to

maskTo

Optional Gridded or Vector dataset which, if supplied, will supply the extent with which to mask from. If Gridded, it will mask with the NA values on the maskTo; if Vector, it will mask on the terra::aggregate(maskTo). To omit masking completely, set this to NA. If supplied, this will override to for the masking step. Defaults to NULL, which means use to

writeTo

Optional character string of a filename to use writeRaster to save the final object. Default is NULL, which means there is no writeRaster

method

Used if projectTo is not NULL, and is the method used for interpolation. See terra::project. Defaults to "bilinear"

datatype

A character string, used if writeTo is not NULL. See raster::writeRaster

overwrite

Logical. Used if writeTo is not NULL; also if terra determines that the object requires writing to disk during a crop, mask or project call e.g., because it is too large.

...

Currently can be either rasterToMatch, studyArea, filename2, useSAcrs, or targetCRS to allow backwards compatibility with postProcess. See section below for details.

touches

See terra::mask

verbose

Numeric, -1 silent (where possible), 0 being very quiet, 1 showing more messaging, 2 being more messaging, etc. Default is 1. Above 3 will output much more information about the internals of Caching, which may help diagnose Caching challenges. Can set globally with an option, e.g., options('reproducible.verbose' = 0) to reduce to minimal

needBuffer

Logical. Defaults to TRUE, meaning nothing is done out of the ordinary. If TRUE, then a buffer around the cropTo, so that if a reprojection has to happen on the cropTo prior to using it as a crop layer, then a buffer of 1.5 * res(cropTo) will occur prior, so that no edges are cut off.

isStack, isBrick, isRaster, isSpatRaster

Logical. Default FALSE. Used to convert from back to these classes prior to writing.

Value

An object of the same class as from, but potentially cropped (via cropTo()), projected (via projectTo()), masked (via maskTo()), and written to disk (via writeTo()).

Use Cases

The table below shows what will result from passing different classes to from and to:

fromtofrom will have:
GriddedGriddedthe extent, projection, origin, resolution and masking where there are NA from the to
GriddedVectorthe projection, origin, and mask from to, and extent will be a round number of pixels that fit within the extent of to. Resolution will be the same as from
VectorVectorthe projection, origin, extent and mask from to

If one or more of the *To arguments are supplied, these will override individual components of to. If to is omitted or NULL, then only the *To arguments that are used will be performed. In all cases, setting a *To argument to NA will prevent that step from happening.

Backwards compatibility with postProcess

rasterToMatch and studyArea:

If these are supplied, postProcessTerra will use them instead of to. If only rasterToMatch is supplied, it will be assigned to to. If only studyArea is supplied, it will be used for cropTo and maskTo; it will only be used for projectTo if useSAcrs = TRUE. If both rasterToMatch and studyArea are supplied, studyArea will only be applied to maskTo (and optionally projectTo if useSAcrs = TRUE); everything else will be from rasterToMatch.

targetCRS, filename2, useSAcrs:

targetCRS if supplied will be assigned to projectTo. filename2 will be assigned to writeTo. If useSAcrs is set, then the studyArea will be assigned to projectTo. All of these will override any existing values for these arguments.

Cropping

If cropTo is not NA, postProcessTerra does cropping twice, both the first and last steps. It does it first for speed, as cropping is a very fast algorithm. This will quickly remove a bunch of pixels that are not necessary. But, to not create bias, this first crop is padded by 2 * res(from)[1]), so that edge cells still have a complete set of neighbours. The second crop is at the end, after projecting and masking. After the projection step, the crop is no longer tight. Under some conditions, masking will effectively mask and crop in one step, but under some conditions, this is not true, and the mask leaves padded NAs out to the extent of the from (as it is after crop, project, mask). Thus the second crop removes all NA cells so they are tight to the mask.

See also

This function is meant to replace postProcess() with the more efficient and faster terra functions.