pi.add {scapesClassification}

Position index addition

Description

Add new raster objects based on position index values.

Usage

pi.add(
  attTbl,
  ngbList,
  rNumb = FALSE,
  RO,
  mainPI = NULL,
  secPI = NULL,
  add.mPI = NULL,
  add.sPI = NULL,
  cond.filter = NULL,
  min.N = NULL,
  plot = FALSE,
  r = NULL
)

Arguments

attTbl

data.frame, the attribute table returned by the function attTbl.

ngbList

list, the list of neighborhoods returned by the function ngbList.

rNumb

logic, the neighborhoods of the argument ngbList are identified by cell numbers (rNumb=FALSE) or by row numbers (rNumb=TRUE) (see ngbList). It is advised to use row numbers for large rasters.

RO

column name, the name of the column with the raster object IDs.

mainPI

column name, the name of the column with main position index values.

secPI

column name, the name of the column with secondary position index values.

add.mPI

numeric, threshold of main position index values. Cells with values above the threshold are flagged as cells potentially being part of new raster objects.

add.sPI

numeric, threshold of secondary position index values. Cells with values above the threshold flagged as cells potentially being part of new raster objects.

cond.filter

character string, defines what cells have to be considered by the function the arguments. Test cell absolute conditions can be used (see conditions).

min.N

numeric, the minimum number of cells a raster object has to have to be included in the function output.

plot

logic, plot the results.

r

single or multi-layer raster of the class SpatRaster (see help("rast", terra)) used to compute the attribute table. Required only if plot = TRUE.

Details

New raster objects are added based on position index values. Two different position indices can be passed to the function (mainPI and secPI).

• Input raster objects are assigned to the same class to flag cells that are part of raster objects;

• Cells with values above mainPI OR above mainPI are flagged as cells potentially being part of new raster objects;

• If not connected to any of the existing raster objects, the groups of cells above position index values are assigned to new raster objects.

• Only raster objects with at least as many cells as specified by the argument min.N are included in the function output.

• If both mainPI and secPI are equal to NULL, the function will exclusively filter raster objects based on their size (min.N).

Value

The function returns a class vector with raster objects IDs. The vector has length equal to the number of rows of the attribute table. NA values are assigned to cells that do not belong to any raster object.

Note

Raster objects are added only if they do not share any border with input raster objects.

See Also

attTbl(), ngbList(), rel.pi(), pi.sgm(), conditions()

Examples

# DUMMY DATA
######################################################################################
# LOAD LIBRARIES
library(scapesClassification)
library(terra)

# LOAD THE DUMMY RASTER
r <- list.files(system.file("extdata", package = "scapesClassification"),
                pattern = "dummy_raster\\.tif", full.names = TRUE)
r <- terra::rast(r)

# COMPUTE THE ATTRIBUTE TABLE
at <- attTbl(r, "dummy_var")

# COMPUTE THE LIST OF NEIGBORHOODS
nbs <- ngbList(r, attTbl=at)

################################################################################
# COMPUTE RASTER OBJECTS
################################################################################
at$RO[at$dummy_var==8] <- 1
at$RO <- cond.4.nofn(at, nbs, classVector = at$RO, class=1, nbs_of = 1,
                     cond = "dummy_var < dummy_var[] & dummy_var > 2")

# One raster object
unique(at$RO)

################################################################################
# POSITION INDEX
################################################################################
at$PI <- (at$dummy_var - mean(at$dummy_var))/stats::sd(at$dummy_var)

################################################################################
# POSITION INDEX ADDITION
################################################################################
RO1 <- pi.add(at, nbs,
              RO = "RO",     # Raster objects
              mainPI = "PI", # PI addition layer
              add.mPI = 1,   # add disjoint objects with PI values > 1
              plot = FALSE, r = r)

################################################################################
# PLOT
################################################################################
# Convert class vectors to raster
r_RO  <- cv.2.rast(r = r, classVector = at$RO)
r_RO1 <- cv.2.rast(r = r, classVector = RO1)

# Plot
oldpar <- par(mfrow = c(1,2))
m <- c(4.5, 0.5, 2, 3.2)

terra::plot(r_RO, type="classes", main="Raster objects - Input", mar=m,
            plg=list(x=1, y=1, cex=0.9))

terra::plot(r_RO1, type="classes", main="Raster objects - Output", mar=m,
            plg=list(x=1, y=1, cex=0.9))
text(xyFromCell(r,at$Cell), as.character(round(at$PI,2)),
cex = 0.8) # visualize relPI
text(0.01, 1, "Add on PI >= 1", adj=c(0,0), cex = 0.8)
par(oldpar)

# Two raster object
unique(RO1)