terra (version 1.8-80)

factors: Categorical rasters

Description

A SpatRaster layer can represent a categorical variable (factor). Like factors, SpatRaster categories are stored as integers that have an associated label.

The categories can be inspected with levels and cats. They are represented by a data.frame that must have two or more columns, the first one identifying the (integer) cell values and the other column(s) providing the category labels.

If there are multiple columns with categories, you can set the "active" category to choose the one you want to use.

cats returns the entire data.frame, whereas levels only return two columns: the index and the active category.

To set categories for the first layer of a SpatRaster, you can provide levels<- with a data.frame or a list with a data.frame. To set categories for multiple layers you can provide levels<- with a list with one element (that either has a data.frame or is NULL) for each layer. Use categories to set the categories for a specific layer or specific layers.

droplevels removes categories that are not used (declared but not present as values in the raster) if levels=NULL.

simplifyLevels combines duplicate levels into one.

addCats adds additional categories to a layer that already is categorical. It adds new variables, not new levels of an existing categorical variable.

combineLevels combines the levels of all layers of x and sets them to all layers. That fails if there are labeling conflicts between layers

Usage

# S4 method for SpatRaster
levels(x)
# S4 method for SpatRaster
levels(x)<-value
# S4 method for SpatRaster
cats(x, layer)
# S4 method for SpatRaster
categories(x, layer=1, value, active=1, ...)
# S4 method for SpatRaster
droplevels(x, level=NULL, layer=1)
# S4 method for SpatRaster
simplifyLevels(x, filename="", overwrite=FALSE, ...)
# S4 method for SpatRaster
addCats(x, value, merge=FALSE, layer=1)
combineLevels(x, assign=TRUE)

Value

SpatRaster, data.frame, list of data.frames (levels, cats), or logical (is.factor)

See Also

activeCat, catalyze, set.cats, as.factor, is.factor

Examples

set.seed(0)
r <- rast(nrows=10, ncols=10)
values(r) <- sample(3, ncell(r), replace=TRUE)
is.factor(r)

cls <- data.frame(id=1:3, cover=c("forest", "water", "urban"))
levels(r) <- cls
is.factor(r)
r

plot(r, col=c("green", "blue", "light gray"))
text(r, digits=3, cex=.75, halo=TRUE)

levels(r) <- data.frame(id=1:3, cover=c("forest", "water", "forest"))
levels(simplifyLevels(r))



# raster starts at 3
x <- r + 2
is.factor(x)

# Multiple categories
d <- data.frame(id=3:5, cover=cls[,2], letters=letters[1:3], value=10:12)
levels(x) <- d
x

# get current index
activeCat(x)
# set index 
activeCat(x) <- 3
activeCat(x)
activeCat(x) <- "letters"
plot(x, col=c("green", "blue", "light gray"))
text(x, digits=3, cex=.75, halo=TRUE)

r <- as.numeric(x)
r

p <- as.polygons(x)
plot(p, "letters", col=c("green", "blue", "light gray"))