Calculate additive function values for sites in a Landscape Network (LSN)

afv_sites(
  sites,
  edges,
  afv_col,
  save_local = TRUE,
  lsn_path = NULL,
  overwrite = TRUE
)

Arguments

sites: A named list of one or more sf objects with POINT geometry that have been snapped to the LSN using sites_to_lsn.
edges: sf object with LINESTING geometry created using lines_to_lsn.
afv_col: Name of the column in edges containing the additive function value for each feature, in character format. Created using afv_edges.
save_local: Logical indicating whether the updated sites should be saved to lsn_path in GeoPackage format. File basenames are taken from the names assigned to the sites list. Default is TRUE.
lsn_path: Optional. Local pathname to a directory in character format specifying where the LSN resides, which is created using link[SSNbler]{lines_to_lsn}. Must be specified if save_local = TRUE.
overwrite: A logical indicating whether results should be overwritten if afv_col already exists in sites or sites.gpkg already exists in lsn_path and save_local = TRUE. Default = TRUE.

Value

One or more sf object(s) with all the original data from sites, along with a new afv_col column in each sites sf object. A named list is returned. If save_local = TRUE, a GeoPackage for each sf object is saved in lsn_path. Output file names are assigned based on the input sites attribute names.

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:

calculating the segment proportional influence (PI) values for the edges,
calculating the additive function values (AFVs) for the edges,
calculating the AFVs for the observed and prediction sites, and
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 additive function value (AFV) for an observed or prediction site is equal to the AFV of the edge the site resides on. Therefore, \(0 \le AFV \le 1\). See Peterson and Ver Hoef (2010) for a more detailed description of AFVs, how they are calculated, and how they are used in the tail up covariance function.

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
)

# Incorporate observed sites into the LSN
obs<- sites_to_lsn(
   sites = MF_obs,
   edges = edges,
   save_local = FALSE,
   snap_tolerance = 100,
   overwrite = TRUE,
   verbose = FALSE
)

# Incorporate the prediction dataset, preds, into the LSN
preds<- sites_to_lsn(sites = MF_preds,
   edges = edges,
   save_local = FALSE,
   snap_tolerance = 1,
   overwrite = TRUE,
   verbose = FALSE
)

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

# Calculate AFVs for observed sites (obs) and the prediction
# dataset, preds.
site.list<- afv_sites(
   sites = list(obs = obs,
                preds = preds),
   edges=edges,
   afv_col = "afvArea",
   save_local = FALSE,
   overwrite = TRUE
)

# Get names of sites in site.list
names(site.list)
#> [1] "obs"   "preds"

# Check AFVs stored in new column afvArea to ensure that 0 <= AFV
# <= 1 and that there are no NULL values.
summary(site.list$obs$afvArea)
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
#> 0.05144 0.15212 0.17089 0.24583 0.29944 1.00000 
summary(site.list$preds$afvArea)
#>     Min.  1st Qu.   Median     Mean  3rd Qu.     Max. 
#> 0.009894 0.031486 0.047469 0.092485 0.108067 0.672706