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`

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.

Arguments

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
`resample`	Warp values to a SpatRaster with a different origin or resolution
`warp`	Project 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

`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
`sampleRegular`	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)