terra (version 1.6-7)

factors: Categorical rasters

Description

A SpatRaster layer can be a categorical variable (factor). Like factors, categories are stored as indices (integer values) 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 cell values and the other column(s) providing the category labels.

If there are multiple columns with categories, you can set the "active" category.

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

To set categories for the first layers 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 for each layer. Use categories to set the categories for a specific layer or specific layers.

Usage

# S4 method for SpatRaster
levels(x)
# S4 method for SpatRaster
levels(x)<-value
# S4 method for SpatRaster
cats(x, layer, active=FALSE)
# S4 method for SpatRaster
categories(x, layer=1, value, index)
# S4 method for SpatRaster
is.factor(x)
# S4 method for SpatRaster
as.factor(x)

Value

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

Arguments

x

SpatRaster

layer

positive integer, the layer number or name

active

logical. If TRUE, only return the active category

value

a data.frame (ID, category) or vector with category names

index

positive integer, indicating the column in data.frame value to be used as the (active) category, (not counting the first column with the cell values)

See Also

activeCat, catalyze, set.cats

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)

# 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"))