terra-package: The terra package

Description

terra provides methods to manipulate geographic (spatial) data in "raster" and "vector" form. Raster data divide space into rectangular cells (pixels) and they are commonly used to represent spatially continuous phenomena, such as elevation or the weather. Satellite images also have this data structure. In contrast, "vector" spatial data (points, lines, polygons) are typically used to represent discrete spatial entities, such as a road, country, or bus stop.

The package implements two main classes (R data types): SpatRaster and SpatVector. SpatRaster supports handling large raster files that cannot be loaded into memory; local, focal, zonal, and global raster operations; polygon, line and point to raster conversion; integration with modeling methods to make spatial predictions; and more. SpatVector supports all types of geometric operations such as intersections.

Additional classes include SpatExtent, which is used to define a spatial extent (bounding box); SpatRasterDataset to represents a collection of sub-datasets for the same area. Each sub-dataset is a SpatRaster with possibly many layers, and may, for example, represent different weather variables; and SpatRasterCollection and SpatVectorCollection that are vectors of SpatRaster or SpatVector.

The classes used wrap a C++ pointer that holds pr points to the data, and almost all data manipulation is done in C++ (for better speed). These objects cannot be directly saved to a ".Rds" file or used in cluster computing. They cannot be recovered from a saved R session either. See pack or writeRaster to work around that limitation.

The terra package is conceived as a replacement of the raster package. terra has a very similar, but simpler, interface, and it is faster than raster. At the bottom of this page there is a table that shows differences in the methods between the two packages.

Below is a list of some of the most important methods grouped by theme. Some of these may not have been implemented yet (they are not hyperlinked).

Arguments

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

SpatRaster

---------------------------------------------------------------------------------------------------------------------

I. Creating, combining and sub-setting SpatRaster objects

`rast`	Create a SpatRaster from scratch, file, or another object
`c`	Combine SpatRasters (multiple layers)
`add<-`	Add a SpatRaster to another one
`subset` or `[[`, or `$`	Select layers of a SpatRaster
`selectRange`	Select cell values from different layers using an index layer
---------------------------	------------------------------------------------------------------------------------------

II. Changing the spatial extent and/or resolution of a SpatRaster

Also see the methods in section VIII

`merge`	Combine SpatRasters with different extents (but same origin and resolution)
`mosaic`	Combine SpatRasters with different extents and a function for the values in overlapping areas
`crop`	Select a geographic subset of a SpatRaster
`expand`	Enlarge a SpatRaster
`trim`	Trim a SpatRaster by removing exterior rows and/or columns that only have NAs
`aggregate`	Combine cells of a SpatRaster to create larger cells
`disaggregate`	Subdivide cells
`resample`	Resample (warp) values to a SpatRaster with a different origin and/or resolution
`project`	Project (warp) values to a SpatRaster with a different coordinate reference system
`shift`	Adjust the location of SpatRaster
`flip`	Flip values horizontally or vertically
`rotate`	Rotate values around the date-line (for lon/lat data)
`t`	Transpose a SpatRaster
---------------------------	------------------------------------------------------------------------------------------

III. Local (cell based) computation

`app`	Apply a function to cells, across layers (as in `base::apply`)
`tapp`	Apply a function to groups of layers (as in `base::tapply`)
`lapp`	Apply a function using the layers as variables
`rapp`	Apply a function to a spatially variable range of layers
`arith`	Use a function to compute new values for all cells
`Arith-methods`	Standard arithmetic methods (`+, -, *, ^, %%, %/%, /`)
`Math-methods`	Math methods like `abs, sqrt, trunc, log, log10, exp, sin, round`
`Logic-methods`	Boolean methods (`!, &, \|`)
`Summary-methods`	Summary methods (`mean, max, min, median, sum, range, prod, any, all, stdev, which.min, which.max`)
`Compare-methods`	Comparison methods (`==, !=, >, <, <=, >=`)
`area`	Compute the area of cells
`classify`	(Re-)classify values
`cover`	First layer covers second layer except where the first layer is `NA`
`init`	Initialize cells with new values
`mask`	Use values from first SpatRaster except where cells of the mask SpatRaster are `NA` (or another value of choice)
---------------------------	------------------------------------------------------------------------------------------

IV. Zonal and global computation

`area`	Compute the total area covered by cells
`crosstab`	Cross-tabulate two SpatRasters
`freq`	Frequency table of SpatRaster cell values
`global`	Summarize SpatRaster cell values with a function
`quantile`	Quantiles
`stretch`	Stretch values
`scale`	Scale values
`summary`	Summary of the values of a SpatRaster (quartiles and mean)
`unique`	Get the unique values in a SpatRaster
`zonal`	Summarize a SpatRaster by zones in another SpatRaster
---------------------------	------------------------------------------------------------------------------------------

V. Focal and other spatial contextual computation

`focal`	Focal (neighborhood; moving window) functions
`adjacent`	Identify cells that are adjacent to a set of cells of a SpatRaster
`boundaries`	Detection of boundaries (edges)
`distance`	Shortest distance to a cell that is not `NA` or to or from a vector object
`direction`	Direction (azimuth) to or from cells that are not `NA`
`localFun`	Local association (using neighborhoods) functions
`patches`	Find patches
`terrain`	Compute slope, aspect and other terrain characteristics from elevation data
`autocor`	Compute global or local spatial autocorrelation
---------------------------	------------------------------------------------------------------------------------------

VI. Model predictions

`predict`	Predict a non-spatial model to a SpatRaster
`interpolate`	Predict a spatial model to a SpatRaster
---------------------------	------------------------------------------------------------------------------------------

VII. Accessing cell values

Apart from the function listed below, you can also use indexing with [ with cell numbers, and row and/or column numbers

`values`	Get or set all cell values (fails with very large rasters)
`setValues`	Set new values to the cells of a SpatRaster
`as.matrix`	Get cell values as a matrix
`as.array`	Get cell values as an array
`extract`	Extract cell values from a SpatRaster (e.g., by cell, coordinates, polygon)
`spatSample`	Regular or random sample
`minmax`	Get the minimum and maximum value of the cells of a SpatRaster (if known)
`setMinMax`	Compute the minimum and maximum value of a SpatRaster if these are not known
`extract`	spatial queries of a SpatRaster with a SpatVector
---------------------------	------------------------------------------------------------------------------------------

VIII. Getting and setting SpatRaster dimensions

Get or set basic parameters of SpatRasters. If there are values associated with a SpatRaster object (either in memory or via a link to a file) these are lost when you change the number of columns or rows or the resolution. This is not the case when the extent is changed (as the number of columns and rows will not be affected). Similarly, with crs you can set the coordinate reference system, but this does not transform the data (see project for that).

`ncol`	The number of columns
`nrow`	The number of rows
`ncell`	The number of cells (can not be set directly, only via ncol or nrow)
`res`	The resolution (x and y)
`nlyr`	Get or set the number of layers
`names`	Get or set the layer names
`xres`	The x resolution (can be set with res)
`yres`	The y resolution (can be set with res)
`xmin`	The minimum x coordinate (or longitude)
`xmax`	The maximum x coordinate (or longitude)
`ymin`	The minimum y coordinate (or latitude)
`ymax`	The maximum y coordinate (or latitude)
`ext`	Get or set the extent (minimum and maximum x and y coordinates (a.k.a. "bounding box")
`origin`	The origin of a SpatRaster
`crs`	The coordinate reference system (map projection)
`is.lonlat`	Test if an object has (or may have) a longitude/latitude coordinate reference system; and if it has global coverage
`sources`	Get the filename(s) to which a SpatRaster is linked
`compareGeom`	Compare the geometry of SpatRasters
`NAflag`	Set the `NA` value (for reading from a file with insufficient metadata)
---------------------------	------------------------------------------------------------------------------------------

IX. Computing row, column, cell numbers and coordinates

Cell numbers start at 1 in the upper-left corner. They increase within rows, from left to right, and then row by row from top to bottom. Likewise, row numbers start at 1 at the top of the raster, and column numbers start at 1 at the left side of the raster.

`xFromCol`	x-coordinates from column numbers
`yFromRow`	y-coordinates from row numbers
`xFromCell`	x-coordinates from row numbers
`yFromCell`	y-coordinates from cell numbers
`xyFromCell`	x and y coordinates from cell numbers
`colFromX`	Column numbers from x-coordinates (or longitude)
`rowFromY`	Row numbers from y-coordinates (or latitude)
`rowColFromCell`	Row and column numbers from cell numbers
`cellFromXY`	Cell numbers from x and y coordinates
`cellFromRowCol`	Cell numbers from row and column numbers
`cellFromRowColCombine`	Cell numbers from all combinations of row and column numbers
`cells`	Cell numbers from an SpatVector or SpatExtent
---------------------------	------------------------------------------------------------------------------------------

X. Writing SpatRaster files

Basic
`writeRaster`	Write all values of SpatRaster to disk
.	`writeCDF`
Write netCDF files	.
Advanced
`blockSize`	Get suggested block size for reading and writing
`writeStart`	Open a file for writing
`writeValues`	Write some values
`writeStop`	Close the file after writing
---------------------------	------------------------------------------------------------------------------------------

XI. Miscellaneous SpatRaster methods

`terraOptions`	Show, set, save or get session options
`sources`	Show the data sources of a SpatRaster
`tmpFiles`	Show or remove temporary files
`canProcessInMemory`	Test whether a file can be created in memory
`readStart`	Open file connections for efficient multi-chunck reading
`readStop`	Close file connections
`inMemory`	Are the cell values in memory?
`fromDisk`	Are the cell values read from a file?
---------------------------	------------------------------------------------------------------------------------------

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

SpatRasterDataSet

---------------------------------------------------------------------------------------------------------------------

XII. SpatRasterDataset

A SpatRasterDataset contains SpatRaster objects that are sub-datasets for the same area. They all have the same extent and resolution.

`sds`	Create a SpatRasterDataset
`[` or `$`	Extract a SpatRaster
`names`	Get the names of the sub-datasets
---------------------------	------------------------------------------------------------------------------------------

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

SpatVector

---------------------------------------------------------------------------------------------------------------------

XIII. Create and combine SpatVector objects

`vect`	Create a SpatRaster from a file (e.g. shapefile) or from another object
`c`	append SpatVectors of the same geometry type ("rbind")
`unique`	remove duplicates
`project`	Project a SpatVector to a different coordinate reference system
`writeVector`	Write SpatVector data to disk
`centroids`	Get the centroids of a SpatVector
`voronoi`	Voronoi diagram
`delauny`	Delauny triangles
`convexhull`	Compute the convex hull of a SpatVector
`fill`	Remove or extract holes from polygons
---------------------------	------------------------------------------------------------------------------------------

XIV. Properties of SpatVector objects

`geom`	returns the geometries as matrix or WKT
`linearUnits`	returns the linear units of the crs (in meter)
`ncol`	The number of columns (of the attributes)
`nrow`	The number of rows (of the geometries and attributes)
`names`	Get or set the layer names
`ext`	Get the extent (minimum and maximum x and y coordinates (a.k.a. "bounding box")
`crs`	The coordinate reference system (map projection)
`is.lonlat`	Test if an object has (or may have) a longitude/latitude coordinate reference system; and if it has global coverage
---------------------------	------------------------------------------------------------------------------------------

XV. Geometric queries

`relate`	geometric relationships such as "intersects", "overlaps", and "touches"
`adjacent`	find adjacent polygons
`near`	find nearby geometries
`area`	computes the area covered by polygons
`perimeter`	computes the length of the perimeter of polygons, and the length of lines
---------------------------	------------------------------------------------------------------------------------------

XVI. Geometric operations

`erase` or "-"	erase (parts of) geometries
`intersect` or "*"	intersect geometries
`union` or "+"	Merge geometries
`cover`	update polygons
`symdif`	symmetrical difference of two polygons
`aggregate`	dissolve smaller polygons into larger ones
`buffer`	buffer geometries
`disaggregate`	split multi-geometries into separate geometries
`crop`	clip geometries using a rectangle (SpatExtent) or SpatVector
---------------------------	------------------------------------------------------------------------------------------

XVII. SpatVector attributes

`extract`	spatial queries between SpatVector and SpatVector (e.g. point in polygons)
`select`	select - interactively select geometries
`click`	identify attributes by clicking on a map
`merge`	Join a table with a SpatVector
`as.data.frame`	get attributes as a data.frame
---------------------------	------------------------------------------------------------------------------------------

XVIII. Change geometries (for display, experimentation)

`shift`	change the position geometries
`spin`	rotate geometries around an origin
`rescale`	shrink (or expand) geometries, for example to make an inset map
`flip`	flip geometries vertially or horizontally
`t`	transpose geometries (switch x and y)
---------------------------	------------------------------------------------------------------------------------------

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Spat* Collections

---------------------------------------------------------------------------------------------------------------------

XIX. Collections

A SpatRasterCollection is a vector of SpatRaster objects. Unlike for a SpatRasterDataset, there the extent and resolution of the elements do not need to match each other. A SpatVectorCollection is a vector of SpatVector objects.

`svc`	create a SpatRasterCollection
`length`	how many elements does the collection have?
`[`	extract an element

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

SpatExtent

---------------------------------------------------------------------------------------------------------------------

XX. SpatExtent

`extent`	Create a SpatExtent object
`intersect`	Intersect two SpatExtent objects, same as `-`
`union`	Combine two SpatExtent objects, same as `+`
`Math-methods`	round/floor/ceiling of a SpatExtent
`align`	Align a SpatExtent with a SpatRaster
`draw`	Create a SpatExtent by drawing it on top of a map (plot)

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

General methods

---------------------------------------------------------------------------------------------------------------------

XXI. Data type conversion

You can coerce SpatRasters to Raster* objects after loading the raster package with as(object, "Raster"), or raster(object) or brick(object) or stack(object)

`rast`	SpatRaster from matrix and other objects
`rasterize`	Rasterizing points, lines or polygons
`as.points`	Create points from a SpatRaster or SpatVector
`as.lines`	Create points from a SpatRaster or SpatVector
`as.polygons`	Create polygons from a SpatRaster
`as.contour`	Contour lines from a SpatRaster
---------------------------	------------------------------------------------------------------------------------------

XXII. Plotting

Maps
`plot`	Plot a SpatRaster or SpatVector. The main method to create a map
`points`	Add points to a map
`lines`	Add lines to a map
`polys`	Add polygons to a map
`plotRGB`	Combine three layers (red, green, blue channels) into a single "real color" image
`dots`	Make a dot-density map
`cartogram`	Make a cartogram
`image`	Alternative way to plot a SpatRaster
`persp`	Perspective plot of a SpatRaster
`contour`	Contour plot or filled-contour plot of a SpatRaster
`text`	Plot the values of a SpatRaster or SpatVector on top of a map
`inset`	Add a small inset (overview) map
`sbar`	Add a scalebar
.	Interacting with a map
	`zoom`
Zoom in to a part of a map	`click`
Query values of SpatRaster or SpatVector by clicking on a map	`select`
Select a spatial subset of a SpatRaster or SpatVector	`draw`
Create a SpatExtent or SpatVector by drawing on a map	.
Other plots
`plot`	x-y scatter plot of the values of two SpatRaster objects
`hist`	Histogram of SpatRaster values
`barplot`	Barplot of a SpatRaster
`density`	Density plot of SpatRaster values
`pairs`	Pairs plot for layers in a SpatRaster
`boxplot`	Box plot of the values of a SpatRaster

XXIII. Comparison with the raster package

terra has a single class SpatRaster for which raster has three (RasterLayer, RasterStack, RasterBrick). Likewise there is a single class for vector data SpatVector that replaces six Spatial* classes. Most method names are the same, but note the following important differences in methods names with the 'raster' package

raster package	terra package
`raster, brick, stack`	`rast`
`rasterFromXYZ`	`rast( , type="xyz")`
`stack, addLayer` (combining Raster* objects or files)	`c`
`addLayer`	`add<-`
`extent`	`ext`
`calc`	`app` and `arith`
`overlay`	`lapp`
`stackApply`	`tapp`
`extend`	`expand`
`nlayers`	`nlyr`
`NAvalue`	`NAflag`
`stackSelect`	`selectRange`
`reclassify, subs, cut`	`classify`
`cellStats`	`global`
`projectRaster`	`project`
`dropLayer`	`subset`
`isLonLat, isGlobalLonLat, couldBeLonLat`	`is.lonlat`
`shapefile`	`vect`
`gridDistance, distanceFromPoints`	`distance`
`drawExtent, drawPoly, drawLine`	`draw`
`compareRaster`	`compareGeom`
`sampleRandom, sampleRegular`	`spatSample`
`rasterToPoints`	`as.points`
`rasterToPolygons`	`as.polygons`
`cellFromLine, cellFromPolygon, cellsFromExtent`	`cells`
`layerize`	`separate`
`clump`	`patches`

Also note that even if function names are the same in terra and raster, their output can be different. In most cases to get more consistency in the returned values (and thus fewer errors in the downstream code that uses them). It other cases it simply seemed better. Here are some examples:

`area`	By default, `terra` returns the summed area of the raster cells that are not `NA`. `raster` returns a `RasterLayer`. Use `sum=FALSE` in `terra` for that behavior
-
`as.polygons`	By default, `terra` returns dissolved polygons
-
`extract`	By default, `terra` returns a matrix, with the first column the sequential ID of the vectors. `raster` returns a list (for lines or polygons) or a matrix (for points, but without the ID column. You can use `list=TRUE` to get the results as a list
-
`values`	`terra` always returns a matrix. `raster` returns a vector for a `RasterLayer`
-
`Summary-methods`	With `raster`, `mean(x, y)` and `mean(stack(x, y)` return the same result, a single layer with the mean of all cell values. This is also what `terra` returns with `mean(c(x, y))`, but with `mean(x, y)` the parallel mean is returned -- that is, the computation is done layer-wise, and the number of layers in the output is the same as that of `x` and `y` (or the larger of the two if they are not the same). This affects all summary functions (`sum`, `mean`, `median`, `which.min`, `which.max`, `min`, `max`, `prod`, `any`, `all`, `stdev`), except `range`, which is not implemented for this case (you can use `min` and `max` instead)

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Acknowledgments

This package is an attempt to climb on the shoulders of giants (GDAL, PROJ, GEOS, NCDF, GeographicLib, Rcpp, R). Many people have contributed by asking questions or filing bug reports. The feedback and suggestsions by Kendon Bell, Jean-Luc Dupouey, Gerald Nelson, and Michael Sumner have been especially helpful.