MyNixOS website logo
Description

Utilities to Weave Hydrologic Fabrics.

A collection of utilities that support creation of network attributes for hydrologic networks. Methods and algorithms implemented are documented in Moore et al. (2019) <doi:10.3133/ofr20191096>), Cormen and Leiserson (2022) <ISBN:9780262046305> and Verdin and Verdin (1999) <doi:10.1016/S0022-1694(99)00011-6>.

hydroloom

R-CMD-check codecov CRAN

hydroloom:

Install:install.packages("hydroloom")

Or for latest development: remotes::install_github("doi-usgs/hydroloom")

hydroloom is a collection of functions to work with hydrologic geospatial fabrics. Hydroloom is designed to provide general hydrologic network functionality for any hydrographic or hydrologic data. The package intended for developers of workflows and other packages that require low level network and network data manipulation utilities.

To Learn More, visit the pkgdown site: https://doi-usgs.github.io/hydroloom/articles/hydroloom.html

Citation:

Blodgett, D., 2023, hydroloom: Utilities to Weave Hydrologic Fabrics, 
https://doi.org/10.5066/P9AQCUY0

Hyroloom has support for attributes that can be seen in:

hydroloom::hydroloom_name_definitions
Click to See Definitions
NameDefinition
idshared network identifier for catchment divide and flowpath or flowline
toidindicates to the downstream id. May or may not be dendritic
fromnodeindicates the node representing the nexus upstream of a catchment
tonodeindicates the node representing the nexus downstream of a catchment
divergenceindicates whether a catchment is not downstream of a diversion (0), the primary path downstream of a divergence (1), or a minor path downstream of a diversion (2).
wbidwaterbody id
total_da_sqkmtotal drainage area at the outlet of a catchment
da_sqkmlocal drainage area of a catchment
length_kmlength of a single catchment’s flowpath
pathlength_kmdistance from the outlet of a catchment to the terminal outlet of a network
arbolate_sumtotal accumulated length of all upstream flowlines
topo_sortSimilar to hydrosequence in NHDPlus. Large topo_sort values are upstream of small topo_sort values. Note that there are many valid topological sort orders of a directed graph.
up_topo_sorttopo sort value of the upstream mainstem
dn_topo_sorttopo sort value of the downstream mainstem
dn_minor_topo_sorttopo sort value of the downstream minor network element with the smallest id
terminal_topo_sorttopo sort value of the outlet network element
terminal_flag1 for network terminous 0 for within network
terminal_idid of terminal catchment for entire drainage basin
start_flag1 for a headwater, 0 otherwise
levelpathprovides an identifier for the collection of flowpaths that make up a single mainstem flowpath of a drainage basin
up_levelpathlevelpath value of the upstream mainstem
dn_levelpathlevelpath value of the downstream mainstem
levelpath_outlet_idid of outlet catchment of a levelpath
stream_levelstarting at 1 for coastal terminals and 4 for inland terminals increments by 1 for each smaller tributary level
dn_stream_levelstream level of downstream mainstem network element
stream_orderstarting at 1 for headwaters increments by 1 for each larger tributary level, divergences adopt stream order from upstream but returning divergent network does not increment stream order
stream_calculatorstarting at 1 for headwaters and 0 along diverted paths increments by 1 for each larger tributary level, does no increment along diverted paths. Is equal to stream_order along the dendritic network
feature_typedescriptive feature type moniker
feature_type_codecompact feature type identifier
vector_proc_unitidentifier for processing units based on vector encapsulation
raster_proc_unitidentifier for processing units based on raster encapsulation
id_measureinterpolative linear reference measure along a single identified feature
aggregate_idaggregate identifier useful for ‘reach’ or ‘flowpath’ aggregation of flowlines
aggregate_id_measureinterpolative linear reference measure along an aggregate feature
aggregate_id_from_measureinterpolative linear reference for downstream end of a single feature that makes up an aggregate feature
aggregate_id_to_measureinterpolative linear reference for the upstream end of a single feature that makes up an aggregate feature
point_ididentifier of hydrologic location point
offsetoffset distance from point to line in units of linear reference analysis units

hydroloom supports your attribute names that map to the in-built definitions. See hydroloom_names() for more.

hydroloom supports both dendritic and non-dendritic networks start at this vignette for more.

hydroloom was largely created from components of nhdplusTools:

Blodgett, D., Johnson, J.M., 2022, nhdplusTools: Tools for
  Accessing and Working with the NHDPlus,
  https://doi.org/10.5066/P97AS8JD

hydroloom will support some key functionality of nhdplusTools. Some components of nhdplusTools will be deprecated in a future version of the package in favor of the hydroloom implementation. In general, nhdplusTools will continue to support web service functionality and particulars of the NHDPlus data model. In contrast, hydroloom is intended to be more general and focused specifically on hydro fabric data functionality.

hydroloom implements algorithms documented in:

NHDPlus Attributes:

Moore, R.B., McKay, L.D., Rea, A.H., Bondelid, T.R., Price, C.V., Dewald, T.G., 
  and Johnston, C.M., 2019, User's guide for the national hydrography dataset 
  plus (NHDPlus) high resolution: U.S. Geological Survey Open-File Report 2019–1096, 
  66 p., https://doi.org/10.3133/ofr20191096.

Graph Concepts:

Cormen, T. H., & Leiserson, C. E. (2022). Introduction to 
  Algorithms, fourth edition. MIT Press.

Pfafstetter Attributes:

Verdin, K. L., & Verdin, J. P. (1999). A topological system for 
  delineation and codification of the Earth's river basins. 
  Journal of Hydrology, 218(1–2), 1–12. 
  https://doi.org/10.1016/S0022-1694(99)00011-6

Terminology:

The following definitions have been used as much as possible throughout the package.
Terms for rivers:
Flowline: A flowline is an linear geometry that represents a segment of a flowing body of water. Some flowlines have no local drainage area and are never aggregate features.
Flowpath: A flowpath is a linear geometry that represents the connection between a catchment’s inlet and its outlet. All flowpaths have a local drainage area and may be aggregates of flowlines.
Catchment: A physiographic unit with zero or one inlets and one outlet. A catchment is represented by one or more partial realizations; flowpath, divide, and networks of flowpaths and divides.
Catchment Divide: The polygon boundary that encompasses a catchment.

Design Notes:

  • Hydroloom uses tibble because dplyr verbs for data.frame was dropping the custom hy attributes.
  • The data.table package is used for some key joins to enhance scalability but dplyr is preferred for clarity.
  • hy class tibble standardizes all attribute names in code.
  • graph representation facilitated by make_index_ids() and make_fromids()
  • names are plural when referring to identifiers and singular when referring to a numerical attribute.

Disclaimer

This software is preliminary or provisional and is subject to revision. It is being provided to meet the need for timely best science. The software has not received final approval by the U.S. Geological Survey (USGS). No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. The software is provided on the condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from the authorized or unauthorized use of the software.

CC0

Metadata

Version

1.0.2

License

Unknown

Platforms (75)

    Darwin
    FreeBSD
    Genode
    GHCJS
    Linux
    MMIXware
    NetBSD
    none
    OpenBSD
    Redox
    Solaris
    WASI
    Windows
Show all
  • aarch64-darwin
  • aarch64-genode
  • aarch64-linux
  • aarch64-netbsd
  • aarch64-none
  • aarch64_be-none
  • arm-none
  • armv5tel-linux
  • armv6l-linux
  • armv6l-netbsd
  • armv6l-none
  • armv7a-darwin
  • armv7a-linux
  • armv7a-netbsd
  • armv7l-linux
  • armv7l-netbsd
  • avr-none
  • i686-cygwin
  • i686-darwin
  • i686-freebsd
  • i686-genode
  • i686-linux
  • i686-netbsd
  • i686-none
  • i686-openbsd
  • i686-windows
  • javascript-ghcjs
  • loongarch64-linux
  • m68k-linux
  • m68k-netbsd
  • m68k-none
  • microblaze-linux
  • microblaze-none
  • microblazeel-linux
  • microblazeel-none
  • mips-linux
  • mips-none
  • mips64-linux
  • mips64-none
  • mips64el-linux
  • mipsel-linux
  • mipsel-netbsd
  • mmix-mmixware
  • msp430-none
  • or1k-none
  • powerpc-netbsd
  • powerpc-none
  • powerpc64-linux
  • powerpc64le-linux
  • powerpcle-none
  • riscv32-linux
  • riscv32-netbsd
  • riscv32-none
  • riscv64-linux
  • riscv64-netbsd
  • riscv64-none
  • rx-none
  • s390-linux
  • s390-none
  • s390x-linux
  • s390x-none
  • vc4-none
  • wasm32-wasi
  • wasm64-wasi
  • x86_64-cygwin
  • x86_64-darwin
  • x86_64-freebsd
  • x86_64-genode
  • x86_64-linux
  • x86_64-netbsd
  • x86_64-none
  • x86_64-openbsd
  • x86_64-redox
  • x86_64-solaris
  • x86_64-windows