terra (version 0.4-3)

terra-package: The "terra" package

Description

The "terra" package implements classes for spatial data (see SpatRaster-class) and supports handling large raster files that cannot be loaded into memory; local, focal, zonal, and global raster operations; polylygon, line and point to raster conversion; integration with modeling methods to make spatial predictions; and more.

The package is conceived as a replacement of the "raster" package. It has a very similar, but simpler, interface, and it is faster. Like the "raster" package, "terra" provides classes and functions to manipulate geographic (spatial) data in "raster" and "vector". Raster data divides space into cells (rectangles; pixels) of equal size (in units of the coordinate reference system). Such continuous spatial data are also referred to as "grid" data, and be contrasted with discrete "vector" spatial data such as points, lines, polygons. An important difference is that "terra" has a single main class for raster data, "SpatRaster", as opposed to the three classes in the "raster" package (RasterLayer, RasterStack, RasterBrick).

Note the following important differences in function names with the raster package

raster package	terra package
raster, brick	rast
stack (for creating an object from file)	rast
stack (for combining Raster* objects)	c
rasterFromXYZ	rast( , type="xyz")
extent	ext
calc	app
stackApply	tapp
reclassify, subs, cut	classify
cellStats	global
projectRaster	warp, project
shapefile	vect
gridDistance, distanceFromPoints	distance
drawExtent, drawPoly, drawLine	draw
nlayers	nlyr
stackSelect	collapse
compareRaster	compareGeom
sampleRegular	spatSample

The package should be particularly useful when using very large datasets that can not be loaded into the computer's memory. Functions will work correctly, because they they process large files in chunks, i.e., they read, compute, and write blocks of data, without loading all values into memory at once.

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

I. Creating SpatRaster objects

SpatRaster objects can be created, from scratch, files, or from objects of other classes, with the following functions:

rast	Create a SpatRaster from scratch, file, or another object
c	Combine SpatRasters (multiple layers) (like raster::stack)
subset	Select layers of a SpatRaster
---------------------------	------------------------------------------------------------------------------------------

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

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
extend	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
warp	Warp values to a SpatRaster with a different origin and/or resolution and/or 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

Arith-methods	Arith functions (+, -, *, ^, %%, %/%, /)
Math-methods	Math functions like abs, sqrt, trunc, log, log10, exp, sin, round
Logic-methods	Logic functions (!, &, |)
Summary-methods	Summary functions (mean, max, min, range, prod, sum, any, all)
Compare-methods	Compare functions (==, !=, >, <, <=, >=)
app	Apply a function to cells of a SpatRaster (as in base::apply)
tapp	Apply a function to cells of a SpatRaster by groups of layers (as in base::tapply)
overlay	Computations on multiple SpatRaster objects
cover	First layer covers second layer except where the first layer is NA
mask	Use values from first SpatRaster except where cells of the mask SpatRaster are NA (or another value of choice)
classify	(Re-)classify values
init	Initialize cells with new values
area	Compute area of cells (for longitude/latitude data)
collapse	Select cell values from different layers using an index layer
---------------------------	------------------------------------------------------------------------------------------

IV. Zonal and global computation

zonal	Summarize a SpatRaster by zones in another SpatRaster
global	Summarize SpatRaster cell values with a function
unique	Get the unique values in a SpatRaster
freq	Frequency table of SpatRaster cell values
crosstab	Cross-tabulate two SpatRasters
quantile	Quantiles
summary	Summary of the values of a SpatRaster (quartiles and mean)
---------------------------	------------------------------------------------------------------------------------------

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
clump	Find clumps (patches)
terrain	Compute slope, aspect and other terrain characteristics from elevation data
autocor	Compute global or local Moran or Geary indices of spatial autocorrelation
---------------------------	------------------------------------------------------------------------------------------

VI. Model predictions

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

VII. Data type conversion

You can coerce SpatRasters to Raster* objects after loading the raster package, using as, as in as(object, "RasterBrick"), 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
---------------------------	------------------------------------------------------------------------------------------

VIII. Accessing values of SpatRaster cells

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

values	Get all cell values (fails with very large rasters), or a row of values (safer)
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)
sampleRandom	Random sample
spatSample	Regular 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
---------------------------	------------------------------------------------------------------------------------------

IX. Plotting

Maps
plot	Plot a SpatRaster. The main method to create a map
plotRGB	Combine three layers (red, green, blue channels) into a single "real color" image
image	Plot a SpatRaster with the image function
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
.	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
---------------------------	------------------------------------------------------------------------------------------

X. Getting and setting SpatRaster dimensions

Basic parameters of existing SpatRasters can be obtained, and in most cases changed. 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 projection you can set the projection, but this does not transform the data (see warp 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)
isLonLat	Test if an object has a longitude/latitude coordinate reference system
filename	Filename(s) to which a SpatRaster is linked
compareGeom	Compare the geometry of SpatRasters
NAvalue	Get or set the NA value (for reading from a file)
---------------------------	------------------------------------------------------------------------------------------

XI. 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
cellsFromExtent	Cell numbers from extent object
---------------------------	------------------------------------------------------------------------------------------

XII. Writing files

Basic	values
Assign new values to the cells of a SpatRaster	writeRaster
Write all values of SpatRaster to disk	.
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	---------------------------
------------------------------------------------------------------------------------------	Basic

XIII. Manipulation of SpatVector objects

The name in bold is the equivalent command in ArcGIS.

c	append combine "rbind" vector data of the same (vector) type
erase or "-"	erase parts of a polygons
intersect or "*"	intersect polygons
union or "+"	union polygons
cover	update and identity a polygons
symdif	symmetrical difference of two polygons
aggregate	dissolve smaller polygons into larger ones
disaggregate	explode: turn polygon parts into separate polygons
crop	clip vector data using a rectangle (SpatExtent )
select	select - interactively select spatial features
click	identify attributes by clicking on a map
merge	Join table
extract	spatial queries between SpatVector and SpatRaster objects
as.data.frame	coerce coordinates into a data.frame
---------------------------	------------------------------------------------------------------------------------------

XIV. SpatExtent objects

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

XV. Miscellaneous

terraOptions	Show, set, save or get session options
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?
---------------------------	------------------------------------------------------------------------------------------

Acknowledgments

This package stands on the shoulders of giants (notably for GDAL, GEOS, GeographicLib)