Factors

These functions allow for defining a RasterLayer as a categorical variable. Such a RasterLayer is linked to other values via a "Raster Attribute Table" (RAT). Thus the cell values are an index, whereas the actual values of interest are in the RAT. The RAT is a data.frame. The first column in the RAT ("ID") has the unique cell values of the layer; this column should normally not be changed. The other columns can be of any basic type (factor, character, integer, numeric or logical). The functions documented here are mainly available such that files with a RAT can be read and processed; currently there is not too much further support. Whether a layer is defined as a factor or not is currently ignored by almost all functions. An exception is the 'extract' function (when used with option df=TRUE).

Function 'levels' returns the RAT for inspection. It can be modified and set using levels <- value (but use caution as it is easy to mess things up).

as.factor and ratify create a layer with a RAT table. Function 'deratify' creates a single layer for a (or each) variable in the RAT table.

Usage

is.factor(x)
as.factor(x)
levels(x)

# S4 method for class 'Raster'
ratify(x, filename="", count=FALSE, ...)

factorValues(x, v, layer=1, att=NULL, append.names=FALSE)
deratify(x, att=NULL, layer=1, complete=FALSE, drop=TRUE, fun='mean', filename='', ...) 

asFactor(x, ...)

Arguments

x

Raster* object

v

integer cell values

layer

integer > 0 indicating which layer to use (in a RasterStack or RasterBrick)

att

numeric or character. Which variable(s) in the RAT table should be used. If NULL, all variables are extracted. If using a numeric, skip the first two default columns

append.names

logical. Should names of data.frame returned by a combination of the name of the layer and the RAT variables? (can be useful for multilayer objects

filename

character. Optional

count

logical. If TRUE, a columns with frequencies is added

...

additional arguments as for writeRaster

complete

logical. If TRUE, the layer returned is no longer a factor

drop

logical. If TRUE a factor is converted to a numerical value if possible

fun

character. Used to get a single value for each class for a weighted RAT table. 'mean', 'min', 'max', 'smallest', or 'largest'

Value

Raster* object; list (levels); boolean (is.factor); matrix (factorValues)

Note

asFactor is deprecated and should not be used

Examples

set.seed(0)
r <- raster(nrow=10, ncol=10)
values(r) <- runif(ncell(r)) * 10
is.factor(r)
#> [1] FALSE

r <- round(r)
f <- as.factor(r)
is.factor(f)
#> [1] TRUE

x <- levels(f)[[1]]
x
#>    ID
#> 1   0
#> 2   1
#> 3   2
#> 4   3
#> 5   4
#> 6   5
#> 7   6
#> 8   7
#> 9   8
#> 10  9
#> 11 10
x$code <- letters[10:20]
levels(f) <- x
levels(f)
#> [[1]]
#>    ID code
#> 1   0    j
#> 2   1    k
#> 3   2    l
#> 4   3    m
#> 5   4    n
#> 6   5    o
#> 7   6    p
#> 8   7    q
#> 9   8    r
#> 10  9    s
#> 11 10    t
#> 
f
#> class      : RasterLayer 
#> dimensions : 10, 10, 100  (nrow, ncol, ncell)
#> resolution : 36, 18  (x, y)
#> extent     : -180, 180, -90, 90  (xmin, xmax, ymin, ymax)
#> crs        : +proj=longlat +datum=WGS84 +no_defs 
#> source     : memory
#> names      : layer 
#> values     : 0, 10  (min, max)
#> attributes :
#>        ID code
#>  from:  0    j
#>   to : 10    t
#> 

r <- raster(nrow=10, ncol=10)
values(r) = 1
r[51:100] = 2
r[3:6, 1:5] = 3
r <- ratify(r)

rat <- levels(r)[[1]]
rat$landcover <- c("Pine", "Oak", "Meadow")
rat$code <- c(12,25,30)
levels(r) <- rat
r
#> class      : RasterLayer 
#> dimensions : 10, 10, 100  (nrow, ncol, ncell)
#> resolution : 36, 18  (x, y)
#> extent     : -180, 180, -90, 90  (xmin, xmax, ymin, ymax)
#> crs        : +proj=longlat +datum=WGS84 +no_defs 
#> source     : memory
#> names      : layer 
#> values     : 1, 3  (min, max)
#> attributes :
#>  ID landcover code
#>   1      Pine   12
#>   2       Oak   25
#>   3    Meadow   30
#> 

# extract values for some cells
i <- extract(r, c(1,2, 25,100))
i
#> [1] 1 1 3 2
# get the attribute values for these cells
factorValues(r, i)
#>   landcover code
#> 1      Pine   12
#> 2      Pine   12
#> 3    Meadow   30
#> 4       Oak   25

# write to file:
# rr <- writeRaster(r, rasterTmpFile(), overwrite=TRUE)
# rr

# create a single-layer factor 
x <- deratify(r, "landcover")
x
#> class      : RasterLayer 
#> dimensions : 10, 10, 100  (nrow, ncol, ncell)
#> resolution : 36, 18  (x, y)
#> extent     : -180, 180, -90, 90  (xmin, xmax, ymin, ymax)
#> crs        : +proj=longlat +datum=WGS84 +no_defs 
#> source     : memory
#> names      : landcover 
#> values     : 1, 3  (min, max)
#> attributes :
#>  ID landcover
#>   1      Pine
#>   2       Oak
#>   3    Meadow
#> 
is.factor(x)
#> [1] TRUE
levels(x)
#> [[1]]
#>   ID landcover
#> 1  1      Pine
#> 2  2       Oak
#> 3  3    Meadow
#>