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

Calculate the distance from the stream outlet (i.e. the most downstream location on the stream network) to the upstream node of each edge feature (i.e. upstream distance) in the Landscape Network (LSN)

updist_edges(
  edges,
  lsn_path = NULL,
  calc_length = FALSE,
  length_col = NULL,
  save_local = TRUE,
  overwrite = TRUE,
  verbose = 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.
calc_length: A logical indicating whether a column representing line length should be calculated and added to edges. Default = FALSE.
length_col: Optional. If calc_length = FALSE, length_col is the name of the column in the edges attribute table that contains the length of the edge feature. When calc_length = FALSE, length_col is required. If calc_length = TRUE, length_col is the name of the new column created in edges that will store the new length values for each feature, in character format. When calc_length = TRUE and length_col = NULL, the default for length_col is "Length".
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 the upDist column already exists in edges or edges.gpkg already exists in lsn_path and save_local = TRUE. Default = TRUE
verbose: Logical. Indicates whether messages about the function progress should be printed to the console. Defaults to TRUE.

Value

An sf object representing edges in the LSN, with a new upDist column. When calc_length = TRUE an additional column named length_col

Details

updist_edges() calculates the total hydrologic distance from the uppermost location on each edge feature (upstream node) 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 edges and stored in a new column in edges named upDist.

The upstream distances stored in upDist are used to calculate the upstream distance for sites in updist_sites() and 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.

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 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
)

# Notice that two new columns have been added to edges containing
# line feature length (Length) and the upstream distance (upDist)
names(edges)
#>  [1] "rid"        "COMID"      "GNIS_NAME"  "REACHCODE"  "FTYPE"     
#>  [6] "FCODE"      "AREAWTMAP"  "SLOPE"      "rcaAreaKm2" "h2oAreaKm2"
#> [11] "Length"     "upDist"     "geometry"  
summary(edges[,c("Length", "upDist")])
#>      Length            upDist                 geometry  
#>  Min.   :  16.55   Min.   :  270.6   LINESTRING   :163  
#>  1st Qu.: 588.88   1st Qu.: 7719.2   epsg:5070    :  0  
#>  Median :1374.09   Median :11270.8   +proj=aea ...:  0  
#>  Mean   :1600.88   Mean   :11684.1                      
#>  3rd Qu.:2417.89   3rd Qu.:14791.9                      
#>  Max.   :6321.20   Max.   :26164.3