\documentclass{article}

\usepackage{natbib}
\usepackage{graphics}
\usepackage{amsmath}
\usepackage{indentfirst}
\usepackage{hanging}
\usepackage[utf8]{inputenc}
\usepackage{hyperref}

%\VignetteIndexEntry{Introduction to the raster package}

\newcommand{\R}{{\normalfont\textsf{R }}{}}
\newcommand{\NA}{{\normalfont\textsf{NA }}{}}

\DeclareGraphicsExtensions{.png,.pdf,.jpg}

\begin{document}

\SweaveOpts{png=TRUE, pdf=FALSE}

\SweaveOpts{resolution=100}
\SweaveOpts{keep.source=TRUE}

<<foo,include=FALSE,echo=FALSE>>=
options(width = 60)
foo <- packageDescription("raster")
@

\title{Introduction to the 'raster' package\\(version \Sexpr{foo$Version})}

\author{Robert J. Hijmans}
\maketitle


\section{Introduction}

This vignette describes the \R package '\verb@raster@'. A raster is a spatial (geographic) data structure that divides a region into rectangles called 'cells' (or 'pixels') that can store one or more values for each of these cells.  Such a data structure is also referred to as a 'grid' and is often contrasted with 'vector' data that is used to represent points, lines, and polygons. 

The \verb@raster@ package has functions for creating, reading, manipulating, and writing raster data. The package provides, among other things, general raster data manipulation functions that can easily be used to develop more specific functions. For example, there are functions to read a chunk of raster values from a file or to convert cell numbers to coordinates and back. The package also implements raster algebra and most functions for raster data manipulation that are common in Geographic Information Systems (GIS). These functions are similar to those in GIS programs such as Idrisi, the raster functions of GRASS, and the 'grid' module of ArcInfo ('workstation').

A notable feature of the \verb@raster@ package is that it can work with raster datasets that are stored on disk and are too large to be loaded into memory (RAM). The package can work with large files because the objects it creates from these files only contain information about the structure of the data, such as the number of rows and columns, the spatial extent, and the filename, but it does not attempt to read all the cell values in memory. In computations with these objects, data is processed in chunks. If no output filename is specified to a function, and the output raster is too large to keep in memory, the results are written to a temporary file. 

To understand what is covered in this vignette, you must understand the basics of the \R language. There is a multitude of on-line and other resources that can help you to get acquainted with it. The \verb@raster@ package does not operate in isolation. For example, for vector type data it uses classes defined in the \verb@sp@ package. See the vignette and help pages of that package or Bivand {\it et al}. (2008). Bivand {\it et al}., provide an introduction to the use of \R for handling spatial data, and to statistically oriented spatial data analysis (such as inference from spatial data, point pattern analysis, and geostatistics). 

In the next section, some general aspects of the design of the '\verb@raster@' package are discussed, notably the structure of the main classes, and what they represent. The use of the package is illustrated in subsequent sections. \verb@raster@ has a large number of functions, not all of them are discussed here, and those that are discussed are mentioned only briefly. See the help files of the package for more information on individual functions and {\bf help("raster-package")} for an index of functions by topic.


\section{Classes}

The package is built around a number of 'S4' classes of which the \verb@RasterLayer@, \verb@RasterBrick@, and \verb@RasterStack@ classes are the most important. See Chambers (2009) for a detailed discussion of the use of S4 classes in \R. When discussing methods that can operate on all three of these objects, they are referred to as 'Raster*' objects.

\subsection{RasterLayer}

A \verb@RasterLayer@ object represents single-layer (variable) raster data. A \verb@RasterLayer@ object always stores a number of fundamental parameters that describe it. These include the number of columns and rows, the coordinates of its spatial extent ('bounding box'), and the coordinate reference system (the 'map projection'). In addition, a \verb@RasterLayer@ can store information about the file in which the raster cell values are stored (if there is such a file). A \verb@RasterLayer@ can also hold the raster cell values in memory.

\subsection{RasterStack and RasterBrick}

It is quite common to analyze raster data using single-layer objects. However, in many cases multi-variable raster data sets are used. The \verb@raster@ package has two classes for multi-layer data the \verb@RasterStack@ and the \verb@RasterBrick@. The principal difference between these two classes is that a \verb@RasterBrick@ can only be linked to a single (multi-layer) file. In contrast, a \verb@RasterStack@ can be formed from separate files and/or from a few layers ('bands') from a single file. 

In fact, a \verb@RasterStack@ is a collection of \verb@RasterLayer@ objects with the same spatial extent and resolution. In essence it is a list of \verb@RasterLayer@ objects. A \verb@RasterStack@ can easily be formed form a collection of files in different locations and these can be mixed with \verb@RasterLayer@ objects that only exist in memory.

A \verb@RasterBrick@  is truly a multilayered object, and processing a \verb@RasterBrick@  can be more efficient than processing a \verb@RasterStack@ representing the same data. However, it can only refer to a single file. A typical example of such a file would be a multi-band satellite image or the output of a global climate model (with e.g., a time series of temperature values for each day of the year for each raster cell). Methods that operate on \verb@RasterStack@ and \verb@RasterBrick@  objects typically return a \verb@RasterBrick@.


\subsection{Other classes}

Below is some more detail, you do not need to read or understand this section to use the \verb@raster@ package. 

The three classes described above inherit from the \verb@Raster@ class (that means they are derived from this more basic 'parent' class by adding something to that class) which itself inherits from the \verb@BasicRaster@ class. The \verb@BasicRaster@ only has a few properties (referred to as 'slots' in S4 speak): the number of columns and rows, the coordinate reference system (which itself is an object of class \verb@CRS@, which is defined in package '\verb@sp@') and the spatial extent, which is an object of class \verb@Extent@.  

An object of class \verb@Extent@ has four slots: xmin, xmax, ymin, and ymax. These represent the minimum and maximum x and y coordinates of the of the Raster object. These would be, for example,  -180, 180, -90, and 90, for a global raster with longitude/latitude coordinates.  Note that raster uses the coordinates of the extremes (corners) of the entire raster (unlike some files/programs that use the coordinates of the center of extreme cells). 

\verb@Raster@  is a virtual class. This means that it cannot be instantiated (you cannot create objects from this class). It was created to allow the definition of methods for that class. These methods will be dispatched when called with a descendent of the class (i.e. when the method is called with a \verb@RasterLayer@, \verb@RasterBrick@  or \verb@RasterStack@ object as argument). This allows for efficient code writing because many methods are the same for any of these three classes, and hence a single method for \verb@Raster@ suffices. 

\verb@RasterStackBrick@ is a class union of the \verb@RasterStack@ and \verb@RasterBrick@ class. This is a also a virtual class. It allows defining methods (functions) that apply to both \verb@RasterStack@ and \verb@RasterBrick@ objects.


\section{Creating Raster* objects}

A \verb@RasterLayer@ can easily be created from scratch using the function {\bf raster}. The default settings will create a global raster data structure with a longitude/latitude coordinate reference system and 1 by 1 degree cells. You can change these settings by providing additional arguments such as {\bf xmin}, {\bf nrow}, {\bf ncol}, and/or {\bf crs}, to the function. You can also change these parameters after creating the object. If you set the projection, this is only to properly define it, not to change it. To transform a \verb@RasterLayer@ to another coordinate reference system (projection) you can use the function {\bf projectRaster}. 

Here is an example of creating and changing a \verb@RasterLayer@ object 'r' from scratch.
<<raster-1a>>=
library(raster)
# RasterLayer with the default parameters
x <- raster()
x

# With other parameters
x <- raster(ncol=36, nrow=18, xmn=-1000, xmx=1000, ymn=-100, ymx=900)
# that can be changed
res(x)

# change resolution
res(x) <- 100
res(x)
ncol(x)
# change the numer of columns (affects resolution)
ncol(x) <- 18
ncol(x)
res(x)

# set the coordinate reference system (CRS) (define the projection)
projection(x) <- "+proj=utm +zone=48 +datum=WGS84"
x
@

The objects 'x' created in the example above only consist of a 'skeleton', that is, we have defined the number of rows and columns, and where the raster is located in geographic space, but there are no cell-values associated with it. Setting and accessing values is illustrated below.

<<raster-1b, fig=TRUE , echo=TRUE>>=
r <- raster(ncol=10, nrow=10)
ncell(r)
hasValues(r)

# use the 'values' function
# e.g., 
values(r) <- 1:ncell(r)
# or
set.seed(0)
values(r) <- runif(ncell(r))

hasValues(r)
inMemory(r)
values(r)[1:10]

plot(r, main='Raster with 100 cells')
@

In some cases, for example when you change the number of columns or rows, you will lose the values associated with the \verb@RasterLayer@ if there were any (or the link to a file if there was one). The same applies, in most cases, if you change the resolution directly (as this can affect the number of rows or columns). Values are not lost when changing the extent as this change adjusts the resolution, but does not change the number of rows or columns. 

<<raster-1c, echo=TRUE>>=
hasValues(r)
res(r)
dim(r)
xmax(r)

# change the maximum x coordinate of the extent (bounding box) of the RasterLayer
xmax(r) <- 0

hasValues(r)
res(r)
dim(r)

ncol(r) <- 6
hasValues(r)
res(r)
dim(r)
xmax(r)
@

The function {\bf raster} also allows you to create a \verb@RasterLayer@ from another object, including another \verb@RasterLayer@, \verb@RasterStack@ and \verb@RasterBrick@ , as well as from a \verb@SpatialPixels*@ and \verb@SpatialGrid*@ object (defined in the \verb@sp@ package), an \verb@Extent@ object, a matrix, an 'im' object (SpatStat), and 'asc' and 'kasc' objects (adehabitat).

It is more common, however, to create a \verb@RasterLayer@ object from a file. The raster package can use raster files in several formats, including some 'natively' supported formats and other formats via the \verb@rgdal@ package. Supported formats for reading include GeoTIFF, ESRI, ENVI, and ERDAS. Most formats supported for reading can also be written to. Here is an example using the 'Meuse' dataset (taken from the \verb@sp@ package), using a file in the native 'raster-file' format:

<<raster-2a, fig=TRUE , echo=TRUE>>=
# get the name of an example file installed with the package
# do not use this construction of your own files
filename <- system.file("external/test.grd", package="raster")

filename
r <- raster(filename)
filename(r)
hasValues(r)
inMemory(r)
plot(r, main='RasterLayer from file')
@

Multi-layer objects can be created in memory (from \verb@RasterLayer@ objects) or from files. 

<<raster-2b>>=
# create three identical RasterLayer objects
r1 <- r2 <- r3 <- raster(nrow=10, ncol=10)
# Assign random cell values 
values(r1) <- runif(ncell(r1))
values(r2) <- runif(ncell(r2))
values(r3) <- runif(ncell(r3))

# combine three RasterLayer objects into a RasterStack
s <- stack(r1, r2, r3)
s
nlayers(s)

# combine three RasterLayer objects into a RasterBrick 
b1 <- brick(r1, r2, r3)
# equivalent to:
b2 <- brick(s)

# create a RasterBrick  from file
filename <- system.file("external/rlogo.grd", package="raster")
filename
b <- brick(filename)
b
nlayers(b)

# extract a single RasterLayer
r <- raster(b, layer=2)
# equivalent to creating it from disk
r <- raster(filename, band=2)
@


\section{Raster algebra}

Many generic functions that allow for simple and elegant raster algebra have been implemented for \verb@Raster*@ objects, including the normal algebraic operators such as {\bf +, -, *, /}, logical operators such as {\bf >, >=, <, ==, !} and functions such as {\bf abs, round, ceiling, floor, trunc, sqrt, log, log10, exp, cos, sin, max, min, range, prod, sum, any, all}. In these functions you can mix \verb@Raster@ objects with numbers, as long as the first argument is a \verb@Raster@ object. 

<<raster-3a>>=
# create an empty RasterLayer
r <- raster(ncol=10, nrow=10)
# assign values to cells
values(r) <- 1:ncell(r)
s <- r + 10
s <- sqrt(s)
s <- s * r + 5
r[] <- runif(ncell(r))
r <- round(r)
r <- r == 1
@

You can also use replacement functions:
<<raster-3b>>=
s[r] <- -0.5
s[!r] <- 5
s[s == 5] <- 15
@

If you use multiple \verb@Raster*@ objects (in functions where this is relevant, such as range), these must have the same resolution and origin. The origin of a \verb@Raster*@ object is the point closest to (0, 0) that you could get if you moved from a corners of a \verb@Raster*@ object towards that point in steps of the \verb@x@ and \verb@y@ resolution. Normally these objects would also have the same extent, but if they do not, the returned object covers the spatial intersection of the objects used.


When you use multiple multi-layer objects with different numbers or layers, the 'shorter' objects are 'recycled'. For example, if you multuply a 4-layer object (a1, a2, a3, a4) with a 2-layer object (b1, b2), the result is a four-layer object (a1b1, a2b2, a3b1, a3b2). 

<<raster-3c>>=
r <- raster(ncol=5, nrow=5)
r[] <- 1
s <- stack(r, r+1)
q <- stack(r, r+2, r+4, r+6)
x <- r + s + q
x
@


Summary functions {\bf (min, max, mean, prod, sum, Median, cv, range, any, all)} always return a \verb@RasterLayer@ object. Perhaps this is not obvious when using functions like {\bf min, sum or mean}. 

<<raster-3d>>=
a <- mean(r,s,10)
b <- sum(r,s)
st <- stack(r, s, a, b)
sst <- sum(st)
sst
@

Use {\bf cellStats} if instead of a \verb@RasterLayer@ you want a single number summarizing the cell values of each layer. 
<<raster-3e>>=
cellStats(st, 'sum')
cellStats(sst, 'sum')
@



\section{'High-level' functions}

Several 'high level' functions have been implemented for \verb@RasterLayer@ objects. 'High level' functions refer to functions that you would normally find in a GIS program that supports raster data. Here we briefly discuss some of these functions. All these functions work for raster datasets that cannot be loaded into memory. See the help files for more detailed descriptions of each function.

The high-level functions have some arguments in common. The first argument is typically 'x' or 'object' and can be a \verb@RasterLayer@, or, in most cases, a \verb@RasterStack@ or \verb@RasterBrick@. It is followed by one or more arguments specific to the function (either additional \verb@RasterLayer@ objects or other arguments), followed by a filename="" and "..." arguments. 

The default filename is an empty character "". If you do not specify a filename, the default action for the function is to return a \verb@Raster@ object that only exists in memory. However, if the function deems that the \verb@Raster@ object to be created would be too large to hold memory it is written to a temporary file instead.

The "..."  argument allows for setting additional arguments that are relevant when writing values to a file: the file format, datatype (e.g. integer or real values), and a to indicate whether existing files should be overwritten. 


\subsection{Modifying a Raster* object}

There are several functions that deal with modifying the spatial extent of \verb@Raster*@ objects. The {\bf crop} function lets you take a geographic subset of a larger \verb@Raster@ object. You can crop a \verb@Raster*@ by providing an extent object or another spatial object from which an extent can be extracted (objects from classes deriving from Raster and from Spatial in the sp package). An easy way to get an extent object is to plot a \verb@RasterLayer@ and then use {\bf drawExtent} to visually determine the new extent (bounding box) to provide to the crop function. 

{\bf trim} crops a \verb@RasterLayer@ by removing the outer rows and columns that only contain \NA values. In contrast, {\bf extend} adds new rows and/or columns with \NA values. The purpose of this could be to create a new \verb@RasterLayer@ with the same Extent of another larger \verb@RasterLayer@ such that the can be used together in other functions. 

The {\bf merge} function lets you merge 2 or more \verb@Raster*@ objects into a single new object. The input objects must have the same resolution and origin (such that their cells neatly fit into a single larger raster). If this is not the case you can first adjust one of the \verb@Raster*@ objects with use {\bf (dis)aggregate} or {\bf resample}.

{\bf aggregate} and {\bf disaggregate} allow for changing the resolution (cell size) of a \verb@Raster*@ object. In the case of {\bf aggregate}, you need to specify a function determining what to do with the grouped cell values (e.g. {\bf mean}). It is possible to specify different (dis)aggregation factors in the x and y direction. {\bf aggregate} and {\bf disaggregate} are the best functions when adjusting cells size only, with an integer step (e.g. each side 2 times smaller or larger), but in some cases that is not possible. 

For example, you may need nearly the same cell size, while shifting the cell centers. In those cases, the {\bf resample} function can be used. It can do either nearest neighbor assignments (for categorical data) or bilinear interpolation (for numerical data). Simple linear shifts of a Raster object can be accomplished with the {\bf shift} function or with the {\bf extent} function. {\bf resample} should not be used to create a Raster* object with much larger resolution. If such adjustments need to be made then you can first use aggregate. 

With the {\bf projectRaster} function you can transform values of \verb@Raster*@ object to a new object with a different coordinate reference system.

Here are some simple examples:
<<raster-5, fig=TRUE , echo=TRUE>>=
r <- raster()
r[] <- 1:ncell(r)
ra <- aggregate(r, 10)
r1 <- crop(r, extent(-180,0,0,30))
r2 <- crop(r, extent(-10,180,-20,10))
m <- merge(r1, r2, filename='test.grd', overwrite=TRUE)
plot(m)
@

{\bf flip} lets you flip the data (reverse order) in horizontal or vertical direction -- typically to correct for a 'communication problem' between different R packages or a misinterpreted file. {\bf rotate} lets you rotate longitude/latitude rasters that have longitudes from 0 to 360 degrees (often used by climatologists) to the standard -180 to 180 degrees system. With {\bf t} you can rotate a \verb@Raster*@ object 90 degrees.


\subsection{Overlay}
The {\bf overlay} function can be used as an alternative to the raster algebra discussed above. Overlay, like the funcitons discussed in the following subsections provide either easy to use short-hand, or more efficient computation for large (file based) objects. 

With {\bf overlay} you can combine multiple Raster objects (e.g. multiply them). The related function {\bf mask} removes all values from one layer that are \NA in another layer, and {\bf cover} combines two layers by taking the values of the first layer except where these are \NA.


\subsection{Calc}

{\bf calc} allows you to do a computation for a single \verb@Raster@ object by providing a function. If you supply a \verb@RasterLayer@, another \verb@RasterLayer@ is returned. If you provide a multi-layer object you get a (single layer) \verb@RasterLayer@ if you use a summary type function (e.g. {\bf sum}) but a \verb@RasterBrick@ if multiple layers are returned. {\bf stackApply} computes summary type layers for subsets of a \verb@RasterStack@ or \verb@RasterBrick@.


\subsection{Reclassify}
You can use {\bf cut} or {\bf reclassify} to replace ranges of values with single values, or {\bf subs} to substitute (replace) single values with other values. 

<<raster-6>>=
r <- raster(ncol=3, nrow=2)
r[] <- 1:ncell(r)
getValues(r)
s <- calc(r, fun=function(x){ x[x < 4] <- NA; return(x)} )
as.matrix(s)
t <- overlay(r, s, fun=function(x, y){ x / (2 * sqrt(y)) + 5 } )
as.matrix(t)
u <- mask(r, t)
as.matrix(u)
v = u==s
as.matrix(v)
w <- cover(t, r)
as.matrix(w)
x <- reclassify(w, c(0,2,1,  2,5,2, 4,10,3))
as.matrix(x)
y <- subs(x, data.frame(id=c(2,3), v=c(40,50)))
as.matrix(y)
@


\subsection{Focal functions}

The {\bf focal} function currently only works for (single layer) RasterLayer objects. It uses values in a neighborhood of cells around a focal cell, and computes a value that is stored in the focal cell of the output RasterLayer. The neighborhood is a user-defined a matrix of weights and could approximate any shape by giving some cells zero weight. It is possible to only compute new values for cells that are \NA in the input RasterLayer.


\subsection{Distance}

There are a number of distance related functions. {\bf distance} computes the shortest distance to cells that are not \NA. {\bf pointDistance} computes the shortest distance to any point in a set of points. {\bf gridDistance} computes the distance when following grid cells that can be traversed (e.g. excluding water bodies). {\bf direction} computes the direction towards (or from) the nearest cell that is not \NA. {\bf adjacency} determines which cells are adjacent to other cells, and {\bf pointDistance} computes distance between points. See the {\bf gdistance} package for more advanced distance calculations (cost distance, resistance distance)

\subsection{Spatial configuration}
Function {\bf clump} identifies groups of cells that are connected. {\bf boundaries} identifies edges, that is, transitions between cell values. {\bf area} computes the size of each grid cell (for unprojected rasters), this may be useful to, e.g. compute the area covered by a certain class on a longitude/latitude raster. 

<<raster-7>>=
r <- raster(nrow=45, ncol=90)
r[] <- round(runif(ncell(r))*3)
a <- area(r)
zonal(a, r, 'sum')
@


\subsection{Predictions}
The package has two functions to make model predictions to (potentially very large) rasters. {\bf predict} takes a multilayer raster and a fitted model as arguments. Fitted models can be of various classes, including glm, gam, randomforest, and brt. Function {\bf interpolate} is similar but is for models that use coordinates as predictor variables, for example in kriging and spline interpolation.


\subsection{Vector to raster conversion}

The raster packages supports point, line, and polygon to raster conversion with the {\bf rasterize} function. For vector type data (points, lines, polygons), objects of Spatial* classes defined in the \verb@sp@ package are used; but points can also be represented by a two-column matrix (x and y). 

Point to raster conversion is often done with the purpose to analyze the point data. For example to count the number of distinct species (represented by point observations) that occur in each raster cell. {\bf rasterize} takes a \verb@Raster*@ object to set the spatial extent and resolution, and a function to determine how to summarize the points (or an attribute of each point) by cell. 

Polygon to raster conversion is typically done to create a \verb@RasterLayer@ that can act as a mask, i.e. to set to \NA a set of cells of a \verb@Raster@ object, or to summarize values on a raster by zone. For example a country polygon is transferred to a raster that is then used to set all the cells outside that country to \NA; whereas polygons representing administrative regions such as states can be transferred to a raster to summarize raster values by region. 

It is also possible to convert the values of a \verb@RasterLayer@ to points or polygons, using {\bf rasterToPoints} and {\bf rasterToPolygons}. Both functions only return values for cells that are not \NA. Unlike {\bf rasterToPolygons}, {\bf rasterToPoints} is reasonably efficient and allows you to provide a function to subset the output before it is produced (which can be necessary for very large rasters as the point object is created in memory). 


\section{Summarizing functions}

When used with a \verb@Raster*@ object as first argument, normal summary statistics functions such as min, max and mean return a RasterLayer. You can use cellStats if, instead, you want to obtain a summary for all cells of a single \verb@Raster*@ object. You can use {\bf freq} to make a frequency table, or to count the number of cells with a specified value. Use {\bf zonal} to summarize a \verb@Raster*@ object using zones (areas with the same integer number) defined in a \verb@RasterLayer@ and {\bf crosstab} to cross-tabulate two \verb@RasterLayer@ objects.

<<raster-10>>=
r <- raster(ncol=36, nrow=18)
r[] <- runif(ncell(r))
cellStats(r, mean)
s = r
s[] <- round(runif(ncell(r)) * 5)
zonal(r, s, 'mean')
freq(s)
freq(s, value=3)
crosstab(r*3, s)
@


\section{Plotting}
Several generic functions have been implemented for Raster* objects to create maps and other plot types. Use 'plot' to create a map of a Raster* object. When plot is used with a \verb@RasterLayer@, it calls the function 'rasterImage' (but, by default, adds a legend; using code from fields::image.plot). It is also possible to directly call {\bf image}. You can zoom in using 'zoom' and clicking on the map twice (to indicate where to zoom to). With {\bf click} it is possible to interactively query a Raster* object by clicking once or several times on a map plot.

After plotting a \verb@RasterLayer@ you can add vector type spatial data (points, lines, polygons). You can do this with functions points, lines, polygons if you are using the basic R data structures or plot(object, add=TRUE) if you are using Spatial* objects as defined in the sp package. When plot is used with a multi-layer Raster* object, all layers are plotted (up to 16), unless the layers desired are indicated with an additional argument. You can also plot Raster* objects with spplot. The {\bf rasterVis} package has several other {\bf lattice} based plotting functions for Raster* objects. {\bf rasterVis} also facilatates creating a map from a {\bf RasterLayer} with the {\bf ggplot2} package.

Multi-layer Raster objects can be plotted as individual layers
<<raster-20a, fig=TRUE , echo=TRUE>>=
b <- brick(system.file("external/rlogo.grd", package="raster"))
plot(b)
@

They can also be combined into a single image, by assigning individual layers to one of the three color channels (red, green and blue):
<<raster-20b, fig=TRUE , echo=TRUE>>=
plotRGB(b, r=1, g=2, b=3)
@

You can also use the a number of other plotting functions with a \verb@Raster@ object as argument, including {\bf hist, persp, contour}, and {\bf density}. See the help files for more info. 



\section{Writing files}

\subsection{File format}

Raster can read most, and write several raster file formats, via the \verb@rgdal@ package. However, it directly reads and writes a native 'rasterfile' format. A rasterfile consists of two files: a binary sequential data file and a text header file. The header file is of the "windows .ini" type. When reading, you do not have to specify the file format, but you do need to do that when writing (except when using the default native format). This file format is also used in DIVA-GIS (\url{http://www.diva-gis.org/}). See the help file for function {\bf writeRaster} or the "Description of the rasterfile format" vignette.



\section{Helper functons}

The cell number is an important concept in the raster package. Raster data can be thought of as a matrix, but in a \verb@RasterLayer@ it is more commonly treated as a vector. Cells are numbered from the upper left cell to the upper right cell and then continuing on the left side of the next row, and so on until the last cell at the lower-right side of the raster. There are several helper functions to determine the column or row number from a cell and vice versa, and to determine the cell number for x, y coordinates and vice versa.

<<raster-15>>=
library(raster)
r <- raster(ncol=36, nrow=18)
ncol(r)
nrow(r)
ncell(r)
rowFromCell(r, 100)
colFromCell(r, 100)
cellFromRowCol(r,5,5)
xyFromCell(r, 100)
cellFromXY(r, c(0,0))
colFromX(r, 0)
rowFromY(r, 0)
@


\section{Accessing cell values}

Cell values can be accessed with several methods. Use {\bf getValues} to get all values or a single row; and {\bf getValuesBlock} to read a block (rectangle) of cell values. 

<<raster-20>>=
r <- raster(system.file("external/test.grd", package="raster"))
v <- getValues(r, 50)
v[35:39]
getValuesBlock(r, 50, 1, 35, 5)
@


You can also read values using cell numbers or coordinates (xy) using the {\bf extract} method.
<<raster-21>>=
cells <- cellFromRowCol(r, 50, 35:39)
cells
extract(r, cells)
xy = xyFromCell(r, cells)
xy
extract(r, xy)
@


You can also extract values using SpatialPolygons* or SpatialLines*. The default approach for extracting raster values with polygons is that a polygon has to cover the center of a cell, for the cell to be included. However, you can use argument "weights=TRUE" in which case you get, apart from the cell values, the percentage of each cell that is covered by the polygon, so that you can apply, e.g., a "50\% area covered" threshold, or compute an area-weighted average.

In the case of lines, any cell that is crossed by a line is included. For lines and points, a cell that is only 'touched' is included when it is below or to the right (or both) of the line segment/point (except for the bottom row and right-most column).

In addition, you can use standard \R indexing to access values, or to replace values (assign new values to cells) in a \verb@Raster@ object. If you replace a value in a \verb@Raster@ object based on a file, the connection to that file is lost (because it now is different from that file). Setting raster values for very large files will be very slow with this approach as each time a new (temporary) file, with all the values, is written to disk. If you want to overwrite values in an existing file, you can use {\bf update} (with caution!)

<<raster-32>>=
r[cells] 
r[1:4]
filename(r)
r[2:3] <- 10
r[1:4]
filename(r)
@

Note that in the above examples values are retrieved using cell numbers. That is, a raster is represented as a (one-dimensional) vector. Values can also be inspected using a (two-dimensional) matrix notation. As for \R matrices, the first index represents the row number, the second the column number.

<<raster-33>>=
r[1]
r[2,2]
r[1,]
r[,2]
r[1:3,1:3]

# keep the matrix structure
r[1:3,1:3, drop=FALSE]
@

Accessing values through this type of indexing should be avoided inside functions as it is less efficient than accessing values via functions like {\bf getValues}. 



\section{Session options}

There is a number of session options that influence reading and writing files. These can be set in a session, with \verb@rasterOptions@, and saved to make them persistent in between sessions. But you probably should not change the default values unless you have pressing need to do so. You can, for example, set the directory where temporary files are written, and set your preferred default file format and data type. Some of these settings can be overwritten by arguments to functions where they apply (with arguments like filename, datatype, format). Except for generic functions like mean, '+', and sqrt. These functions may write a file when the result is too large to hold in memory and then these options can only be set through the session options.  The options chunksize and maxmemory determine the maximum size (in number of cells) of a single chunk of values that is read/written in chunk-by-chunk processing of very large files.

<<raster-119>>=
rasterOptions()
@


\section{Coercion to objects of other classes}

Although the raster package defines its own set of classes, it is easy to coerce objects of these classes to objects of the 'spatial' family defined in the sp package. This allows for using functions defined by sp (e.g. spplot) and for using other packages that expect spatial* objects. To create a Raster object from variable n in a SpatialGrid* x use \verb@raster(x, n)@ or \verb@stack(x)@ or \verb@brick(x)@. Vice versa use \verb@as( , )@

You can also convert objects of class "im" (spatstat) and "asc" (adehabitat) to a \verb@RasterLayer@ and "kasc" (adehabitat) to a \verb@RasterStack@ or Brick using the \verb@raster(x)@, \verb@stack(x)@ or \verb@brick(x)@ function.

<<raster-120>>=
r1 <- raster(ncol=36, nrow=18)
r2 <- r1
r1[] <- runif(ncell(r1))
r2[] <- runif(ncell(r1))
s <- stack(r1, r2)
sgdf <- as(s, 'SpatialGridDataFrame')
newr2 <- raster(sgdf, 2)
news <- stack(sgdf)
@


\section{Extending raster objects}

It is straightforward to build on the Raster* objects using the S4 inheritance mechanism. Say you need objects that behave like a \verb@RasterLayer@, but have some additional properties that you need to use in your own functions (S4 methods). See Chambers (2009) and the help pages of the Methods package for more info. Below is an example:

<<raster-132>>=
setClass ('myRaster',
	contains = 'RasterLayer',
	representation (
		important = 'data.frame',
		essential = 'character'
	) ,
	prototype (
		important = data.frame(),
		essential = ''
	)
)
	
r = raster(nrow=10, ncol=10)

m <- as(r, 'myRaster')
m@important <- data.frame(id=1:10, value=runif(10))
m@essential <- 'my own slot'
m[] <- 1:ncell(m)
@

<<raster-133>>=
setMethod ('show' , 'myRaster', 
	function(object) {
		callNextMethod(object) # call show(RasterLayer)
		cat('essential:', object@essential, '\n')
		cat('important information:\n')
		print( object@important)
	})	
	
m
@



\section{References}

\begin{hangparas}{3em}{1}

\noindent Bivand, R.S., E.J. Pebesma and V. Gomez-Rubio, 2008. Applied Spatial Data Analysis with \R. Springer. 378p.

\noindent Chambers, J.M., 2009. Software for Data Analysis: Programming with \R. Springer. 498p.

\end{hangparas}


\end{document}
