Calculate the additive function value for edges in a LSN

Source: R/afv_edges.R

Calculate the additive function value for each edge feature in a Landscape Network (LSN)

afv_edges(
  edges,
  lsn_path,
  infl_col,
  segpi_col,
  afv_col,
  save_local = TRUE,
  overwrite = TRUE
)

Arguments

edges

An sf object with LINESTING geometry created using lines_to_lsn.

lsn_path

Local pathname to a directory in character format specifying where relationships.csv resides, which is created using lines_to_lsn.

infl_col

Name of the existing column in the edges data.frame that will be used to generate the segment proportional influence (segment PI) for each line feature, in character format.

segpi_col

Name of the new column created in edges that will store the new segment proportional influence values for each feature, in character format.

afv_col

Name of the new column created in edges to store the additive function value for each feature, in character format.

save_local

Logical indicating whether the updated edges should be saved to lsn_path in GeoPackage format. Defaults to TRUE.

overwrite

A logical indicating whether results should be overwritten if segpi_col and/or afv_col already exists in edges, or edges.gpkg already exists in lsn_path and save_local = TRUE. Default = TRUE.

Value

An sf object representing edges in the LSN, with new segpi_col and afv_col columns. If save_local = TRUE, the updated version of edges will be saved as edges.gpkg in lsn_path.

Details

Spatial weights are used when fitting statistical models with 'SSN2' to split the tail-up covariance function upstream of network confluences, which allows for the disproportionate influence of one upstream edge over another (e.g., a large stream channel converges with a smaller one) on downstream values. Calculating the spatial weights is a four-step process:

  1. calculating the segment proportional influence (PI) values for the edges,

  2. calculating the additive function values (AFVs) for the edges,

  3. calculating the AFVs for the observed and prediction sites, and

  4. calculating the spatial weights for observed and prediction sites.

Steps 1) and 2) are undertaken in afv_edges, Step 3) is calculated in afv_sites(), and Step 4) is calculated in the package 'SSN2' when spatial stream-network models that include the tail-up covariance function are fit using ssn_lm or ssn_glm.

The segment PI for each edge, \(\omega_j\), is defined as the relative influence of the j-th edge feature on the edge directly downstream. \(\omega_j\) is often based on cumulative watershed area for the downstream node of each edge, which is used as a surrogate for flow volume. However, simpler measures could be used, such as Shreve's stream order (Shreve 1966) or equal weighting, as long as a value exists for every line feature in edges (i.e., missing data are not allowed). It is also preferable to use a column that does not contain values equal to zero, which is explained below.

The segment PI values produced in afv_edges() are ratios. Therefore, the sum of the PI values for edges directly upstream of a single node always sum to one. Also note that \(\omega_j=0\) when \(A_j=0\).

The AFVs for the j-th edge, \(AFV_j\), is equal to the product of the segment PIs found in the path between the edge and the network outlet (i.e., most downstream edge in the network), including edge j itself. Therefore, \(0 \le AFV \le 1\). If \(\omega_j=0\), the AFV values for edges upstream of the j-th edge will also be equal to zero. This may not be problematic if the j-th edge is a headwater segment without an observed site. However, it can have a significant impact on the covariance structure of the tail-up model when the j-th edge is found lower in the stream network.

A more detailed description of the segment PIs and the steps used to calculate AFVs are provided in Peterson and Ver Hoef (2010; Appendix A).

References

Peterson, E.E. and Ver Hoef, J.M. (2010) A mixed-model moving-average approach to geostatistical modeling in stream networks. Ecology 91(3), 644–651.

Examples

# Get temporary directory, where the example LSN will be stored
# locally.
temp_dir <- tempdir()

# Build the LSN. When working with your own data, lsn_path will be
# a local folder of your choice rather than a temporary directory.
edges <- lines_to_lsn(
  streams = MF_streams,
  lsn_path = temp_dir,
  snap_tolerance = 1,
  check_topology = FALSE,
  overwrite = TRUE,
  verbose = FALSE
)

# Calculate the AFV for the edges using an existing column
# representing watershed area for the downstream node of each line
# feature (h2oAreaKm2).
edges <- afv_edges(
  edges = edges,
  infl_col = "h2oAreaKm2",
  segpi_col = "areaPI",
  lsn_path = temp_dir,
  afv_col = "afvArea",
  overwrite = TRUE,
  save_local = FALSE
)

# Check AFVs stored in new column afvArea to ensure that 0 <= AFV
# <= 1 and that there are no NULL values.
summary(edges$afvArea)
#>     Min.  1st Qu.   Median     Mean  3rd Qu.     Max. 
#> 0.004709 0.026168 0.066095 0.160335 0.169575 1.000000