R/postProcessTo.R
postProcessTo.RdThis function provides a single step to achieve the GIS operations
"pre-crop-with-buffer-to-speed-up-projection", "project",
"post-projection-crop", "mask" and possibly "write".
It uses primarily the terra package internally
(with some minor functions from sf)
in an attempt to be as efficient as possible. Currently, this function is tested
with sf, SpatVector, SpatRaster, Raster* and Spatial* objects passed
to from, and the same plus SpatExtent, and crs passed to to or the
relevant *to functions.
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 also used internally with the deprecated family postProcess(),
*Inputs, such as cropInputs().
postProcessTo(
from,
to,
cropTo = NULL,
projectTo = NULL,
maskTo = NULL,
writeTo = NULL,
overwrite = TRUE,
verbose = getOption("reproducible.verbose"),
...
)
postProcessTerra(
from,
to,
cropTo = NULL,
projectTo = NULL,
maskTo = NULL,
writeTo = NULL,
overwrite = TRUE,
verbose = getOption("reproducible.verbose"),
...
)
maskTo(
from,
maskTo,
overwrite = FALSE,
verbose = getOption("reproducible.verbose"),
...
)
projectTo(
from,
projectTo,
overwrite = FALSE,
verbose = getOption("reproducible.verbose"),
...
)
cropTo(
from,
cropTo = NULL,
needBuffer = FALSE,
overwrite = FALSE,
verbose = getOption("reproducible.verbose"),
...
)
writeTo(
from,
writeTo,
overwrite = getOption("reproducible.overwrite"),
isStack = NULL,
isBrick = NULL,
isRaster = NULL,
isSpatRaster = NULL,
verbose = getOption("reproducible.verbose"),
...
)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.
Attention. Conflicts may arise with when projectTo is a Vector/CRS object with a
distinct CRS from to. Because to is used for masking after from is re-projected using
projectTo, the extents of to and from may no longer overlap (as in align)
perfectly leading to failure during
the masking step. We recommend passing a raster templates to projectTo whose extent and CRS
are both compatible with the object used later for masking (either to or 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
Optional character string of a filename to use writeRaster to save the final
object. Default is NULL, which means there is no 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.
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
Arguments passed to terra::mask (for maskTo), terra::project (for projectTo)
or terra::writeRaster (for writeTo) and not used for cropTo, as well postProcess's
rasterToMatch and studyArea arguments (see below). Commonly used arguments might be
method, touches, and datatype. If filename is passed, it will be ignored; use
writeTo = .
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 NULL. Used to convert from
back to these classes prior to writing, if provided.
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()).
postProcessTo is a wrapper around (an initial "wide" crop for speed)
cropTo(needBuffer = TRUE), projectTo,
cropTo (the actual crop for precision), maskTo, writeTo.
Users can call each of these individually.
postProcessTerra is the early name of this function that is now postProcessTo.
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. See section
below about projectTo. |
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.
projectToSince these functions use the gis capabilities of sf and terra, they will only
be able to do things that those functions can do. One key caution, which is
stated clearly in ?terra::project is that projection of a raster (i.e., gridded)
object should always be with another gridded object. If the user chooses to
supply a projectTo that is a vector object for a from that is gridded,
there may be unexpected failures due e.g., to extents not overlapping during
the maskTo stage.
postProcessrasterToMatch and studyArea:If these are supplied, postProcessTo 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 (unless maskWithRTM = TRUE),
and, optionally, to projectTo (if useSAcrs = TRUE); everything else
will be from rasterToMatch.
targetCRS, filename2, useSAcrs, maskWithRTM: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. If maskWithRTM is used, then the
rasterToMath will be assigned to maskTo. All of these will override
any existing values for these arguments.
See also postProcess() documentation section on
Backwards compatibility with rasterToMatch and/or studyArea for further
detail.
If cropTo is not NA, postProcessTo 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.