-
Notifications
You must be signed in to change notification settings - Fork 33
/
README.Rmd
212 lines (164 loc) · 9.59 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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
---
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%"
)
```
# nhdplusTools <img src="man/figures/logo.png" align="right" alt="" width="120" />
 [](https://app.codecov.io/gh/doi-usgs/nhdplusTools) [](https://cran.r-project.org/package=nhdplusTools) [](https://cran.r-project.org/package=nhdplusTools)
## nhdplusTools: Tools for Accessing and Working with the NHDPlus and other US hydrographic data.
### Recommended Citation:
```
Blodgett, D., Johnson, J.M., 2022, nhdplusTools: Tools for
Accessing and Working with the NHDPlus,
https://doi.org/10.5066/P97AS8JD
```
### Installation:
```{r, eval = FALSE}
install.packages("nhdplusTools")
```
For the latest development:
```{r, eval = FALSE}
install.packages("remotes")
remotes::install_github("DOI-USGS/nhdplusTools")
```
### Resources
For data discovery and access in a U.S. context, start with the [**Getting Started page**](https://doi-usgs.github.io/nhdplusTools/articles/nhdplusTools.html).
Detailed documentation of all the package functions can be found at the [**Reference page**](https://doi-usgs.github.io/nhdplusTools/reference/).
### Data:
`nhdplusTools`, is designed to provide easy access to data associated with the U.S. National Hydrography Dataset. Many functions provided in `nhdplusTools` are thin wrappers around functions that have been migrated to `hydroloom`.
## Package Vision
The `nhdplusTools` package is intended to provide a reusable set of tools to
subset, relate data to, and generate network attributes for U.S. NHDPlus data.
General, globally applicable functionality has been moved to [`hydroloom`](https://github.com/DOI-USGS/hydroloom)
`nhdplusTools` implements a data model consistent with both the [NHDPlus](https://www.epa.gov/waterdata/nhdplus-national-hydrography-dataset-plus)
dataset and the [HY\_Features](http://opengeospatial.github.io/HY_Features/) data
model. The package aims to provide a set of tools that can be used to build
workflows using NHDPlus data.
**This vision is intended as a guide to contributors -- conveying what kinds of
contributions are of interest to the package's long term vision. It is a
reflection of the current thinking and is open to discussion and modification.**
### Functional Vision
The following describe a vision for the functionality that should be included
in the package in the long run.
##### Subsetting
The NHDPlus is a very large dataset both spatially and in terms of the number
of attributes it contains. Subsetting utilities will provide network location
discovery, network navigation, and data export utilities to generate spatial
and attribute subsets of the NHDPlus dataset.
##### Indexing
One of the most important roles of the NHDPlus is as a connecting network for
ancillary data and models. The first step in any workflow that uses the
network like this is indexing relevant data to the network. A number of methods
for indexing exist, they can be broken into two main categories: linear
referencing and catchment indexing. Both operate on features represented by
points, lines, and polygons. `nhdplusTools` should eventually support both
linear and catchment indexing.
### Data Model
Given that `nhdplusTools` is focused on working with NHDPlus data, the NHDPlus
data model will largely govern the data model the package is designed to work
with. That said, much of the package functionality also uses concepts from
the HY\_Features standard.
*Note:* The HY\_Features standard is based on the notion that a "catchment" is a
holistic feature that can be "realized" (some might say modeled) in a number of
ways. In other words, a catchment can *only* be characterized fully through a
collection of different conceptual representations. In NHDPlus, the "catchment"
feature is the polygon feature that describes the drainage divide around the
hydrologic unit that contributes surface flow to a given NHD flowline. While this
may seem like a significant difference, in reality, the NHDPlus COMID identifier
lends itself very well to the HY\_Features catchment concept. The COMID is
used as an identifier for the catchment polygon, the flowline that
connects the catchment inlet and outlet, and value added attributes that
describe characteristics of the catchment's interior. In this way, the COMID
identifier is actually an identifier for a collection of data that
together fully describe an NHDPlus catchment. [See the NHDPlus mapping to
HY_Features in the HY_Features specification.](https://docs.ogc.org/is/14-111r6/14-111r6.html#annexD_1)
Below is a description of the scope of data used by the
`nhdplusTools` package. While other data and attributes may come into scope,
it should only be done as a naive pass-through, as in data subsetting, or
with considerable deliberation.
##### Flowlines and Waterbodies
Flowline geometry is a mix of 1-d streams and 1-d "artificial paths". In order
to complete the set of features meant to represent water, we need to include
waterbody polygons.
##### Catchment Polygons
Catchment polygons are the result of a complete elevation derived hydrography
process with hydro-enforcement applied with both Watershed Boundary Dataset
Hydrologic Units and NHD reaches.
##### Network Attributes
The NHDPlus includes numerous attributes that are built using the network and
allow a wide array of capabilities that would require excessive iteration or
sophisticated and complex graph-oriented data structures and algorithms.
### Architecture
The NHDPlus is a very large dataset. The architecture of this package as it
relates to handling data and what dependencies are used will be very important.
##### Web vs Local Data
`nhdplusTools` offers a mix of web service and local data functionality.
Web services have generally been avoided for large processes. However,
applications that would require loading significant amounts of data to perform
something that can be accomplished with a web service very quickly are supported.
Systems like the [Network Linked Data Index](https://waterdata.usgs.gov/blog/nldi-intro/) are
used for data discovery.
##### NHDPlus Version
Initial package development focused on the [National Seamless NHDPlus](https://www.epa.gov/waterdata/nhdplus-national-data)
database. [NHDPlus High Resolution](https://www.usgs.gov/national-hydrography/nhdplus-high-resolution) is also supported.
### Related similar packages:
https://github.com/mbtyers/riverdist
https://github.com/jsta/nhdR
https://github.com/lawinslow/hydrolinks
https://github.com/mikejohnson51/HydroData
https://github.com/ropensci/FedData
https://github.com/hyriver/pygeohydro
... others -- please suggest additions?
### Build notes:
This package uses a convention to avoid building vignettes on CRAN. The `BUILD_VIGNETTES` environment variable must be set to `TRUE`. This is done with a .Renviron file in the package directory with the line `BUILD_VIGNETTES=TRUE`.
Given this, the package should be built locally to include vignettes using:
```r
devtools::build()
```
### Check notes:
In addition to typical R package checking, a Dockerfile is included in this repository. Once built, it can be run with the following command.
```
docker build -t nhdplustools_test .
docker run --rm -it -v $PWD:/src nhdplustools_test /bin/bash -c "cp -r /src/* /check/ && cp /src/.Rbuildignore /check/ && cd /check && Rscript -e 'devtools::build()' && R CMD check --as-cran ../nhdplusTools_*"
```
### Release procedure:
- ensure all checks pass and code coverage is adequate.
- ensure news has been updated
- convert disclaimer to [released form](https://code.usgs.gov/water/sbtools/-/blob/v1.1.14/README.md#L113)
- update version in inst/CITATION file
- update version in code.json file
- Build source package and upload to CRAN
- Once a new version has been accepted by cran,
- ensure pkgdown is up to date
- commit, push, and PR/MR changes
- create release page and tag
- attach cran tar.gz to release page
- update DOI to point to release page
- switch README disclaimer back to ["dev" mode.](https://code.usgs.gov/water/sbtools#disclaimer)
- Update version in Description.
- push an PR/MR changes.
### Contributing:
First, thanks for considering a contribution! I hope to make this package a community created resource
for us all to gain from and won't be able to do that without your help!
1) Contributions should be thoroughly tested with [`testthat`](https://testthat.r-lib.org/).
2) Code style should attempt to follow the [`tidyverse` style guide.](https://style.tidyverse.org/)
3) Please attempt to describe what you want to do prior to contributing by submitting an issue.
4) Please follow the typical github [fork - pull-request workflow.](https://gist.github.com/Chaser324/ce0505fbed06b947d962)
5) Make sure you use roxygen and run Check before contributing. More on this front as the package matures.
Other notes:
- consider running `lintr` prior to contributing.
- consider running `goodpractice::gp()` on the package before contributing.
- consider running `devtools::spell_check()` if you wrote documentation.
- this package uses pkgdown. Running `pkgdown::build_site()` will refresh it.
```{r disclaimer, child="DISCLAIMER.md", eval=TRUE}
```
[
](https://creativecommons.org/publicdomain/zero/1.0/)