Our transition to terra from raster

We have been asked multiple times how we are “dealing with the transition from raster to terra”. The answer is, somewhat painfully and more slowly than we had hoped for.

Much of what we do involves manipulating spatial objects (raster or vector data) be it for data extraction (e.g., extracting data for statistical modelling), results production (e.g., outputting results spatially) or visualisation (e.g., making maps) and our packages and SpaDES modules were deeply intertwined with the raster and sp packages.

We have started the transition more than a year ago and still haven’t finished. Part of the reason why this takes so long is because we are attempting to keep backwards compatibility. Which take us to the purpose of this post.

Our advice to others in the same transition journey as us:

• Try to keep backwards compatibility. Many terra functions allow passing Raster* class objects. Where they don’t, make your own function wrappers to deal with this. We have a few in the reproducible and LandR (on GitHub) packages (see table bellow)

• Test. A LOT.

That’s all really.

Below is a lit of raster to terra (or other packages) function equivalencies that may be useful. Note that these are likely to change as terra and other packages evolve.

See also the description of terra methods for more useful information.

raster package	terra or other packages
ras[]	as.vector(ras[]) or as.vector(values(ras))
compareCRS	For now, LandR::.compareCRS – only 2 rasters LandR::.compareRas – multiple rasters
maxValue, minValue	minmax or reproducible::minFn, reproducible::maxFn
compareRaster	terra::compareGeom – more sensitive than st_crs(x) == st_crs(y) and returns false negatives in many situations. Alternatives are: sf::st_crs(x) == sf::st_crs(y) LandR::.compareRas LandR::.compareCRS
getValues	SpatRaster[] returns a matrix, even if it is just one layer; RasterLayer[] returns a vector; RasterStack[] returns a matrix For consistency, use: reproducible::values2 which replicates the old RasterLayer/RasterStack behaviour of vector if 1 layer, matrix if > 1 layer, using internally: terra::v alues(ras, mat = nlyr(ras) > 1) if ras is a RasterLayer
setValues	ras[] <-
extract, mask, ncell, cover	Same function names in terra, all compatible with RasterLayer and RasterStack
raster(ras)	Used to create a template raster. terra equivalent is: rast(ras) reproducible::rasterRead can use either, depending on value of getOp tion("reproducible.rasterRead")
raster(filepath)	Used to load a raster from a file. terra equivalent is rast(filepath) reproducible::rasterRead can use either, depending on value of getOp tion("reproducible.rasterRead")
layerNames	names
extent	terra::ext – compatible with RasterLayer and RasterStack
res	terra::res – compatible with RasterLayer and RasterStack
nlayers	length(names(ras)) or terra::nlyr; new transition function reproducible::nlayers2 works with either RasterLayer or SpatRaster
as.integer(ras)	Doesn’t work for SpatRaster. This also doesn’t work: ra s[] <- as.integer (ras[])ras <- LandR::asInt(ras) works on RasterLayer or SpatRaster LandR::isInt # the equivalent for is.integer
setColors	See terra::coltab
subs	terra::subst – but arguments are different
fasterize::fasterize	No equivalent for SpatVector objects yet. Use terra::rasterize but this appears to be slow at the moment. sf objects may need to be converted to a temporary SpatVector
SpaDES.core::Plots(ras)	Use SpaDES.core::Plot s(ras, fn = LandR::plotRast, …) available in LandR@development
quickPlot::Plot(ras)	quickPlot::Plot(ras) – accepts SpatRaster
raster::dataType	Equivalent in terra is datatype (notice different capitalization) reproducible::dataType2 works on RasterLayer and SpatRaster
xyFromCell	terra::xyFromCell(..., cell) does not accept a matrix for cell (unlike raster::xyFromCell). But passing as.vector(cell) will work with RasterLayer and SpatRaster
clump()	patches()
filename()	Equivalent in terra is sources() reproducible::Filenames() works on either RasterLayer or SpatRaster