This function provides a single step to achieve the GIS operations "crop", "project", "mask" and possibly "write". 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.

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

cropTo(from, cropTo = NULL, needBuffer = TRUE)

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

A Vector dataset

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

...

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

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.

Value

An object of the same class as from, but potentially cropped, projected, masked, and written to disk.

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 on 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.