ngbList: List of neighborhoods

Description

Computes the neighborhoods of the cells of a raster. Neighborhoods are not computed for cells with missing values.

Usage

ngbList(r, rNumb = FALSE, attTbl = NULL)

Arguments

single or multi-layer raster of the class SpatRaster (see help("rast", terra)).

rNumb

logic, the neighbors of a raster cell are identified by cell numbers (rNumb=FALSE) or by row numbers (rNumb=TRUE). If true, the argument attTbl cannot be NULL.

attTbl

data.frame, the attribute table returned by the function attTbl (see attTbl). It is required only if the argument rNumb=TRUE.

Value

Named list of integer vectors.

Details

Definition of neighborhood

A cell with coordinates (x, y) has 8 neighbors with coordinates: (x<U+00B1>1, y), (x, y<U+00B1>1) and (x<U+00B1>1, y<U+00B1>1). Cells on the edge of a raster have less than 8 neighbors.

Neighborhoods (rNumb=FALSE)

Neighbors are identified by their cell numbers if the argument rNumb=FALSE.

Neighborhoods (rNumb=TRUE)

Neighbors are identified by their positions in the attribute table (i.e. row numbers) if the argument rNumb=TRUE;
When the argument rNumb = TRUE, neighbors with missing values are omitted;
(scapes)Classifications are faster when the list of neighborhoods uses row numbers.

Neighborhood names

The list of neighborhoods is named.

When rNumb = FALSE, the element name identifies the raster cell to which the neighborhood refers. For instance, the element with name "n" stores the neighborhood of the raster cell n.
When rNumb = TRUE, the element name identifies the row number to which the neighborhood refers. For instance, the element with name "n" stores the neighborhood of the raster cell located in the nth row of the attribute table (attTbl$Cell[n]).

Examples

Run this code

# NOT RUN {
library(scapesClassification)
library(terra)

## CREATE A DUMMY RASTER AND COMPUTE ATTRIBUTE TABLE ##
r <- terra::rast(matrix(c(NA,100,100,NA,100,100,0,0,0),
                        nrow = 3,
                        ncol = 3,
                        byrow = TRUE))

at <- attTbl(r, var_names = c("dummy_var"))

## RASTER CELL NUMBERS ##
rcn <- r; rcn[] <- 1:9

## PLOT DATA AND CELL NUMBERS ##
oldpar <- par(mfrow = c(1,2))
m <- c(4, 1, 4, 1)

plot(r, col="grey90", colNA="red3", mar=m, asp=NA, axes=FALSE, legend=FALSE)
text(r)
lines(r)
mtext(side=3, line=0.2, adj=0, cex=1.5, font=2, "Dummy_var")
legend("bottomright", ncol = 1, bg = "white", fill = c("red3"),
       legend = c("NA cells (1 and 4)"))

plot(rcn, col="grey90", mar=m, asp = NA, axes=FALSE, legend=FALSE)
text(rcn)
lines(rcn)
mtext(side=3, line=0.2, adj=0, cex=1.5, font=2, "Cell numbers")
par(oldpar)

## NEIGHBORHOODS - CELL NUMBERS ##

# Cells 1 and 4 are omitted because they are NAs
nbs_CELL <- ngbList(r, rNumb = FALSE)
nbs_CELL


## NEIGHBORHOODS - ROW NUMBERS ##

# Cells 1 and 4 are omitted because they are NAs
nbs_ROW <- ngbList(r, rNumb = TRUE, attTbl = at)
nbs_ROW

# Numbers in 'nbs_ROW' refer to row numbers
# (e.g. number 1 refers to the cell #2)
at$Cell[1]

# (e.g. number 2 refers to the cell #3)
at$Cell[2]

# (e.g. number 5 refers to the cell #7)
at$Cell[5]


## CONSIDER THE NEIGHBORHOOD OF CELL #2 ##

# Cell #2 corresponds to the 1st element of both 'nbs_CELL' and 'nbs_ROW'
# because raster cell 1 is an NA-cell
r[1]

# Neighborhood cell #2 corresponds to cells:
nbs_CELL[1]

# Neighborhood cell #2 corresponds to rows:
nbs_ROW[1]

# Rows can be converted to cell numbers
at$Cell[ nbs_ROW[[1]] ]

# Note that 'at$Cell[ nbs_ROW[[1]] ]' is not equal to 'nbs_CELL'
identical( at$Cell[ nbs_ROW[[1]] ] , nbs_CELL[[1]] )

# This is because raster cells 1 and 4 (NA-cells) are omitted in 'nbs_ROW'
setdiff(nbs_CELL[[1]], at$Cell[ nbs_ROW[[1]] ])
r[c(1,4)]
# }