SSNbler (version 1.1.0)

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

Description

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

Usage

updist_sites(
  sites,
  edges,
  length_col,
  lsn_path,
  save_local = TRUE,
  overwrite = TRUE
)

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.

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 LINESTRING 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 or length_col columns already exist in sites or sites.gpkg already exists in lsn_path. 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. If the upDist or length_col columns already exist in sites and overwrite = TRUE, the columns will be deleted from all sites.,

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)

# Summarize the new column upDist in preds
summary(site.list$preds$upDist)