hydroloom (version 1.1.0)

add_divergence: Add Divergence Attribute

Description

Given a non-dendritic flow network and required attributes, adds a divergence attribute according to NHDPlus data model methods.

Usage

add_divergence(
  x,
  coastal_outlet_ids,
  inland_outlet_ids,
  name_attr,
  type_attr,
  major_types
)
# S3 method for data.frame
add_divergence(
  x,
  coastal_outlet_ids,
  inland_outlet_ids,
  name_attr,
  type_attr,
  major_types
)
# S3 method for hy
add_divergence(
  x,
  coastal_outlet_ids,
  inland_outlet_ids,
  name_attr,
  type_attr,
  major_types
)

Value

returns x with a divergence attribute appended

Arguments

x

data.frame network compatible with hydroloom_names.

coastal_outlet_ids

vector of identifiers for network outlets that terminate at the coast.

inland_outlet_ids

vector of identifiers for network outlets that terminate inland.

name_attr

character attribute name of attribute containing a feature name or name identifier.

type_attr

character attribute name of attribute containing a feature type indicator.

major_types

vector of values of type_attr that should be interpreted as being "major". e.g. river might be major and canal might be minor.

Details

When considering downstream connections with diversions, there are three factors considered to determine which is primary.
1a) same name
1b) is named
2) feature type (type_attr controls this)
3) flows to coast (has a coastal connection is preferred)

The following list describes the order of precedence for tests
1: 1a, 2, 3
2: 1a, 2
3: The NHDPlus uses diverted fraction this is not used currently.
4: 1b, 2, 3
5: 2, 3
6: 1b, 3
7: 3,
8: 1b, 2
9: 2
10: 1b

If all checks return and no primary connection has been identified, the connection with a smaller id is chosen.

In the case that there are two or more upstream connections, the upstream name to use is chosen 1) if there is only one upstream flowline with a name 2) if one of the upstream flowlines with a name matches the downstream line, 3) if one of the upstream flowlines is of a "major" type and others are not, and, 4) if no criteria exist to select one, the smallest id value otherwise.

Examples

f <- system.file("extdata/coastal_example.gpkg", package = "hydroloom")

g <- sf::read_sf(f)
g <- g[g$FTYPE != "Coastline", ]

outlets <- g$COMID[!g$ToNode %in% g$FromNode]

g <- dplyr::select(g, COMID, gnis_id, FTYPE,
                   FromNode, ToNode)

add_divergence(g,
               coastal_outlet_ids = outlets,
               inland_outlet_ids = c(),
               name_attr = "gnis_id",
               type_attr = "FTYPE",
               major_types = c("StreamRiver", "ArtificialPath", "Connector"))