Review for new official release.

[dblodgett-usgs]

The original "official" nhdplusTools release was made back in 2022 around version v0.3. A lot has happened since then.

The package grew significantly and hydroloom split off at v1.0.0 -- in recent releases, a lot of work has gone into migration to api.water.usgs.gov, using services for 3DHP and geoconnex.us, and building out utilities to support US-specific datasets and processes.

This issue will be used to capture colleague review in prep for the v2.0.0 release which will prompt a rename of nhdplusTools to hydrogeofetch.

[lkoenig-usgs]

Review of hydrogeofetch v2.0.0

Documentation

As part of my review, I checked that hydrogeofetch includes the following forms of documentation:

• A statement of need: clearly stating problems the software is designed to solve and its target audience in README
• Installation instructions: for the development version of package and any non-standard dependencies in README
• Vignette(s): demonstrating major functionality that runs successfully locally
• Function Documentation: for all exported functions
• Examples: (that run successfully locally) for all exported functions

Functionality

As part of my review, I confirmed the following aspects of package functionality:

• Installation: Installation succeeds as documented.
• Functionality: Any functional claims of the software have been confirmed.
• Performance: Any performance claims of the software have been confirmed.
• Automated tests: Unit tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine.

---

Review Comments

Installation and README

The first thing I did was install the package tarball (from the pre-release materials) on my local machine. I reviewed the README, which clearly states the purpose of hydrogeofetch, its evolution from the existing nhdplusTools packge, and how it fits in with a companion package (hydroloom).

My only comment here is that the document overview justifies the package rename because the scope has grown beyond a single dataset (NHDPlus), yet the text in the Package Vision statement is still very focused on NHDPlus, at least to my reading. In addition, the Data Model section reads "Given that hydrogeofetch is focused on working with NHDPlus data". Maybe this is OK, since NHDPlus functionality still makes up a large portion of the package. But perhaps there is also an opportunity to include minor edits to signal this newly expanded scope for users or contributors, e.g., "The package aims to provide a set of tools that can be used to build workflows using hydrographic data." I'm not fully aware of the expanded vision for the package, so I leave any edits to your discretion.

Two minor notes:

1. The "Getting Started" link in the Resources sub-section of the README did not work for me when I tried it. Can you confirm that the link points to the correct url (maybe this one? https://doi-usgs.github.io/nhdplusTools/articles/hydrogeofetch.html)
2. The README (and the DESCRIPTION file) still include references to the nhdplusTools package, including in the Installation sub-section and the Build and release section. Is that intentional, or should these code and text lines be updated for this release?

Technical review

I then attempted to use the installed package bundle (rather than the source code directory) to run through the examples, and inspected the source code, with a focus on more recent software changes.

Many functions have been moved to a companion package (hydroloom), and new functionality has been added to interface with the 3DHP and mainstems datasets. The added code makes efficient use of web services, and the documentation does a good job informing users of any potential limitations of these services.

Tests are comprehensive and cover the range of package functionality. With the exception of one issue with the example in get_split_catchment() (noted below), all tests passed on my local computer as part of the devtools::check().

All in all, the release looks good and provides valuable utility for users of hydrographic data. I have included some additional, minor comments about the specific aspects of my review below.

Examples

As part of my review, I ran through all of the examples to confirm that any output matches what I would expect based on the documentation.

I noticed just a couple issues, most of which I chalked up to bad timing with server-side errors associated with web service(s), because I could successfully rerun the example after trying again.

1. In get_catchment_characteristics(), I see warnings related to discarded metadata objects that may result from a data.table --> parquet --> read parquet sequence. I don't consider these a problem, as the user can set the recommended option config to suppress them, but if you think it's worth a comment (or even an edit to the function), feel free to add one.

library(hydrogeofetch)
get_catchment_characteristics("CAT_BFI", c(5329343, 5329427))
#> Warning: Potentially unsafe or invalid elements have been discarded from R metadata.
#> ℹ Type: "externalptr"
#> → If you trust the source, you can set `options(arrow.unsafe_metadata = TRUE)` to preserve them.
#> Potentially unsafe or invalid elements have been discarded from R metadata.
#> ℹ Type: "externalptr"
#> → If you trust the source, you can set `options(arrow.unsafe_metadata = TRUE)` to preserve them.
#> Potentially unsafe or invalid elements have been discarded from R metadata.
#> ℹ Type: "externalptr"
#> → If you trust the source, you can set `options(arrow.unsafe_metadata = TRUE)` to preserve them.
#>   characteristic_id   comid characteristic_value percent_nodata
#> 1           CAT_BFI 5329343                27.76              0
#> 2           CAT_BFI 5329427                24.49              0

^{Created on 2026-07-14 with reprex v2.1.0}

2. The example code for get_nldi_basin() runs, but it did not produce a plot as I expected. I suspect this is because the site, basin, and basin2 objects are not transformed, and so they would plot outside of the plotting window defined by the base plot (where the buffer uses a projected crs). Either transforming these objects to match the buffer crs or just keeping the buffer in the geographic crs used by the other objects should fix this issue.

3. In get_split_catchment(), I'm not sure why the second plotting component of the example doesn't run on my machine. This example also threw an error when running devtools::check() on my local machine. Any ideas?

library(hydrogeofetch)

point <- sf::st_sfc(sf::st_point(x = c(-89.2158, 42.9561)), crs = 4326)
trace <- get_raindrop_trace(point)

if(inherits(trace, "sf")) {
  
  (snap_point <- sf::st_sfc(sf::st_point(trace$intersection_point[[1]]),
                            crs = 4326))
  (catchment <- get_split_catchment(snap_point))
  
  (catchment <- get_split_catchment(snap_point, upstream = FALSE))
  
  if(inherits(catchment, "sf")) {
    bbox <- sf::st_bbox(catchment) + c(-0.005, -0.005, 0.005, 0.005)
    hydrogeofetch::plot_nhdplus(bbox = bbox, cache_data = FALSE)
  }
}
#> Error in UseMethod("st_transform") : 
#>   no applicable method for 'st_transform' applied to an object of class "NULL"

4. In get_xs_point, I haven't been able to run the example locally. Can you confirm that the request looks valid?

library(hydrogeofetch)

point <- sf::st_sfc(sf::st_point(x = c(-105.97218, 36.17592)), crs = 4326)

(xs <- get_xs_point(point, 300, 100))
#> Warning: Failed to get features from
#> https://api.water.usgs.gov/nldi/pygeoapi/processes/nldi-xsatpoint/execution:
#> HTTP 400 Bad Request.
#> NULL

^{Created on 2026-07-14 with reprex v2.1.0}

5. In get_3dhp(), the example to query by reachcode/universalreferenceid returns NULL. Is that expected?

library(hydrogeofetch)

AOI <- sf::st_as_sfc(sf::st_bbox(c(xmin = -89.56684, ymin = 42.99816,
                                   xmax = -89.24681, ymax = 43.17192),
                                 crs = "+proj=longlat +datum=WGS84 +no_defs"))

hydrolocation <- get_3dhp(AOI = AOI, type = "hydrolocation")

get_3dhp(universalreferenceid = unique(hydrolocation$universalreferenceid),
         type = "hydrolocation")
#> NULL

^{Created on 2026-07-14 with reprex v2.1.0}

Function documentation

I read through the documentation for 55 functions, checking for completeness. A couple questions:

In the documentation for the download_rf1() function, the example actually calls a different function. Should this be updated to download_rf1("./data/rf1/")?

In prepare_nhdplus(), the value text describes a refactor_flowlines function that doesn't appear to be an exported function in hydrogeofetch. I also don’t see that name referenced elsewhere in the documentation. Is that function still included in the package, or should the reference be removed here?

Minor comments/suggestions that you could consider as useful:

1. In get_geoconnex_reference() it may be helpful to clarify the type argument description. Specifically, that type should align with one of the id entries from discover_geoconnex_reference() (the output of that function also contains an attribute called 'type', but I don't think those entries would be valid here).
2. In get_nldi_index(), minor edit to the description to fix a typo: “uses the Network Linked Data Index to retrieve an estimated …”
3. In get_nwis(), minor suggested edit to the ‘buffer’ argument to fix a typo: “…results are arranged by distance…”
4. In get_split_catchment(), minor suggested edit to the details section to fix a typo: “This service works within the conterminous US NHDPlusV2 domain…”
5. In plot_nhdplus() minor suggested edit to the actually_plot and the overwrite arguments to fix two small typos: (1) “…the plot? Used to get data subset only.” (2) “passed on to subset_nhdplus."
6. In plot_nhdplus(), plot_config details for network_wtbd and off_networkd_wtbd options are not formatted/being rendered as preformatted code, as with the basin, flowline, and outlets options.
7. In prepare_nhdplus(), minor suggested edit to fix a typo in the warn argument: “…controls whether warning and status messages…”
8. In get_xs_point(), minor suggested edit to the Description to fix a typo: “…is determined based on direction of the flowline found…” In addition, the “point” argument may have an extra 'crs' at the end of the argument description.
9. In get_elev_along_path(), minor suggested edit to the 'res' argument to fix a typo: "Must be one of: 1,..."

Vignettes

The package includes one vignette (U.S. Data and Package Basics) that I built locally and ran to confirm the output. I also reviewed six additional articles included in the pkgdown site, although I did not build those locally. The vignettes look good - they cover the main functional aspects of the package and provide helpful examples for users wishing to apply hydrogeofetch functionality to their own workflows. With this release, the new "Migrating from nhdplusTools" vignette is especially helpful for users wishing to understand the latest changes; update older workflows; or become more familiar with the scope and functionality in hydrogeofetch + hydroloom.

My only comment about the vignette (U.S. Data and Package Basics) relates to user reproducibility. I like how some of the other articles - including the NHDHR article - provide various setup variables so that a user can easily step through each line of code and understand the output. That's made a little trickier when variables (e.g., work_dir) are only included in setup chunks within the vignette Rmd file. As an example, the NHD HiRes section suggests that a sample of HR data is loaded with hydrogeofetch, but how the vignette code is accessing it isn't clear without referencing the .Rmd file. If you're open to it, I think defining work_dir (or any other variables needed to run the code in this section) within a visible code block would make it easier for users to understand the NHD HiRes example.

Minor comments/suggestions in case they're useful:

1. In U.S. Data and Package Basics vignette, minor suggested edit to fix a typo: "Or fetch an NWIS an site as the starting point and generate a plot. Data is returned and/or stored in a local file for later use." Similar comment for "...regional to national scales, skip down to the Local Data..." as well as "...(NLDI) and the Water Mission Area pygeoapi..."
2. The NHDHR article has a couple places (Basic Functionality; HR modification) where enumerated lists are all marked with "1" - this isn't an issue for readability, as it's easy for the reader to infer the list in both cases, but I note it here in case a quick fix would result in the intended formatting.
3. Interestingly, in the 3DHP vignette, I had to search for a flowline 11 meters from the point in order to return output other than NULL.

[dblodgett-usgs]

Thank you for your review @lkoenig-usgs -- I really appreciate it!

I will clean up the slightly stale documentation related to nhdplus. I still donsider the "nhdplus data model" to be what this package generally supports, but increasingly it's the "hydrofabric data model" -- but they are slowly merging into one in my brain.

On your examples list:

• 1 is a known issue with that source data that I'm working to fix. I can't fix it here. I'll see above suppressing that warning though, it's benign.
• 2, I'll fix up.
• 3, I'll have to chaise down ... NULL there indicates a web service call failed or something.
• 4, getxspoints is one of the less reliable services in the mix here, I'll verify and improve error handling.
• 5, no. But I know why it's failing and will fix.

Documentation:

• yes. Will fix the download_rf1 oversite.
• I meant to remove prepare_nhdplus -- that function is a relic of a bygone erra in this package's history.
• Will apply all your minor suggestions. Thank you for the editorial help!
• the work_dir being withheld was mainly to keep the vignette more prose and less code -- but I agree that it should be code first. Will update and try to streamline the code setup so it doesn't dominate the introduction of the vignette.
• Will clean up the minor comments on vignettes.