# Transform a GIS dataset so it has the properties (extent, projection, mask) of another This 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, except if all inputs are `sf` objects. (in which case `sf` is used). 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()`. ```r 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"), ... ) ``` ## 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`. 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`). - `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` - `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. - `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` - `...`: 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 =`. If `reproducible.gdalwarp = TRUE`, then these will be passed to the `gdal*` functions. See them for details. - `needBuffer`: Logical. Defaults to `FALSE`, 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 `NULL`. Used to convert `from` back to these classes prior to writing, if provided. ## Returns 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()`). ## Details `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`. This function is meant to replace `postProcess()` with the more efficient and faster `terra` functions. ## Use Cases 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. ## `projectTo` Since 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. ## Backwards compatibility with `postProcess` ### `rasterToMatch` 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. ## Cropping 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. ## Examples ```r # prepare dummy data -- 3 SpatRasters, 2 SpatVectors # need 2 SpatRaster rf <- system.file("ex/elev.tif", package = "terra") elev1 <- terra::rast(rf) #' ras2 <- terra::deepcopy(elev1) ras2[ras2 > 200 & ras2 < 300] <- NA_integer_ terra::values(elev1) <- rep(1L, terra::ncell(ras2)) #' # a polygon vector f <- system.file("ex/lux.shp", package = "terra") vOrig <- terra::vect(f) v <- vOrig[1:2, ] #' utm <- terra::crs("epsg:23028") # $wkt vInUTM <- terra::project(vOrig, utm) vAsRasInLongLat <- terra::rast(vOrig, resolution = 0.008333333) res100 <- 100 rInUTM <- terra::rast(vInUTM, resolution = res100, vals = 1) # crop, reproject, mask, crop a raster with a vector in a different projection # --> gives message about not enough information t1 <- postProcessTo(elev1, to = vInUTM) # crop, reproject, mask a raster to a different projection, then mask t2a <- postProcessTo(elev1, to = vAsRasInLongLat, maskTo = vInUTM) # using gdal directly --> slightly different mask opts <- options(reproducible.gdalwarp = TRUE) t2b <- postProcessTo(elev1, to = vAsRasInLongLat, maskTo = vInUTM) t3b <- postProcessTo(elev1, to = rInUTM, maskTo = vInUTM) options(opts) ``` ## See Also `maskTo()`, `cropTo()`, `projectTo()`, `writeTo()`, and `fixErrorsIn()`. Also the functions that call `sf::gdal_utils(...)` directly: `gdalProject()`, `gdalResample()`, `gdalMask()`

postProcessTo function