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

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

- 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 (**or by`rNumb=FALSE`

)**row numbers (**. If true, the argument`rNumb=TRUE`

)`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`

.

Named list of integer vectors.

**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]`

).

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.

```
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
```