Get upstream distance for sites in a Landscape Network (LSN)

updist_sites(
  sites,
  edges,
  length_col,
  lsn_path,
  save_local = TRUE,
  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

An sf object with LINESTING geometry created using lines_to_lsn and link[SSNbler]{updist_edges}.

length_col

The name of the column in edges that contains the length of each edge feature.

lsn_path

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.

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.

overwrite

A logical indicating whether results should be overwritten if the upDist column already exists in sites or sites.gpkg already exists in lsn_path and save_local = TRUE. Default = TRUE.

#' @details updist_sites() calculates the total hydrologic distance from each observed or prediction point feature to the stream outlet (i.e. the most downstream location in the stream network), when movement is restricted to the stream network. We refer to this as the upstream distance.

Upstream distances are measured in the map projection units for the sf object containing the point features and stored in a new column named upDist.

The upstream distances stored in upDist are used to calculate the pairwise hydrologic distances used to fit spatial stream network models in the 'SSN2' package. Do not modify the name of the column in any way or the values the upDist column contains.

Value

One or more sf object(s) with all the original data from sites, along with a new upDist 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.

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, MF_obs, into LSN
obs<- sites_to_lsn(
   sites = MF_obs,
   edges = edges,
   save_local = FALSE,
   snap_tolerance = 100,
   overwrite = TRUE,
   verbose = FALSE
)

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

# Calculate upstream distance for edges
edges<- updist_edges(
   edges = edges,
   lsn_path = temp_dir,
   calc_length = TRUE,
   length_col = "Length",
   overwrite = TRUE,
   save_local = FALSE,
   verbose = FALSE
)

# Calculate upstream distance for observed sites (obs) and one
# prediction dataset (preds)
site.list<- updist_sites(
   sites = list(obs = obs,
                preds = preds),
   edges = edges,
   length_col= "Length",
   lsn_path = temp_dir,
   save_local = FALSE,
   overwrite = TRUE
)

# Summarize the new column upDist in obs
summary(site.list$obs$upDist)
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
#>   909.9  6281.2 10020.0 10176.9 14295.2 19566.2 

# Summarize the new column upDist in preds
summary(site.list$preds$upDist)
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
#>    3863    8030   12189   12370   15870   24337