get_drainage_area_estimates: Estimate drainage area from HUC and catchment data

In nhdplusTools: NHDPlus Tools

Estimate drainage area from HUC and catchment data

Description

Combines HUC12 areas upstream of HUC outlets with NHDPlusV2 catchment areas for the portion of the basin between the outlet and HUC12 outlets to produce a drainage area estimate. Non-contributing areas captured in HUC12 boundaries are included.

Usage

get_drainage_area_estimates(
  start,
  catchments = FALSE,
  nhdplushr = TRUE,
  local_navigation = FALSE,
  huc12_data = NULL,
  huc12_outlets = NULL,
  waterbody_data = NULL,
  catchment_data = NULL,
  HU_inclusion_override = NULL,
  outlet_split_threshold_m = 100
)

Arguments

start	list with featureSource and featureID compatible with get_nldi_feature.
catchments	logical. If TRUE, fetch and return NHDPlusV2 catchment polygons for the full upstream network. Default FALSE.
nhdplushr	logical. If TRUE (the default), compute a drainage area estimate from NHDPlusHR catchments. Set to FALSE to skip this step, which avoids the HR web service calls and speeds up computation.
local_navigation	logical. If TRUE, use get_vaa for network navigation and flowline attributes instead of NLDI/OGC API web services. Only HUC12 pour points are fetched from the NLDI. Default FALSE.
huc12_data	sf data.frame or NULL. In-memory HUC12 polygon table to use instead of fetching from web services. Column names are lowercased internally; must include at minimum huc_12 and ncontrb_a (case-insensitive). When provided, all HUC12 polygon queries are resolved by subsetting this table. Default NULL (use web services).
huc12_outlets	sf data.frame, character path, or NULL. HUC12 pour points to use instead of the NLDI huc12pp service. Accepts either a preloaded sf data.frame or a path to a GPKG, which is read with read_sf. Columns COMID and FinalWBD_HUC12 are renamed to comid and identifier; any other columns are preserved. When provided, the outlets are filtered to the upstream network COMID set and no NLDI huc12pp queries are issued. Pair with local_navigation = TRUE and huc12_data to run fully offline. National CONUS outlets GPKGs are available from Blodgett, D.L., 2022, Mainstem Rivers of the Conterminous United States (ver. 3.0, February 2026): U.S. Geological Survey data release, \Sexpr[results=rd]{tools:::Rd_expr_doi("10.5066/P13LNDDQ")} (layer hu_points). Default NULL.
waterbody_data	sf data.frame or NULL. In-memory NHDWaterbody polygon table to use instead of fetching from web services. Column names are lowercased internally; must include comid (case-insensitive). When provided and start is an sfc_POINT, the waterbody containing the point is resolved by spatial filter on this table. Default NULL (use web services).
catchment_data	sf data.frame or NULL. In-memory NHDPlusV2 CatchmentSP polygon table. Column names are lowercased internally; must include featureid (case-insensitive). Used in three ways: (1) when catchments = TRUE, catchment polygons for the upstream network are subsetted from this table instead of fetched from the OGC API; (2) the gap-zone catchment polygons (between the outlet and the immediate HUC12 outlets) are subsetted from this table instead of fetched; (3) when start is an sfc_POINT and no waterbody is found, the COMID is resolved by spatial join on this table. Default NULL (use web services).
HU_inclusion_override	character vector or NULL. Eight- or ten-digit HUC codes whose HUC12s should be kept even when the parent HUC outlet is not in the on-network set. Useful for regions like the Prairie Potholes where landscape-connected HUCs lack a network outlet (e.g. "10130106" in South Dakota). Default NULL (no overrides).
outlet_split_threshold_m	numeric. Minimum distance in meters from the gage to the outlet of its catchment before the catchment is split. When the gage is at least this far upstream, the outlet catchment is split at the gage point and only the upstream portion is included. Default 100.

Details

By default, network navigation is performed via the NLDI web service and flowline attributes are retrieved from the NHDPlusV2 OGC API. When local_navigation = TRUE, the NHDPlusV2 Value Added Attributes (get_vaa) are used for network navigation instead, and only HUC12 pour points are fetched from the NLDI.

HUC drainage area is used upstream of the nearest HUC12 outlet. Between the outlet (e.g. gage) and the HUC outlet(s), catchment areas are used. For large upstream areas the largest HUC level is used to define connectedness, but drainage estimates are derived from HUC12 because that is where the non-contributing area attribute lives.

Three pairs of drainage area estimates are returned: one using only NLDI-identified HUC12s (HUC12-level), one using HUC10-level queries, and one using HUC08-level queries for basins spanning multiple HUC08s. Each pair includes a total and a contributing-only estimate derived from the ncontrb_a (non-contributing acres) attribute on HUC12 features.

Value

list with elements:

da_huc12_sqkm

numeric. Total DA using NLDI-identified HUC12s only.

da_huc10_sqkm

numeric or NA. Total DA using HUC10-level queries. NA when basin is within a single HUC10.

da_huc08_sqkm

numeric or NA. Total DA using HUC08-level queries. NA when basin is within a single HUC08.

contrib_da_huc12_sqkm

numeric. Contributing DA (HUC12-only).

contrib_da_huc10_sqkm

numeric or NA. Contributing DA (HUC10-level).

contrib_da_huc08_sqkm

numeric or NA. Contributing DA (HUC08-level).

network_da_sqkm

numeric. Network-derived total DA for comparison.

nhdplushr_network_dasqkm

numeric or NA. Drainage area from NHDPlusHR catchments upstream of the matched HR flowline. NA with a warning when the HR web service is unavailable or fails.

nhdplushr_boundary

sfc_GEOMETRY or NULL. Dissolved boundary of upstream NHDPlusHR catchments. NULL when the HR estimate is unavailable.

start_feature

sf data.frame. The resolved NLDI start feature.

hu12_by_huc12

sf data.frame. NLDI-identified upstream HUC12 polygons (EPSG:5070).

hu12_by_huc10

sf data.frame or NULL. Upstream HUC12 polygons (HUC10 query). NULL when basin is within a single HUC10.

hu12_by_huc08

sf data.frame or NULL. Upstream HUC12 polygons (HUC08 query). NULL when basin is within a single HUC08.

extra_catchments

sf data.frame. Catchments between outlet and HUC12 outlets.

split_catchment

sf data.frame. Split catchment at HUC12 outlet(s).

all_network

data.frame. Full upstream flowline attributes.

all_catchments

sf data.frame or NULL. NHDPlusV2 catchment polygons for the full upstream network. NULL when catchments = FALSE.

outlet_flowline_measure

numeric or NULL. Flowline measure (0–100) for the gage on its outlet flowline. NULL for non-gage starts.

outlet_split_catchment

sf data.frame or NULL. Split catchment at the gage point. Contains "catchment" and "splitCatchment" rows with areas. NULL when no split is needed (gage at outlet or below threshold).

hu12_outlet

sf data.frame. HUC12 pour points upstream of outlet.

Examples

# Black Earth Creek
start <- list(featureSource = "nwissite", featureID = "USGS-05406500")
result <- get_drainage_area_estimates(start)
result$da_huc10_sqkm
result$network_da_sqkm

nhdplusTools documentation built on May 26, 2026, 5:06 p.m.