Description of the methods in the terra package

terra provides methods to manipulate geographic (spatial) data in "raster" and "vector" form. Raster data divide space into rectangular grid cells and they are commonly used to represent spatially continuous phenomena, such as elevation or the weather. Satellite images also have this data structure, and in that context grid cells are often referred to as pixels. 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 (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, which 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 equivalent to lists of SpatRaster or SpatVector objects. There is also a SpatGraticule class to assist in adding a longitude/latitude lines and labels to a map with another coordinate reference system.

These classes hold a C++ pointer to the data "reference class" and that creates some limitations. They cannot be recovered from a saved R session either or directly passed to nodes on a computer cluster. Generally, you should use writeRaster to save SpatRaster objects to disk (and pass a filename or cell values to cluster nodes). Also see wrap. Also, package developers should not directly access this pointer, as its user-interface is not stable.

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.

———————————————————————————————————————

SpatRaster

———————————————————————————————————————

I. Creating, combining and sub-setting

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 or resolution

Also see the methods in section VIII

merge	Combine SpatRasters with different extents (but same origin and resolution)
mosaic	Combine SpatRasters with different extents using a function for overlapping cells
crop	Select a geographic subset of a SpatRaster
extend	Add rows and/or columns to 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
disagg	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) methods

Apply-like methods

app	Apply a function to all cells, across layers, typically to summarize (as in base::apply)
tapp	Apply a function to groups of layers (as in base::tapply and stats::aggregate)
lapp	Apply a function to using the layers of a SpatRaster as variables
sapp	Apply a function to each layer
rapp	Apply a function to a spatially variable range of layers
—————————	——————————————————————————————

Arithmetic, logical, and standard math methods

Arith-methods	Standard arithmetic methods (+, -, *, ^, %%, %/%, /)
Compare-methods	Comparison methods for SpatRaster (==, !=, >, <, <=, >=m is.na, is.finite)
not.na	a one-step equivalent to !is.na
Summary-methods	mean, max, min, median, sum, range, prod,
	any, all, stdev, which.min, which.max, anyNA, noNA, allNA
Logic-methods	Boolean methods (!, &, |)
Math-methods	abs, sign, sqrt, ceiling, floor, trunc, cummax, cummin, cumprod,
	cumsum, log, log10, log2, log1p, acos, acosh, asin, asinh, atan, atanh,
	exp, expm1, cos, cosh, sin, sinh, tan, tanh, round, signif
as.bool	create a Boolean (logical) SpatRaster
as.int	create an integer (whole numbers) SpatRaster
—————————	——————————————————————————————

Other methods

approximate	Compute missing values for cells by interpolation across layers
roll	Rolling functions such as the rolling mean
clamp	Restrict cell values to a minimum and/or maximum value
cellSize	Compute the area of cells
classify	(Re-)classify values
subst	Substitute (replace) cell values
cover	First layer covers second layer except where the first layer is NA
init	Initialize cells with new values
mask	Replace values in a SpatRaster based on values in another SpatRaster
which.lyr	which is the first layer that is TRUE?
segregate	Make a 0/1 layer for each unique value
rangeFill	Make a 0/1 SpatRaster for a time series
regress	Cell-based regression models
—————————	——————————————————————————————

IV. Zonal and global methods

expanse	Compute the summed area of cells
crosstab	Cross-tabulate two SpatRasters
freq	Frequency table of SpatRaster cell values
global	Summarize SpatRaster cell values with a function
quantile	Quantiles
layerCor	Correlation between layers
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. Situation (spatial context) based methods

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
gridDist	Shortest distance through adjacent grid cells
costDist	Shortest distance considering cell-varying friction
direction	Direction (azimuth) to or from cells that are not NA
focal	Focal (neighborhood; moving window) functions
focal3D	Three dimensional (row, col, lyr) focal functions
focalCpp	Faster focal by using custom C++ functions
focalReg	Regression between layers for focal areas
focalPairs	Apply a function (e.g. a correlation coefficient) to focal values for pairs of layers
patches	Find patches (clumps)
sieve	Sieve filter to remove small patches
terrain	Compute slope, aspect and other terrain characteristics from elevation data
viewshed	Compute viewshed (showing areas that are visible from a particular location
shade	Compute hill shade from slope and aspect layers
autocor	Compute global or local spatial autocorrelation
—————————	——————————————————————————————

VI. Model predictions

predict	Predict a non-spatial (regression or classification) model to a SpatRaster
interpolate	Predict a spatial model to a SpatRaster
interpIDW	Inverse-distance-weighted interpolation
interpNear	Nearest neighbor interpolation
k_means	k-means clustering of SpatRaster data
princomp and prcomp	Principal Component Analysis (PCA) with raster data
—————————	——————————————————————————————

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	cell values (fails with very large rasters)
values<-	Set new values to the cells of a SpatRaster
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
as.data.frame	get cell values as a data.frame (including class lables)
extract	Extract cell values from a SpatRaster (with cell numbers, coordinates, points, lines, or polygons)
extractAlong	Extract cell values along a line such that the values are in the right order
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 dimensions

Get or set basic parameters of SpatRasters. If there are values associated with a SpatRaster (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 ("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
sources	Get the filename(s) to which a SpatRaster is linked
inMemory	Are the data sources in memory (or on disk)?
toMemory	Force data sources to memory (not recommended)?
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. Time related methods

time	Get or set time
fillTime	can add empty layers in between existing layers to assure that the time step between layers is constant
mergeTime	combine multiple rasters, perhaps partly overlapping in time, into a single time series
—————————	——————————————————————————————

XI. Methods for categorical rasters

is.factor	Are there categorical layers?
levels	Get active categories, or set categories
activeCat	Get or set the active category
cats	Get categories (active and inactive)
set.cats	Set categories in place
concats	Combine SpatRasters with different categories
catalyze	Create a layer for each category
as.numeric	use the active category to create a non-categorical SpatRaster
as.factor	Make the layers of a SpatRaster categorical
—————————	——————————————————————————————

XII. Writing SpatRaster files

Basic

writeRaster	Write all values of SpatRaster to disk. You can set the filetype, datatype, compression.
writeCDF	Write SpatRaster data to a netCDF file
—————————	——————————————————————————————

Advanced

readStart	Open file connections for efficient multi-chunk reading
readValues	Read some values from an opened file
readStop	Close file connections
writeStart	Open a file for writing
writeValues	Write some values to an opened file
writeStop	Close the file after writing
blocks	Get blocksize for reading files (when not writing)
—————————	——————————————————————————————

XIII. Miscellaneous SpatRaster methods

terraOptions	Show, set, or get session options, mostly to control memory use and to set write options
sources	Show the data sources of a SpatRaster
tmpFiles	Show or remove temporary files
mem_info	memory needs and availability
inMemory	Are the cell values in memory?
—————————	——————————————————————————————

XIV. SpatRasterDataset

A SpatRasterDataset contains SpatRasters that represent sub-datasets for the same area. They all have the same extent and resolution.

sds	Create a SpatRasterDataset from a file with subdatasets (ncdf or hdf) or from SpatRasters
[ or $	Extract a SpatRaster
names	Get the names of the sub-datasets
—————————	——————————————————————————————

XV. SpatRasterCollections

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

sprc	create a SpatRasterCollection from (a list of) SpatRasters
length	how many SpatRasters does the SpatRasterCollection have?
crop	crop a SpatRasterCollection
impose	force the members of SpatRasterCollection to the same geometry
merge	merge the members of a SpatRasterCollection
mosaic	mosaic (merge with a function for overlapping areas) the members of a SpatRasterCollection
[	extract a SpatRaster
—————————	——————————————————————————————

SpatVector

———————————————————————————————————————

XVI. Create SpatVector objects

vect	Create a SpatVector from a file (for example a "shapefile") or from another object
vector_layers	list or delete layers in a vector database such as GPGK
rbind	append SpatVectors of the same geometry type
unique	remove duplicates
na.omit	remove empty geometries and/or fields that are NA
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
delaunay	Delaunay triangles
convHull	Compute the convex hull of a SpatVector
minRect	Compute the minimum minimal bounding rotated rectangle of a SpatVector
minCircle	Compute the minimal bounding circle of a SpatVector
fillHoles	Remove or extract holes from polygons
—————————	——————————————————————————————

XVII. Properties of SpatVector objects

geom	returns the geometries as matrix or WKT
crds	returns the coordinates as a matrix
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 ("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
—————————	——————————————————————————————

XVIII. Geometric queries

adjacent	find adjacent polygons
expanse	computes the area covered by polygons
nearby	find nearby geometries
nearest	find the nearest geometries
relate	geometric relationships such as "intersects", "overlaps", and "touches"
perim	computes the length of the perimeter of polygons, and the length of lines
—————————	——————————————————————————————

XIX. 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
disagg	split multi-geometries into separate geometries
crop	clip geometries using a rectangle (SpatExtent) or SpatVector
—————————	——————————————————————————————

XX. SpatVector attributes

We use the term "attributes" for the tabular data (data.frame) associated with vector geometries.

extract	spatial queries between SpatVector and SpatVector (e.g. point in polygons)
sel	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
as.list	get attributes as a list
values	Get the attributes of a SpatVector
values<-	Set new attributes to the geometries of a SpatRaster
sort	sort SpatVector by the values in a field
—————————	——————————————————————————————

XXI. Change geometries (for display, experimentation)

shift	change the position geometries by shifting their coordinates in horizontal and/or vertical direction
spin	rotate geometries around an origin
rescale	shrink (or expand) geometries, for example to make an inset map
flip	flip geometries vertically or horizontally
t	transpose geometries (switch x and y)
—————————	——————————————————————————————

XXII. Geometry properties and topology

width	the minimum diameter of the geometries
clearance	the minimum clearance of the geometries
sharedPaths	shared paths (arcs) between line or polygon geometries
simplifyGeom	simplify geometries
gaps	find gaps between polygon geometries
fillHoles	get or remove the polygon holes
makeNodes	create nodes on lines
mergeLines	connect lines to form polygons
removeDupNodes	remove duplicate nodes in geometries and optionally rounds the coordinates
is.valid	check if geometries are valid
makeValid	attempt to repair invalid geometries
snap	make boundaries of geometries identical if they are very close to each other
erase (single argument)	remove parts of geometries that overlap
union (single argument)	create new polygons such that there are no overlapping polygons
rotate	rotate to (dis-) connect them across the date-line
normalize.longitude	move geometries that are outside of the -180 to 180 degrees range.
elongate	make lines longer by extending both sides
combineGeoms	combine geometries that overlap, share a border, or are within a minimum distance of each other
forceCCW	force counter-clockwise polygon winding
—————————	——————————————————————————————

XXIII. SpatVectorCollections

A SpatVectorCollection is a vector of SpatVector objects.

svc	create a SpatVectorCollection from (a list of) SpatVector objects
length	how many SpatRasters does the SpatRasterCollection have?
[	extract a SpatVector
—————————	——————————————————————————————

Other classes

———————————————————————————————————————

XXIV. SpatExtent

ext	Create a SpatExtent object. For example to crop a Spatial dataset
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)
—————————	——————————————————————————————

XXV. SpatGraticule

graticule	Create a graticule
crop	crop a graticule
plot<SpatGraticule>	plot a graticule
—————————	——————————————————————————————

General methods

———————————————————————————————————————

XXVI. Conversion between spatial data objects from different packages

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
vect	SpatVector from sf or Spatial* vector data
sf::st_as_sf	sf object from SpatVector
rasterize	Rasterizing points, lines or polygons
rasterizeWin	Rasterize points with a moving window
rasterizeGeom	Rasterize attributes of geometries such as "count", "area", or "length"
as.points	Create points from a SpatRaster or SpatVector
as.lines	Create lines from a SpatRaster or SpatVector
as.polygons	Create polygons from a SpatRaster
as.contour	Contour lines from a SpatRaster
—————————	——————————————————————————————

XXVII. Plotting

Maps

plot	Plot a SpatRaster or SpatVector. The main method to create a map
panel	Combine multiple plots
points	Add points to a map
lines	Add lines to a map
polys	Add polygons to a map
text	Add text (such as the values of a SpatRaster or SpatVector) to a map
halo	Add text with a halo to a map
map.pal	Color palettes for mapping
image	Alternative to plot to make a map with a SpatRaster
plotRGB	Combine three layers (red, green, blue channels) into a single "real color" plot
plot<SpatGraticule>	plot a graticule
sbar	Add a scale bar to a map
north	Add a north arrow to a map
inset	Add a small inset (overview) map
add_legend	Add a legend to a map
add_box	Add a bounding box to a map
map_extent	Get the coordinates of a map's axes positions
dots	Make a dot-density map
cartogram	Make a cartogram
persp	Perspective plot of a SpatRaster
contour	Contour plot or filled-contour plot of a SpatRaster
colorize	Combine three layers (red, green, blue channels) into a single layer with a color-table
—————————	——————————————————————————————

Interacting with a map

zoom	Zoom in to a part of a map by drawing a bounding box on it
click	Query values of SpatRaster or SpatVector by clicking on a map
sel	Select a spatial subset of a SpatRaster or SpatVector by drawing on a map
draw	Create a SpatExtent or SpatVector by drawing on a map
—————————	——————————————————————————————

Other plots

plot	x-y scatter plot of the values of (a sample of) the layers of two SpatRaster objects
hist	Histogram of SpatRaster values
barplot	Bar plot 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
—————————	——————————————————————————————

Comparison with the raster package

———————————————————————————————————————

XXVIII. New method names

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	c
addLayer	add<-
area	cellSize or expanse
approxNA	approximate
calc	app
cellFromLine, cellFromPolygon,	cells
cellsFromExtent	cells
cellStats	global
clump	patches
compareRaster	compareGeom
corLocal	focalPairs
coordinates	crds
couldBeLonLat	is.lonlat
disaggregate	disagg
distanceFromPoints	distance
drawExtent, drawPoly, drawLine	draw
dropLayer	subset
extent	ext
getValues	values
isLonLat, isGlobalLonLat	is.lonlat
layerize	segregate
layerStats	layerCor
movingFun	roll
NAvalue	NAflag
nlayers	nlyr
overlay	lapp
unstack	as.list
projectRaster	project
rasterToPoints	as.points
rasterToPolygons	as.polygons
readAll	toMemory
reclassify, subs, cut	classify
sampleRandom, sampleRegular	spatSample
shapefile	vect
stackApply	tapp
stackSelect	selectRange

XXIX. Changed behavior

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

as.polygons	By default, terra returns dissolved polygons
quantile	computes by cell, across layers instead of the other way around
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)
—————————	——————————————————————————————

Authors

Except where indicated otherwise, the methods and functions in this package were written by Robert Hijmans. The configuration scripts were written by Roger Bivand. Some of code using the GEOS library was adapted from code by Edzer Pebesma for sf. Michael Sumner contributed various bits and pieces.

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 raising issues. Feedback and suggestions by Márcia Barbosa, Kendon Bell, Andrew Gene Brown, Jean-Luc Dupouey, Krzysztof Dyba, Sarah Endicott, Derek Friend, Alex Ilich, Gerald Nelson, Jakub Nowosad, and Monika Tomaszewska have been especially helpful.