Review Facilitation PR

.Rbuildignore

@@ -31,3 +31,9 @@ README.Rmd
 CONTRIBUTING.md
 cran-comments.md
 ^CRAN-SUBMISSION$
+.lintr
+.vscode
+.*temp.*
+revdep
+.claude
+CLAUDE.md

.github/workflows/R-CMD-check.yaml

@@ -16,6 +16,7 @@ jobs:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
       _R_CHECK_TESTS_NLINES_: 0
       NOT_CRAN: true
+      HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK: true
     strategy:
       fail-fast: false
       matrix:

.gitignore

@@ -5,3 +5,7 @@
 .Renviron
 cran-comments.md
 CRAN-SUBMISSION
+*temp*
+.vscode/
+revdep/
+CLAUDE.md

.lintr

@@ -0,0 +1,6 @@
+linters: linters_with_defaults(
+  line_length_linter(120),
+  indentation_linter = NULL,
+  object_usage_linter = NULL,
+  object_name_linter = NULL
+  )

DESCRIPTION

@@ -1,22 +1,26 @@
 Package: hydroloom
 Title: Utilities to Weave Hydrologic Fabrics
-Version: 1.0.0
-Authors@R: 
+Version: 1.2.0
+Authors@R: c(
     person(given = "David", 
            family = "Blodgett", 
            role = c("aut", "cre"), 
            email = "dblodgett@usgs.gov",
-           comment = c(ORCID = "0000-0001-9489-1710"))
+           comment = c(ORCID = "0000-0001-9489-1710")),
+    person(given = "Andrew",
+           family = "Psoras",
+           role = "ctb",
+           email = "apsoras@usgs.gov"))
 Description: 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>.  
-Depends: R (>= 4.0)
+Depends: R (>= 4.1.0)
 Imports: dplyr, data.table, sf, units, stats, methods, utils, pbapply, tidyr, RANN, rlang, fastmap
-Suggests: testthat, nhdplusTools, future, lwgeom, future.apply, knitr, gifski, mapview
+Suggests: testthat, nhdplusTools, future, lwgeom, future.apply, knitr, gifski, mapview, webshot, geos
 License: CC0
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.3
 Config/testthat/parallel: true
 Config/testthat/edition: 3
 VignetteBuilder: knitr
 Language: en-US
-URL: https://github.com/DOI-USGS/hydroloom
+URL: https://github.com/DOI-USGS/hydroloom, https://doi-usgs.github.io/hydroloom/

NAMESPACE

@@ -2,40 +2,88 @@
 
 S3method(accumulate_downstream,data.frame)
 S3method(accumulate_downstream,hy)
+S3method(accumulate_downstream,hy_node)
+S3method(accumulate_downstream,hy_topo)
 S3method(add_divergence,data.frame)
 S3method(add_divergence,hy)
+S3method(add_divergence,hy_node)
+S3method(add_divergence,hy_topo)
 S3method(add_levelpaths,data.frame)
 S3method(add_levelpaths,hy)
+S3method(add_levelpaths,hy_node)
+S3method(add_levelpaths,hy_topo)
+S3method(add_measures,data.frame)
+S3method(add_measures,hy)
 S3method(add_pathlength,data.frame)
 S3method(add_pathlength,hy)
+S3method(add_pathlength,hy_node)
+S3method(add_pathlength,hy_topo)
 S3method(add_pfafstetter,data.frame)
 S3method(add_pfafstetter,hy)
+S3method(add_pfafstetter,hy_leveled)
+S3method(add_pfafstetter,hy_node)
+S3method(add_pfafstetter,hy_topo)
 S3method(add_return_divergence,data.frame)
 S3method(add_return_divergence,hy)
+S3method(add_return_divergence,hy_node)
+S3method(add_return_divergence,hy_topo)
 S3method(add_streamlevel,data.frame)
 S3method(add_streamlevel,hy)
+S3method(add_streamlevel,hy_leveled)
+S3method(add_streamlevel,hy_topo)
 S3method(add_streamorder,data.frame)
 S3method(add_streamorder,hy)
+S3method(add_streamorder,hy_node)
+S3method(add_streamorder,hy_topo)
 S3method(add_toids,data.frame)
 S3method(add_toids,hy)
+S3method(add_toids,hy_node)
+S3method(add_toids,hy_topo)
 S3method(add_topo_sort,data.frame)
 S3method(add_topo_sort,hy)
+S3method(add_topo_sort,hy_node)
+S3method(add_topo_sort,hy_topo)
+S3method(get_bridge_flowlines,data.frame)
+S3method(get_bridge_flowlines,hy)
+S3method(get_bridge_flowlines,hy_node)
+S3method(get_bridge_flowlines,hy_topo)
 S3method(index_points_to_lines,data.frame)
 S3method(index_points_to_lines,hy)
 S3method(make_attribute_topology,data.frame)
 S3method(make_attribute_topology,hy)
 S3method(make_index_ids,data.frame)
 S3method(make_index_ids,hy)
+S3method(make_index_ids,hy_flownetwork)
+S3method(make_index_ids,hy_topo)
 S3method(make_node_topology,data.frame)
 S3method(make_node_topology,hy)
+S3method(make_node_topology,hy_topo)
 S3method(navigate_hydro_network,data.frame)
 S3method(navigate_hydro_network,hy)
+S3method(navigate_hydro_network,hy_leveled)
+S3method(navigate_hydro_network,hy_node)
+S3method(navigate_hydro_network,hy_topo)
+S3method(print,hy_flownetwork)
+S3method(print,hy_node)
+S3method(print,hy_topo)
 S3method(print,hydroloom_names)
 S3method(sort_network,data.frame)
 S3method(sort_network,hy)
+S3method(sort_network,hy_node)
+S3method(sort_network,hy_topo)
+S3method(subset_network,data.frame)
+S3method(subset_network,hy)
+S3method(subset_network,hy_node)
+S3method(subset_network,hy_topo)
+S3method(to_flownetwork,data.frame)
+S3method(to_flownetwork,hy)
+S3method(to_flownetwork,hy_leveled)
+S3method(to_flownetwork,hy_node)
+S3method(to_flownetwork,hy_topo)
 export(accumulate_downstream)
 export(add_divergence)
 export(add_levelpaths)
+export(add_measures)
 export(add_pathlength)
 export(add_pfafstetter)
 export(add_return_divergence)
@@ -48,16 +96,20 @@ export(check_hy_graph)
 export(disambiguate_indexes)
 export(fix_flowdir)
 export(format_index_ids)
+export(get_bridge_flowlines)
 export(get_hydro_location)
 export(get_node)
 export(get_partial_length)
 export(hy)
+export(hy_capabilities)
+export(hy_network_type)
 export(hy_reverse)
 export(hydroloom_name_definitions)
 export(hydroloom_names)
 export(index_points_to_lines)
 export(index_points_to_waterbodies)
 export(is.hy)
+export(is_dendritic)
 export(make_attribute_topology)
 export(make_fromids)
 export(make_index_ids)
@@ -69,11 +121,20 @@ export(rename_geometry)
 export(rescale_measures)
 export(sort_network)
 export(st_compatibalize)
+export(subset_network)
+export(to_flownetwork)
 importFrom(RANN,nn2)
+importFrom(data.table,.N)
+importFrom(data.table,.SD)
 importFrom(data.table,as.data.table)
 importFrom(data.table,copy)
 importFrom(data.table,data.table)
+importFrom(data.table,fcase)
+importFrom(data.table,rbindlist)
+importFrom(data.table,setcolorder)
 importFrom(data.table,setnames)
+importFrom(data.table,setorder)
+importFrom(data.table,setorderv)
 importFrom(dplyr,all_of)
 importFrom(dplyr,any_of)
 importFrom(dplyr,arrange)

NEWS.md

@@ -1,3 +1,81 @@
+hydroloom 1.2.0
+==========
+
+This release introduces an S3 class hierarchy (`hy_topo`, `hy_leveled`,
+`hy_node`, `hy_flownetwork`) that lets hydroloom functions validate input
+at dispatch time and provide guided error messages when the wrong network
+representation is passed. Existing code that passes `data.frame` or `hy`
+objects continues to work without changes -- the new classes are assigned
+automatically and are transparent to downstream consumers. Package
+developers who depend on hydroloom should note that returned objects now
+carry subclass attributes (e.g. `hy_topo`) which are stripped by
+`hy_reverse()` and by standard dplyr operations.
+
+- Improve performance of `add_levelpaths()` by converting to data.table
+- Add S3 class hierarchy: `hy_topo`, `hy_leveled`, `hy_node`, `hy_flownetwork` -- #73
+- `hy()` gains `add_topo` parameter to auto-build toid from fromnode/tonode
+- New exported helpers: `hy_network_type()`, `is_dendritic()`, `hy_capabilities()`
+- Print methods for `hy_topo`, `hy_node`, `hy_flownetwork`
+- Producer functions now stamp output classes: `add_toids()` -> `hy_topo`,
+  `sort_network()` -> `hy_topo`, `add_levelpaths()` -> `hy_leveled`,
+  `make_node_topology()` -> `hy_node`, `to_flownetwork()` -> `hy_flownetwork`
+- `add_divergence()` sets `attr(x, "dendritic") <- FALSE` on output
+- `add_toids(return_dendritic = FALSE)` is deprecated; use `to_flownetwork()`
+- S3 method dispatch: functions now dispatch on subclass (e.g. `.hy_topo`,
+  `.hy_leveled`) with guided error messages for wrong input class
+- Functions that require `hy_leveled` (e.g. `add_pfafstetter()`,
+  `navigate_hydro_network()`, `to_flownetwork()`) fall through from
+  `hy_topo`/`hy_node` when required columns are already present
+- Fix pre-existing bug in `make_to_dt()` where dendritic branch failed on
+  tibble input (data.table `with = FALSE` syntax on plain data.frame)
+- **Deprecation notice:** A future release will require that `hy_topo` objects
+  have unique `id` values (one row per catchment). Non-dendritic connectivity
+  with duplicated ids in a toid-based edge list will need to be represented as
+  `hy_flownetwork` (via `to_flownetwork()`). Developers who currently pass
+  non-dendritic toid tables through hydroloom functions should migrate to
+  `to_flownetwork()` or `make_node_topology()` for non-dendritic workflows.
+
+hydroloom 1.1.3
+==========
+
+Update test tolerances for failing Fedora CRAN tests
+
+hydroloom 1.1.2
+==========
+
+Hydroloom 1.1.2 introduces new functionality in `accumulate_downstream()`, reworks the `make_index_ids()`, 
+and deprecates `make_fromids()` and `format_index_ids()` for clarity of package function. Deprecated functions
+will be removed in the next major version release.
+
+- `subset_network()` has been added to support subsetting networks to include all diversions that emanate from the basin. -- #60
+- `accumulate_downstream()` now supports "total upstream" and "divergence routed" accumulation. -- #17
+- `make_index_ids()` has been rewritten. It now uses four modes ("to", "from", and "both"). 
+- `make_fromids()` is deprecated in favor of `make_index_ids()` with mode = "from".
+- `format_index_ids()` is deprecated. The *_list element of `make_index_ids()` can be unnested instead.
+
+hydroloom 1.1.1
+==========
+
+- fix bug with sort_network when duplicate entries are in the extended attributes -- #52
+- add specific id search to index_points_to_lines for #24
+- error handling #49
+
+hydroloom 1.1.0
+==========
+
+- Add new vignette for network navigation `vignette("network_navigation")`
+- Add support for upmain and downmain navigation in `navigate_network_dfs()`
+- Add support for upmain and downmain in `make_index_ids()` and `make_fromids()`.
+- Add function to create a "flownetwork" representation of the network with a `to_flownetwork` function.
+- Improved handling / fix bugs with edge cases in `add_toids()`
+- Improved error conditions when missing suggested packages.
+- `navigate_hydro_network()` will now navigate from a diverted path to a main path where it previously only followed traditional tributaries..
+
+hydroloom 1.0.1 and 1.0.2
+==========
+
+- Add checks if nhdplusTools is available.
+
 hydroloom 1.0.0
 ==========