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"
)
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()).
A Gridded or Vector dataset on which to do one or more of: crop, project, mask, and write
A Gridded or Vector dataset which is the object
whose metadata will be the target for cropping, projecting, and masking of from.
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
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
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
Optional character string of a filename to use writeRaster to save the final
object. Default is NULL, which means there is no writeRaster
Used if projectTo is not NULL, and is the method used for
interpolation. See terra::project. Defaults to "bilinear"
A character string, used if writeTo is not NULL. See raster::writeRaster
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.
See terra::mask
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
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.
Logical. Default FALSE. Used to convert from
back to these classes prior to writing.
The table below shows what will result from passing different classes to from
and to:
from | to | from will have: |
Gridded | Gridded | the extent, projection, origin, resolution and
masking where there are NA from the to |
Gridded | Vector | the 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 |
Vector | Vector | the 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.
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.
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.
This function is meant to replace postProcess() with the more efficient
and faster terra functions.