covariate_river: Attribute covariates to nodes of a river network

Description

Attributes covariate values from raster files to subcatchments of a river object. Both local and upstream-averaged covariate values are calculated.

Usage

covariate_river(x, river, categorical = TRUE, overwrite = FALSE)

Value

A river object. The following elements are added:

SC$locCov: Data frame of covariates evaluated as local values for each subcatchment (i.e., mean covariate value within a catchment).
SC$upsCov: Data frame of covariates evaluated as upstream-averaged values for each subcatchment (i.e., mean covariate value within the area upstream of a given subcatchment, including the subcatchment itself).

Arguments

x: SpatRaster object (obtained via rast) containing categorical or continuous variables from which covariates are computed. Its coordinate system must be the same of river. Consider using terra::project to change coordinate system.
river: river object. It must have been aggregated (via aggregate_river).
categorical: Logical. Is the covariate categorical (e.g. land cover classes)? If x consists of several layers, it is possible to specify categorical as a vector of logicals (one per each layer); alternatively, the single value of categorical is applied to all layers of x.
overwrite: Logical. If TRUE, overwrite previously calculated covariates.

Details

If categorical = TRUE, the number of columns of SC$locCov, SC$upsCov is equal to the number of unique values of x within the catchment. Column names are composed as "y_z", where y = names(x) and z are the unique values of x. Values correspond to the fraction of pixels (FD nodes) within the local/upstream area that are covered by a given category (e.g., land cover type).

If categorical = FALSE, SC$locCov and SC$upsCov have a single column named names(x). Values correspond to the mean covariate value within the local/upstream reference area.

If x has multiple layers, columns in the data frames are added sequentially. The same occurs if covariate_river is run repeated times (for instance, to compute covariates for one SpatRaster object at a time) when overwrite = FALSE.

Examples

Run this code

if (FALSE) { # interactive() && traudem::can_register_taudem()
# \donttest{
 
fp <- system.file("extdata/wigger.tif", package="rivnet")
river <- extract_river(outlet=c(637478,237413),
                       DEM=fp)
river <- aggregate_river(river)

# land cover raster file (categorical)
r1 <- terra::rast(system.file("extdata/landcover.tif", package="rivnet")) 
# legend: 1-urban; 2-agriculture; 3-forest; 4-improductive

river <- covariate_river(r1, river)

plot(river$SC$locCov[ , 1], river) # fraction of urban area within a subcatchment
plot(river$SC$upsCov[ , 1], river) # fraction of upstream-averaged urban area  
 
# mean air temperature raster file (continuous) 
r2 <- terra::rast(system.file("extdata/temperature.tif", package="rivnet"))

river <- covariate_river(r2, river, categorical = FALSE)

plot(river$SC$locCov[, 5], river) # the layer has been added after the 4 previous ones
 
names(river$SC$locCov) 
 
 # }
}