-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathREADME.Rmd
132 lines (96 loc) · 5.18 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# hydroloom <img src="man/figures/logo.png" align="right" alt="" width="120" />
[](https://github.com/DOI-USGS/hydroloom/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/doi-usgs/hydroloom)
[](https://cran.r-project.org/package=hydroloom)
## 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:
```{r, eval=FALSE}
hydroloom::hydroloom_name_definitions
```
<details>
<summary>Click to See Definitions</summary>
```{r, echo=FALSE, eval=TRUE}
knitr::kable(data.frame(Name = names(hydroloom::hydroloom_name_definitions),
Definition = unname(hydroloom::hydroloom_name_definitions)))
```
</details>
<br/>
`hydroloom` supports your attribute names that map to the in-built definitions. See [`hydroloom_names()`](https://doi-usgs.github.io/hydroloom/reference/hydroloom_names.html) for more.
`hydroloom` supports both dendritic and non-dendritic networks start at [this vignette](https://doi-usgs.github.io/hydroloom/articles/non-dendritic.html) for more.
`hydroloom` was largely created from components of [nhdplusTools](https://doi.org/10.5066/P97AS8JD):
```
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.
```{r disclaimer, child="DISCLAIMER.md", eval=TRUE}
```
[
](https://creativecommons.org/publicdomain/zero/1.0/)