List of neighborhoods

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

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

Arguments

r: 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±1, y), (x, y±1) and (x±1, y±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]).

Note

There is always a correspondence between the indices of the attribute table (attTbl) and the indices of the list of neighborhoods: the 1st element of the list corresponds to the neighbors of the cell stored in the 1st row of the attribute table; the 2nd element corresponds to the 2nd row; etc.
There is a correspondence between the raster cell number and the indices of the list of neighborhoods only when no missing value is present in the raster.

Examples

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
#> $`2`
#> [1] 1 3 4 5 6
#> 
#> $`3`
#> [1] 2 5 6
#> 
#> $`5`
#> [1] 1 2 3 4 6 7 8 9
#> 
#> $`6`
#> [1] 2 3 5 8 9
#> 
#> $`7`
#> [1] 4 5 8
#> 
#> $`8`
#> [1] 4 5 6 7 9
#> 
#> $`9`
#> [1] 5 6 8
#> 


## NEIGHBORHOODS - ROW NUMBERS ##

# Cells 1 and 4 are omitted because they are NAs
nbs_ROW <- ngbList(r, rNumb = TRUE, attTbl = at)
nbs_ROW
#> $`1`
#> [1] 2 3 4
#> 
#> $`2`
#> [1] 1 3 4
#> 
#> $`3`
#> [1] 1 2 4 5 6 7
#> 
#> $`4`
#> [1] 1 2 3 6 7
#> 
#> $`5`
#> [1] 3 6
#> 
#> $`6`
#> [1] 3 4 5 7
#> 
#> $`7`
#> [1] 3 4 6
#> 

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

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

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


## 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]
#>   lyr.1
#> 1    NA

# Neighborhood cell #2 corresponds to cells:
nbs_CELL[1]
#> $`2`
#> [1] 1 3 4 5 6
#> 

# Neighborhood cell #2 corresponds to rows:
nbs_ROW[1]
#> $`1`
#> [1] 2 3 4
#> 

# Rows can be converted to cell numbers
at$Cell[ nbs_ROW[[1]] ]
#> [1] 3 5 6

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

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

Arguments

Value

Details

Note

See also

Examples