v_match_rasters: Matching the reference coordinate system, extension,...
In BlasBenito/sdmflow: Streamlining the Development of Species Distribution Models

Description Usage Arguments Details Value Author(s)

View source: R/v_match_rasters.R

Raster files from different sources may have different reference coordinate systems, extensions, resolutions, and valid cells. However, species distribution models require all rasters to have the same features, and this function facilitates the tedious task of processing raster layers so they can be used in species distribution modelling exercises.

v_match_rasters(
 raster.template = NULL,
 raster.template.crs = "+init=epsg:4326",
 input.folder,
 output.folder,
 default.crs = "+init=epsg:4326",
 n.cores = NULL
 )

`raster.template`	Complete path to a raster file or raster object in the R environment to be used as a template. All rasters in `input.folder` will be adjusted to the coordinate reference system, exent, and resolution of this raster layer.
`raster.template.crs`	Character string in proj4string format defining a coordinate reference system of `raster.template`. Only required when the raster format of the template does not contain this information (as it happens with .asc files). The default crs is "+init=epsg:4326", valid latitude-longitude data according the global datum WGS84.
`input.folder`	Character string, path (without final slash) to the folder containing the raster files to be matched, or folder containing subfolders, each one containing raster files representing data from different times.
`output.folder`	Character string, path (without final slash) of the folder where the matched rasters will be written. Defaults to "/matched_rasters" in the working directory if nothing else is provided
`default.crs`	Default coordinate system for those files in `input.folder` that don't have one. The default value is `"+init=epsg:4326"`, as in `raster.template.crs`. Use this argument with care!
`n.cores`	Integer, number of cores to be used during the matching operations. If the target rasters are very large, and the RAM memory available is low, `n.cores` should be low as well.

This function requires a raster.template, which is a raster file stored in the hard disk or a raster object in the R environment having the desired properties.

If the template file does not contain information about the coordinate reference system (.asc files don't), the user must define the argument raster.template.crs, which takes a character string following the proj4string. The easiest way to do this is by using the EPSG code of the given coordinate reference system. For example, for for latitude-longitude data based on the datum WGS84, the usual proj4string format would be "+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs". The EPSG alternative is "+init=epsg:4326", way shorter and easier to remember. Note that this argument is not required if the file format of raster.template already contains information about the coordinate reference system. This is the case with geotif files (.tif extension) and many others.

The input.folder argument is either:

The path to the folder containing the raster files to be matched. For example, the folder ".../my_rasters" containing the rasters "temperature.tif" and "rainfall.tif"). This is named 4D data (x, y, variable values, and variable names) in this package.
The path to the folder containing the subfolders with the rasters representing different times. For example, the folder ".../my_rasters" containing the subfolders "2019" and "2020", each one containing the rasters "temperature.tif" and "rainfall.tif" of the respective years. This is named 5D data (x, y, variable values, variable names, and times). In this case, the sub-folders with the matched rasters are written to output.path.

When the data is separated in subfolders representing different times, the mask (spatial distribution of no-data values) for each subfolder is computed separately. This allows different times to have different masks. This is especially useful when different times may have very different masks, as it is the case between the present time and the Last Glacial Maximum.

This function relies on the following functions of the raster package:

projectRaster: to reproject any given raster to the same coordinate reference system, extension and resolution as raster.template when they do not have the same crs.
resample: to adjust a raster to the extension and resolution of raster.template when they have the same crs.
crop: to adjust a raster to the extension of raster.template when they have the same crs and resolution.
mask: to apply a common mask to all rasters.
trim: to remove NA values from the border of the rasters.
raster: to import raster files from disk into R.
crs: to set the coordinate reference system of layers that do not have any.

The function writes the matched rasters to output.folder in R format, with the extensions .grd and .gri. These rasters can be imported directly with raster::raster() and outside of R with Quantum GIS.

The function also returns an object of the class "environmental.data" with a slot named "meta" containing a data frame with information (metadata) that helps to trace the transformations applied to each raster file. This output can be used down the line by v_import_rasters to import the matched rasters into the R session. The object has two variants:

**4D** variant: If input.folder contains raster files, the output object has the attribute "4D", and the "meta" slot contains a data frame with metadata.
**5D** variant: If input.folder contains sub-folders with raster files representing different times, the output object has the attribute "5D", and the "meta" slot has sub-slots named after the different sub-folders, and each one contains the data frame with the metadata of the operations applied for each particular folder.

Blas Benito <blasbenito@gmail.com>. The functions raster, crs, projectRaster, resample, crop, mask, and trim are authored by Robert J. Hijmans.