Skip to content

Commit

Permalink
use knitr for definitions and doco for #12
Browse files Browse the repository at this point in the history
  • Loading branch information
@dblodgett-usgs
dblodgett-usgs committed Sep 18, 2023
1 parent c4cb694 commit 9833e20
Show file tree
Hide file tree
Showing 6 changed files with 56 additions and 122 deletions.
2 changes: 1 addition & 1 deletion DESCRIPTION
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Authors@R:
Description: A collection of utilities that support creation of network attributes for hydrologic networks.
Depends: R (>= 4.0)
Imports: dplyr, data.table, sf, units, stats, methods, utils, pbapply, tidyr, RANN, rlang, fastmap
Suggests: testthat, nhdplusTools, future, lwgeom, future.apply
Suggests: testthat, nhdplusTools, future, lwgeom, future.apply, knitr
Remotes: doi-usgs/nhdplusTools@hydroloom, dblodgett-usgs/pbapply@master
License: CC0
Encoding: UTF-8
Expand Down
37 changes: 10 additions & 27 deletions R/00_hydroloom.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,54 +83,37 @@ hnd$id <- "shared network identifier for catchment divide and flowpath or flowli
hnd$toid <- "indicates to the downstream id. May or may not be dendritic"
hnd$fromnode <- "indicates the node representing the nexus upstream of a catchment"
hnd$tonode <- "indicates the node represneting the nexus downstream of a catchment"
hnd$divergence <-
"indicates whether a catchment is not downstream of a diversion (0),
\t the primary path downstream of a divergence (1),
\t or a minor path downstream of a diversion (2)."
hnd$divergence <- "indicates 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)."
hnd$wbid <- "waterbody id"
hnd$total_da_sqkm <- "total drainage area at the outlet of a catchment"
hnd$da_sqkm <- "local drainage area of a catchment"
hnd$length_km <- "length of a single catchment's flowpath"
hnd$pathlength_km <- "distance from the outlet of a catchment to the terminal
\t outlet of a network"
hnd$pathlength_km <- "distance from the outlet of a catchment to the terminal outlet of a network"
hnd$arbolate_sum <- "total accumulated length of all upstream flowlines"
hnd$topo_sort <- "Similar to hydrosequence in NHDPlus. Large topo_sort values
\t are upstream of small topo_sort values. Note that there are
\t many valid topological sort orders of a directed graph."
hnd$topo_sort <- "Similar 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."
hnd$up_topo_sort <- "topo sort value of the upstream mainstem"
hnd$dn_topo_sort <- "topo sort value of the downstream mainstem"
hnd$dn_minor_topo_sort <- "topo sort value of the downstream minor network
\t element with the smallest id"
hnd$dn_minor_topo_sort <- "topo sort value of the downstream minor network element with the smallest id"
hnd$terminal_topo_sort <- "topo sort value of the outlet network element"
hnd$terminal_flag <- "1 for network terminous 0 for within network"
hnd$terminal_id <- "id of terminal catchment for entire drainage basin"
hnd$start_flag <- "1 for a headwater, 0 otherwise"
hnd$levelpath <- "provides an identifier for the collection of flowpaths
\t that make up a single mainstem flowpath of a drainage
\t basin"
hnd$levelpath <- "provides an identifier for the collection of flowpaths that make up a single mainstem flowpath of a drainage basin"
hnd$up_levelpath <- "levelpath value of the upstream mainstem"
hnd$dn_levelpath <- "levelpath value of the downstream mainstem"
hnd$stream_level <- "starting at 1 for coastal terminals and 4 for inland terminals
\t increments by 1 for each smaller tributary level"
hnd$stream_level <- "starting at 1 for coastal terminals and 4 for inland terminals increments by 1 for each smaller tributary level"
hnd$dn_stream_level <- "stream level of downstream mainstem network element"
hnd$stream_order <- "starting at 1 for headwaters increments by 1 for each larger
\t tributary level, divergences adopt stream order from upstream
\t but returning divergent network does not increment stream order"
hnd$stream_calculator <- "starting at 1 for headwaters and 0 along divirted paths
\t increments by 1 for each larger tributary level, does not
\t increment along diverted paths. Is equal to stream_order
\t along the dendritic network"
hnd$stream_order <- "starting 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"
hnd$stream_calculator <- "starting at 1 for headwaters and 0 along divirted paths increments by 1 for each larger tributary level, does no increment along diverted paths. Is equal to stream_order along the dendritic network"
hnd$feature_type <- "descriptive feature type monicker"
hnd$feature_type_code <- "compact feature type identifier"
hnd$vector_proc_unit <- "identifier for processing units based on vector encapsulation"
hnd$raster_proc_unit <- "identifier for processing units based on raster encapsulation"
hnd$id_measure <- "interpolative linear reference measure along a single identified feature"
hnd$aggregate_id <- "aggregate identifier useful for 'reach' or 'flowpath' aggregation of flowlines"
hnd$aggregate_id_measure <- "interpolative linear reference measure along an aggregate feature"
hnd$aggregate_id_from_measure <- "interpolative linear reference for downstream end of a single
\t feature that makes up an aggregate feature"
hnd$aggregate_id_to_measure <- "interpolative linear reference for the upstream end of a single
\t feature that makes up an aggregate feature"
hnd$aggregate_id_from_measure <- "interpolative linear reference for downstream end of a single feature that makes up an aggregate feature"
hnd$aggregate_id_to_measure <- "interpolative linear reference for the upstream end of a single feature that makes up an aggregate feature"
hnd$point_id <- "identifier of hydrologic location point"
hnd$offset <- "offset distance from point to line in units of linear reference analysis units"
hnd$levelpath_outlet_id <- "id of outlet catchment of a levelpath"
Expand Down
1 change: 1 addition & 0 deletions R/add_levelpaths.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ required_atts_add_levelpaths <- c("id", "toid")
#' @param name_attribute character attribute to be used as name identifiers.
#' @param weight_attribute character attribute to be used as weight.
#' @param override_factor numeric multiplier to use to override `name_attribute`.
#' See details.
#' @param status boolean if status updates should be printed.
#' @return data.frame with id, levelpath_outlet_id, topo_sort, and levelpath columns.
#' See details for more info.
Expand Down
3 changes: 2 additions & 1 deletion README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ hydroloom::hydroloom_name_definitions
<summary>Click to See Definitions</summary>

```{r, echo=FALSE, eval=TRUE}
hydroloom::hydroloom_name_definitions
knitr::kable(data.frame(Name = names(hydroloom::hydroloom_name_definitions),
Definition = unname(hydroloom::hydroloom_name_definitions)))
```

</details>
Expand Down
132 changes: 40 additions & 92 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,98 +25,46 @@ hydroloom::hydroloom_name_definitions
Click to See Definitions
</summary>

#> 1 "id":
#> shared network identifier for catchment divide and flowpath or flowline
#> 2 "toid":
#> indicates to the downstream id. May or may not be dendritic
#> 3 "fromnode":
#> indicates the node representing the nexus upstream of a catchment
#> 4 "tonode":
#> indicates the node represneting the nexus downstream of a catchment
#> 5 "divergence":
#> indicates 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).
#> 6 "wbid":
#> waterbody id
#> 7 "total_da_sqkm":
#> total drainage area at the outlet of a catchment
#> 8 "da_sqkm":
#> local drainage area of a catchment
#> 9 "length_km":
#> length of a single catchment's flowpath
#> 10 "pathlength_km":
#> distance from the outlet of a catchment to the terminal
#> outlet of a network
#> 11 "arbolate_sum":
#> total accumulated length of all upstream flowlines
#> 12 "topo_sort":
#> Similar 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.
#> 13 "up_topo_sort":
#> topo sort value of the upstream mainstem
#> 14 "dn_topo_sort":
#> topo sort value of the downstream mainstem
#> 15 "dn_minor_topo_sort":
#> topo sort value of the downstream minor network
#> element with the smallest id
#> 16 "terminal_topo_sort":
#> topo sort value of the outlet network element
#> 17 "terminal_flag":
#> 1 for network terminous 0 for within network
#> 18 "terminal_id":
#> id of terminal catchment for entire drainage basin
#> 19 "start_flag":
#> 1 for a headwater, 0 otherwise
#> 20 "levelpath":
#> provides an identifier for the collection of flowpaths
#> that make up a single mainstem flowpath of a drainage
#> basin
#> 21 "up_levelpath":
#> levelpath value of the upstream mainstem
#> 22 "dn_levelpath":
#> levelpath value of the downstream mainstem
#> 23 "levelpath_outlet_id":
#> id of outlet catchment of a levelpath
#> 24 "stream_level":
#> starting at 1 for coastal terminals and 4 for inland terminals
#> increments by 1 for each smaller tributary level
#> 25 "dn_stream_level":
#> stream level of downstream mainstem network element
#> 26 "stream_order":
#> starting 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
#> 27 "stream_calculator":
#> starting at 1 for headwaters and 0 along divirted paths
#> increments by 1 for each larger tributary level, does not
#> increment along diverted paths. Is equal to stream_order
#> along the dendritic network
#> 28 "feature_type":
#> descriptive feature type monicker
#> 29 "feature_type_code":
#> compact feature type identifier
#> 30 "vector_proc_unit":
#> identifier for processing units based on vector encapsulation
#> 31 "raster_proc_unit":
#> identifier for processing units based on raster encapsulation
#> 32 "id_measure":
#> interpolative linear reference measure along a single identified feature
#> 33 "aggregate_id":
#> aggregate identifier useful for 'reach' or 'flowpath' aggregation of flowlines
#> 34 "aggregate_id_measure":
#> interpolative linear reference measure along an aggregate feature
#> 35 "aggregate_id_from_measure":
#> interpolative linear reference for downstream end of a single
#> feature that makes up an aggregate feature
#> 36 "aggregate_id_to_measure":
#> interpolative linear reference for the upstream end of a single
#> feature that makes up an aggregate feature
#> 37 "point_id":
#> identifier of hydrologic location point
#> 38 "offset":
#> offset distance from point to line in units of linear reference analysis units
| Name | Definition |
|:--------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| id | shared network identifier for catchment divide and flowpath or flowline |
| toid | indicates to the downstream id. May or may not be dendritic |
| fromnode | indicates the node representing the nexus upstream of a catchment |
| tonode | indicates the node represneting the nexus downstream of a catchment |
| divergence | indicates 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). |
| wbid | waterbody id |
| total_da_sqkm | total drainage area at the outlet of a catchment |
| da_sqkm | local drainage area of a catchment |
| length_km | length of a single catchment’s flowpath |
| pathlength_km | distance from the outlet of a catchment to the terminal outlet of a network |
| arbolate_sum | total accumulated length of all upstream flowlines |
| topo_sort | Similar 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_sort | topo sort value of the upstream mainstem |
| dn_topo_sort | topo sort value of the downstream mainstem |
| dn_minor_topo_sort | topo sort value of the downstream minor network element with the smallest id |
| terminal_topo_sort | topo sort value of the outlet network element |
| terminal_flag | 1 for network terminous 0 for within network |
| terminal_id | id of terminal catchment for entire drainage basin |
| start_flag | 1 for a headwater, 0 otherwise |
| levelpath | provides an identifier for the collection of flowpaths that make up a single mainstem flowpath of a drainage basin |
| up_levelpath | levelpath value of the upstream mainstem |
| dn_levelpath | levelpath value of the downstream mainstem |
| levelpath_outlet_id | id of outlet catchment of a levelpath |
| stream_level | starting at 1 for coastal terminals and 4 for inland terminals increments by 1 for each smaller tributary level |
| dn_stream_level | stream level of downstream mainstem network element |
| stream_order | starting 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_calculator | starting at 1 for headwaters and 0 along divirted 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_type | descriptive feature type monicker |
| feature_type_code | compact feature type identifier |
| vector_proc_unit | identifier for processing units based on vector encapsulation |
| raster_proc_unit | identifier for processing units based on raster encapsulation |
| id_measure | interpolative linear reference measure along a single identified feature |
| aggregate_id | aggregate identifier useful for ‘reach’ or ‘flowpath’ aggregation of flowlines |
| aggregate_id_measure | interpolative linear reference measure along an aggregate feature |
| aggregate_id_from_measure | interpolative linear reference for downstream end of a single feature that makes up an aggregate feature |
| aggregate_id_to_measure | interpolative linear reference for the upstream end of a single feature that makes up an aggregate feature |
| point_id | identifier of hydrologic location point |
| offset | offset distance from point to line in units of linear reference analysis units |

</details>

Expand Down
Loading

0 comments on commit 9833e20

Please sign in to comment.