Generic function to post process objects

The method for spatialClasses (Raster* and Spatial*) will crop, reproject, and mask, in that order. This is a wrapper for cropInputs(), fixErrors(), projectInputs(), maskInputs() and writeOutputs(), with a decent amount of data manipulation between these calls so that the crs match.

postProcess(x, ...)

# S3 method for default
postProcess(x, ...)

# S3 method for list
postProcess(x, ...)

# S3 method for spatialClasses
postProcess(
  x,
  filename1 = NULL,
  filename2 = NULL,
  studyArea = NULL,
  rasterToMatch = NULL,
  overwrite = getOption("reproducible.overwrite", TRUE),
  useSAcrs = FALSE,
  useCache = getOption("reproducible.useCache", FALSE),
  verbose = getOption("reproducible.verbose", 1),
  ...
)

# S3 method for sf
postProcess(
  x,
  filename1 = NULL,
  filename2 = NULL,
  studyArea = NULL,
  rasterToMatch = NULL,
  overwrite = getOption("reproducible.overwrite", TRUE),
  useSAcrs = FALSE,
  useCache = getOption("reproducible.useCache", FALSE),
  verbose = getOption("reproducible.verbose", 1),
  ...
)

Arguments

x

An object of postProcessing, e.g., spatialClasses. See individual methods. This can be provided as a rlang::quosure or a normal R object.

...

Additional arguments passed to methods. For spatialClasses, these are: cropInputs(), fixErrors(), projectInputs(), maskInputs(), determineFilename(), and writeOutputs(). Each of these may also pass ... into other functions, like raster::writeRaster(), or sf::st_write. This might include potentially important arguments like datatype, format. Also passed to projectRaster, with likely important arguments such as method = "bilinear". See details.

... passed to:

cropInputs:

raster::crop()

projectInputs

raster::projectRaster()

maskInputs

fastMask() or raster::intersect()

fixErrors

raster::buffer()

writeOutputs

raster::writeRaster() or raster::shapefile()

determineFilename

• Can be overridden with useSAcrs ** Will mask with NAs from rasterToMatch if maskWithRTM

filename1

Character strings giving the file paths of the input object (filename1) filename1 is only used for messaging (i.e., the object itself is passed in as x) and possibly naming of output (see details and filename2).

filename2

filename2 is optional, and is either NULL (no writing of outputs to disk), or several options for writing the object to disk. If TRUE (the default), it will give it a file name determined by .prefix(basename(filename1), prefix). If a character string, it will use this as its file name. See determineFilename().

studyArea

SpatialPolygons* object used for masking and possibly cropping if no rasterToMatch is provided. If not in same CRS, then it will be spTransformed to CRS of x before masking. Currently, this function will not reproject the x. Optional in postProcess.

rasterToMatch

Template Raster* object used for cropping (so extent should be the extent of desired outcome) and reprojecting (including changing the resolution and projection). See details in postProcess().

overwrite

Logical. Should downloading and all the other actions occur even if they pass the checksums or the files are all there.

useSAcrs

Logical. If FALSE, the default, then the desired projection will be taken from rasterToMatch or none at all. If TRUE, it will be taken from studyArea. See table in details below.

useCache

Passed to Cache in various places. Defaults to getOption("reproducible.useCache", 2L) in prepInputs, and getOption("reproducible.useCache", FALSE) if calling any of the inner functions manually. For prepInputs, this mean it will use Cache only up to 2 nested levels, which will generally including postProcess and the first level of *Input functions, e.g., cropInputs, projectInputs, maskInputs, but not fixErrors.

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

Value

A GIS file (e.g., RasterLayer, SpatRaster etc.) that has been appropriately cropped, reprojected, masked, depending on the inputs.

Post processing sequence

If the rasterToMatch or studyArea are passed, then the following sequence will occur:

1. Fix errors fixErrors(). Currently only errors fixed are for SpatialPolygons using buffer(..., width = 0).

2. Crop using cropInputs()

3. Project using projectInputs()

4. Mask using maskInputs()

5. Determine file name determineFilename()

6. Write that file name to disk, optionally writeOutputs()

NOTE: checksumming does not occur during the post-processing stage, as there are no file downloads. To achieve fast results, wrap prepInputs with Cache

NOTE: sf objects are still very experimental.

Passing rasterToMatch and/or studyArea

Depending on which of these were passed, different things will happen to the targetFile located at filename1.

If targetFile is a Raster* object:

	rasterToMatch	studyArea	Both
extent	Yes	Yes	rasterToMatch
resolution	Yes	No	rasterToMatch
projection	Yes	No*	rasterToMatch*
alignment	Yes	No	rasterToMatch
mask	No**	Yes	studyArea**

• Can be overridden with useSAcrs. ** Will mask with NAs from rasterToMatch if maskWithRTM.

If targetFile is a Spatial* object:

	rasterToMatch	studyArea	Both
extent	Yes	Yes	rasterToMatch
resolution	NA	NA	NA
projection	Yes	No*	rasterToMatch*
alignment	NA	NA	NA
mask	No	Yes	studyArea

• Can be overridden with useSAcrs

See also

prepInputs

Examples

# Add a study area to Crop and Mask to
# Create a "study area"
library(sp)
library(raster)
ow <- setwd(tempdir())

# make a SpatialPolygon
coords1 <- structure(c(-123.98, -117.1, -80.2, -100, -123.98, 60.9, 67.73, 65.58, 51.79, 60.9),
                     .Dim = c(5L, 2L))
Sr1 <- Polygon(coords1)
Srs1 <- Polygons(list(Sr1), "s1")
shpEcozone <- SpatialPolygons(list(Srs1), 1L)
crs(shpEcozone) <- "+proj=longlat +datum=WGS84 +no_defs +ellps=WGS84 +towgs84=0,0,0"

# make a "study area" that is subset of larger dataset
coords <- structure(c(-118.98, -116.1, -99.2, -106, -118.98, 59.9, 65.73, 63.58, 54.79, 59.9),
                    .Dim = c(5L, 2L))
Sr1 <- Polygon(coords)
Srs1 <- Polygons(list(Sr1), "s1")
StudyArea <- SpatialPolygons(list(Srs1), 1L)
crs(StudyArea) <- crs(shpEcozone)
projString <- "+proj=utm +zone=15 +ellps=GRS80 +datum=NAD83 +units=m +no_defs"
StudyArea <- sp::spTransform(StudyArea, CRSobj = projString)

##########
shpEcozonePostProcessed <- postProcess(shpEcozone, studyArea = StudyArea)
#>   useCache is FALSE; skipping Cache on function cropInputs (currently running nested Cache level 2)
#>     cropping ...
#> No cachePath supplied and getOption('reproducible.cachePath') is inside a temporary directory;
#>   this will not persist across R sessions.
#>     reprojecting ...
#> maskInputs with sf class objects is still experimental
#>     intersecting ...
#> Checking for errors in SimpleFeature
#>   Found no errors.
#> Checking for errors in SimpleFeature
#>   Found no errors.
#>   Skipping writeOutputs; filename2 is NULL


# Try manually, individual pieces
shpEcozoneReprojected <- projectInputs(shpEcozone, StudyArea)
#>     reprojecting ...
shpEcozoneCropped <- cropInputs(shpEcozone, StudyArea)
#>     cropping ...
shpEcozoneClean <- fixErrors(shpEcozone)
#> Checking for errors in SpatialPolygon
#>   Found no errors.
shpEcozoneMasked <- maskInputs(shpEcozone, StudyArea)
#> maskInputs with sf class objects is still experimental
#>     intersecting ...
#> Checking for errors in SimpleFeature
#>   Found no errors.
#> Checking for errors in SimpleFeature
#>   Found no errors.

# With terra
if (require("terra")) {
  opts <- options("reproducible.useTerra" = TRUE)
  vectEcozone <- terra::vect(shpEcozone)

  # If input is Spatial object --> return will also be Spatial
  shpEcozonePostProcessed <- postProcess(shpEcozone, studyArea = StudyArea)
  # Try manually, individual pieces -- Note functions are different
  shpEcozoneReprojected <- projectInputs(shpEcozone, StudyArea)
  shpEcozoneMasked <- maskInputs(shpEcozone, StudyArea)
  shpEcozoneCropped <- cropInputs(shpEcozone, StudyArea)

  # If input is Spat object --> return will also be Spat
  vectEcozonePostProcessed <- postProcess(vectEcozone, studyArea = StudyArea)
  # Try manually, individual pieces -- Note functions are different
  vectEcozoneMasked <- maskInputs(vectEcozone, StudyArea)
  VectEcozoneReprojected <- projectInputs(vectEcozone, StudyArea)
  vectEcozoneCropped <- cropInputs(vectEcozone, StudyArea)

  # fixErrorsTerra --> generally not called on its own
  shpEcozoneClean <- fixErrorsTerra(vectEcozone)

  options(opts)
}
#> Loading required package: terra
#> terra 1.6.47
#> 
#> Attaching package: ‘terra’
#> The following objects are masked from ‘package:magrittr’:
#> 
#>     extract, inset
#> studyArea is supplied (deprecated); assigning it to `cropTo` & `maskTo`
#>     cropping...
#> ...done in 0.02 secs
#>     masking...
#> ...done in 0.00132 secs
#>     cropping...
#> ...done in 0.0175 secs
#>   postProcessTerra done in 0.0747 secs
#>     reprojecting ...
#>     projecting...
#> done in 0.0543 secs
#>     masking...
#> ...done in 0.00134 secs
#>     cropping...
#> ...done in 0.0181 secs
#> studyArea is supplied (deprecated); assigning it to `cropTo` & `maskTo`
#>     cropping...
#> ...done in 0.0181 secs
#>     masking...
#> ...done in 0.00131 secs
#>     cropping...
#> ...done in 0.0177 secs
#>   postProcessTerra done in 0.052 secs
#>     masking...
#> ...done in 0.00131 secs
#>     projecting...
#> done in 0.0307 secs
#>     cropping...
#> ...done in 0.0177 secs

setwd(ow)