raster: raster-package – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

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'))

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

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

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.

Author(s)

Except where indicated otherwise, the functions in this package were written by Robert J. Hijmans

raster

Geographic Data Analysis and Modeling

v3.4-10

GPL (>= 3)

Authors

Robert J. Hijmans [cre, aut] (<https://orcid.org/0000-0001-5872-2872>), Jacob van Etten [ctb], Michael Sumner [ctb], Joe Cheng [ctb], Dan Baston [ctb], Andrew Bevan [ctb], Roger Bivand [ctb], Lorenzo Busetto [ctb], Mort Canty [ctb], Ben Fasoli [ctb], David Forrest [ctb], Aniruddha Ghosh [ctb], Duncan Golicher [ctb], Josh Gray [ctb], Jonathan A. Greenberg [ctb], Paul Hiemstra [ctb], Kassel Hingee [ctb], Institute for Mathematics Applied Geosciences [cph], Charles Karney [ctb], Matteo Mattiuzzi [ctb], Steven Mosher [ctb], Babak Naimi [ctb], Jakub Nowosad [ctb], Edzer Pebesma [ctb], Oscar Perpinan Lamigueiro [ctb], Etienne B. Racine [ctb], Barry Rowlingson [ctb], Ashton Shortridge [ctb], Bill Venables [ctb], Rafael Wueest [ctb]

Initial release

2021-05-02