Accumulate edge values downstream

Accumulate (sum) edge values downstream in a Landscape Network (LSN)

accum_edges(
  edges,
  lsn_path,
  sum_col,
  acc_col,
  save_local = TRUE,
  overwrite = FALSE,
  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 link{lines_to_lsn}.

sum_col

Name of an existing column in edges (character format) that contains the value to sum downstream.

acc_col

Name of the new column in edges (character format) where the accumulated sum_col values will be stored (see details).

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 acc_col already exists in edges or edges.gpkg already exists in lsn_path and save_local = 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 acc_col column. If save_local = TRUE, edges is saved to lsn_path in GeoPackage (.gpkg) format.

Details

accum_edges sums (i.e. accumulates) numeric values in edges downstream, from headwater or source features to each network outlet feature (i.e. most downstream line feature in each sub-network). Missing values are not allowed in sum_col and should be replaced with 0, or any other meaningful numeric value, prior to running accum_edges. The acc_col returned contains the sum of sum_col found in upstream edges, in addition the the sum_col for the edge itself. As such, acc_col represents the cumulative upstream sum of sum_col for the downstream node of each line feature in edges.

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
)

# Accumulate RCA area (rcaAreaKm2) downstream and store in a new
# column named WArea_km2
edges <- accum_edges(
  edges = edges,
  lsn_path = temp_dir,
  sum_col = "rcaAreaKm2",
  acc_col = "WArea_km2",
  save_local = FALSE,
  overwrite = TRUE,
  verbose = FALSE
)

summary(edges$WArea_km2)
#>     Min.  1st Qu.   Median     Mean  3rd Qu.     Max. 
#>   0.0036   2.4534   5.9877  22.6237  28.2600 209.8989