raster (version 3.1-5)

raster-package: Overview of the functions in the raster package

Description

The raster package provides classes and functions to manipulate geographic (spatial) data in 'raster' format. 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 (object based) spatial data (points, lines, polygons).

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 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 functions grouped by theme. See the vignette for more information and some examples (you can open it by running this command: vignette('Raster'))

I. Creating Raster* objects

RasterLayer, RasterStack, and RasterBrick objects are, as a group, referred to as Raster* objects. Raster* objects can be created, from scratch, files, or from objects of other classes, with the following functions:

raster	To create a RasterLayer
stack	To create a RasterStack (multiple layers)
brick	To create a RasterBrick (multiple layers)
subset	Select layers of a RasterStack/Brick
addLayer	Add a layer to a Raster* object
dropLayer	Remove a layer from a RasterStack or RasterBrick
unstack	Create a list of RasterLayer objects from a RasterStack
---------------------------	---------------------------------------------------------------------------------------------------

II. Changing the spatial extent and/or resolution of Raster* objects

merge	Combine Raster* objects with different extents (but same origin and resolution)
mosaic	Combine RasterLayers with different extents and a function for overlap areas
crop	Select a geographic subset of a Raster* object
extend	Enlarge a Raster* object
trim	Trim a Raster* object by removing exterior rows and/or columns that only have NAs
aggregate	Combine cells of a Raster* object to create larger cells
disaggregate	Subdivide cells
resample	Warp values to a Raster* object with a different origin or resolution
projectRaster	project values to a raster with a different coordinate reference system
shift	Move the location of Raster
flip	Flip values horizontally or vertically
rotate	Rotate values around the date-line (for lon/lat data)
t	Transpose a Raster* object
---------------------------	------------------------------------------------------------------------------------------

III. Raster algebra

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 (==, !=, >, <, <=, >=)
---------------------------	------------------------------------------------------------------------------------------

IV. Cell based computation

calc	Computations on a single Raster* object
overlay	Computations on multiple RasterLayer objects
cover	First layer covers second layer except where the first layer is NA
mask	Use values from first Raster except where cells of the mask Raster are NA
cut	Reclassify values using ranges
subs	Reclassify values using an 'is-becomes' matrix
reclassify	Reclassify using a 'from-to-becomes' matrix
init	Initialize cells with new values
stackApply	Computations on groups of layers in Raster* object
stackSelect	Select cell values from different layers using an index RasterLayer
---------------------------	------------------------------------------------------------------------------------------

V. Spatial contextual computation

distance	Shortest distance to a cell that is not NA
gridDistance	Distance when traversing grid cells that are not NA
distanceFromPoints	Shortest distance to any point in a set of points
direction	Direction (azimuth) to or from cells that are not NA
focal	Focal (neighborhood; moving window) functions
localFun	Local association (using neighborhoods) functions
boundaries	Detection of boundaries (edges)
clump	Find clumps (patches)
adjacent	Identify cells that are adjacent to a set of cells on a raster
area	Compute area of cells (for longitude/latitude data)
terrain	Compute slope, aspect and other characteristics from elevation data
Moran	Compute global or local Moran or Geary indices of spatial autocorrelation
---------------------------	------------------------------------------------------------------------------------------

VI. Model predictions

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

VII. Data type conversion

You can coerce Raster* objects to Spatial* objects using as, as in as(object, 'SpatialGridDataFrame')

raster	RasterLayer from SpatialGrid*, image, or matrix objects
rasterize	Rasterizing points, lines or polygons
rasterToPoints	Create points from a RasterLayer
rasterToPolygons	Create polygons from a RasterLayer
rasterToContour	Contour lines from a RasterLayer
rasterFromXYZ	RasterLayer from regularly spaced points
rasterFromCells	RasterLayer from a Raster object and cell numbers
---------------------------	------------------------------------------------------------------------------------------

VIII. Summarizing

cellStats	Summarize a Raster cell values with a function
summary	Summary of the values of a Raster* object (quartiles and mean)
freq	Frequency table of Raster cell values
crosstab	Cross-tabulate two Raster* objects
unique	Get the unique values in a Raster* object
zonal	Summarize a Raster* object by zones in a RasterLayer
---------------------------	------------------------------------------------------------------------------------------

IX. Accessing values of Raster* object cells

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

getValues	Get all cell values (fails with very large rasters), or a row of values (safer)
getValuesBlock	Get values for a block (a rectangular area)
getValuesFocal	Get focal values for one or more rows
as.matrix	Get cell values as a matrix
as.array	Get cell values as an array
extract	Extract cell values from a Raster* object (e.g., by cell, coordinates, polygon)
sampleRandom	Random sample
sampleRegular	Regular sample
minValue	Get the minimum value of the cells of a Raster* object (not always known)
maxValue	Get the maximum value of the cells of a Raster* object (not always known)
setMinMax	Compute the minimum and maximum value of a Raster* object if these are not known
---------------------------	------------------------------------------------------------------------------------------

X. Plotting

See the rasterVis package for additional plotting methods for Raster* objects using methods from 'lattice' and other packages.

Maps
plot	Plot a Raster* object. The main method to create a map
plotRGB	Combine three layers (red, green, blue channels) into a single 'real color' image
spplot	Plot a Raster* with the spplot function (sp package)
image	Plot a Raster* with the image function
persp	Perspective plot of a RasterLayer
contour	Contour plot of a RasterLayer
filledContour	Filled contour plot of a RasterLayer
text	Plot the values of a RasterLayer on top of a map
.	Interacting with a map
	zoom
Zoom in to a part of a map	click
Query values of Raster* or Spatial* objects by clicking on a map	select
Select a geometric subset of a Raster* or Spatial* object	drawPoly
Create a SpatialPolygons object by drawing it	drawLine
Create a SpatialLines object by drawing it	drawExtent
Create an Extent object by drawing it	.
Other plots
plot	x-y scatter plot of the values of two RasterLayer objects
hist	Histogram of Raster* object values
barplot	barplot of a RasterLayer
density	Density plot of Raster* object values
pairs	Pairs plot for layers in a RasterStack or RasterBrick
boxplot	Box plot of the values of one or multiple layers
---------------------------	------------------------------------------------------------------------------------------

XI. Getting and setting Raster* dimensions

Basic parameters of existing Raster* objects can be obtained, and in most cases changed. If there are values associated with a RasterLayer 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 projectRaster 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)
nlayers	How many layers does the object have?
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)
extent	The extent (minimum and maximum x and y coordinates)
origin	The origin of a Raster* object
crs	The coordinate reference system (map projection)
isLonLat	Test if an object has a longitude/latitude coordinate reference system
filename	Filename to which a RasterLayer or RasterBrick is linked
bandnr	layer (=band) of a multi-band file that this RasterLayer is linked to
nbands	How many bands (layers) does the file associated with a RasterLayer object have?
compareRaster	Compare the geometry of Raster* objects
NAvalue	Get or set the NA value (for reading from a file)
---------------------------	------------------------------------------------------------------------------------------

XII. 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
cellsFromExtent	Cell numbers from extent object
coordinates	x and y coordinates for all cells
validCell	Is this a valid cell number?
validCol	Is this a valid column number?
validRow	Is this a valid row number?
---------------------------	------------------------------------------------------------------------------------------

XIII. Writing files

Basic	setValues
Put new values in a Raster* object	writeRaster
Write all values of Raster* object to disk	KML
Save raster as KML file	.
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	update
Change the values of an existing file	---------------------------
------------------------------------------------------------------------------------------	Basic

XIV. Manipulation of SpatialPolygons* and other vector type Spatial* objects

Some of these functions are in the sp package. The name in bold is the equivalent command in ArcGIS. These functions build on the geometry ("spatial features") manipulation functions in package rgeos. These functions are extended here by also providing automated attribute data handling.

bind	append combine Spatial* objects of the same (vector) type
erase or "-"	erase parts of a SpatialPolygons* object
intersect or "*"	intersect SpatialPolygons* objects
union or "+"	union SpatialPolygons* objects
cover	update and identity for a SpatialPolygons and another one
symdif	symmetrical difference of two SpatialPolygons* objects
aggregate	dissolve smaller polygons into larger ones
disaggregate	explode: turn polygon parts into separate polygons (in the sp package)
crop	clip a Spatial* object using a rectangle (Extent object)
select	select - interactively select spatial features
click	identify attributes by clicking on a map
merge	Join table (in the sp package)
over	spatial queries between Spatial* objects
extract	spatial queries between Spatial* and Raster* objects
as.data.frame	coerce coordinates of SpatialLines or SpatialPolygons into a data.frame
---------------------------	------------------------------------------------------------------------------------------

XV. Extent objects

extent	Create an extent object
intersect	Intersect two extent objects
union	Combine two extent objects
round	round/floor/ceiling of the coordinates of an Extent object
alignExtent	Align an extent with a Raster* object
drawExtent	Create an Extent object by drawing it on top of a map (see plot)
---------------------------	------------------------------------------------------------------------------------------

XVI. Miscellaneous

rasterOptions	Show, set, save or get session options
getData	Download and geographic data
pointDistance	Distance between points
readIniFile	Read a (windows) 'ini' file
hdr	Write header file for a number of raster formats
trim	Remove leading and trailing blanks from a character string
extension	Get or set the extension of a filename
cv	Coefficient of variation
modal	Modal value
sampleInt	Random sample of (possibly very large) range of integer values
showTmpFiles	Show temporary files
removeTmpFiles	Remove temporary files
---------------------------	------------------------------------------------------------------------------------------

XVII. For programmers

canProcessInMemory	Test whether a file can be created in memory
pbCreate	Initialize a progress bar
pbStep	Take a progress bar step
pbClose	Close a progress bar
readStart	Open file connections for efficient multi-chunk reading
readStop	Close file connections
rasterTmpFile	Get a name for a temporary file
inMemory	Are the cell values in memory?
fromDisk	Are the cell values read from a file?
---------------------------	------------------------------------------------------------------------------------------

Acknowledgments

Extensive contributions were made by Jacob van Etten, Jonathan Greenberg, Matteo Mattiuzzi, and Michael Sumner. Significant help was also provided by Phil Heilman, Agustin Lobo, Oscar Perpinan Lamigueiro, Stefan Schlaffer, Jon Olav Skoien, Steven Mosher, and Kevin Ummel. Contributions were also made by Jochen Albrecht, Neil Best, Andrew Bevan, Roger Bivand, Isabelle Boulangeat, Lyndon Estes, Josh Gray, Tim Haering, Herry Herry, Paul Hiemstra, Ned Hornig, Mayeul Kauffmann, Bart Kranstauber, Rainer Krug, Alice Laborte, John Lewis, Lennon Li, Justin McGrath, Babak Naimi, Carsten Neumann, Joshua Perlman, Richard Plant, Edzer Pebesma, Etienne Racine, David Ramsey, Shaun Walbridge, Julian Zeidler and many others.

Details

The package implements classes for Raster data (see Raster-class) and supports

• Creation of Raster* objects from scratch or from file

• Handling extremely large raster files

• Raster algebra and overlay functions

• Distance, neighborhood (focal) and patch functions

• Polygon, line and point to raster conversion

• Model predictions

• Summarizing raster values

• Easy access to raster cell-values

• Plotting (making maps)

• Manipulation of raster extent, resolution and origin

• Computation of row, column and cell numbers to coordinates and vice versa

• Reading and writing various raster file types

.