R/get_drainage_area_estimates.R
get_drainage_area_estimates.RdCombines 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.
get_drainage_area_estimates(
start,
catchments = FALSE,
nhdplushr = TRUE,
local_navigation = FALSE,
huc12_data = NULL,
huc12_outlets = NULL,
HU_inclusion_override = NULL,
outlet_split_threshold_m = 100
)list with featureSource and featureID compatible
with get_nldi_feature.
logical. If TRUE, fetch and return NHDPlusV2 catchment polygons for the full upstream network. Default FALSE.
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.
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.
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).
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,
doi:10.5066/P13LNDDQ
(layer hu_points). Default NULL.
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).
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.
list with elements:
numeric. Total DA using NLDI-identified HUC12s only.
numeric or NA. Total DA using HUC10-level queries. NA when basin is within a single HUC10.
numeric or NA. Total DA using HUC08-level queries. NA when basin is within a single HUC08.
numeric. Contributing DA (HUC12-only).
numeric or NA. Contributing DA (HUC10-level).
numeric or NA. Contributing DA (HUC08-level).
numeric. Network-derived total DA for comparison.
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.
sfc_GEOMETRY or NULL. Dissolved boundary of upstream NHDPlusHR catchments. NULL when the HR estimate is unavailable.
sf data.frame. The resolved NLDI start feature.
sf data.frame. NLDI-identified upstream HUC12 polygons (EPSG:5070).
sf data.frame or NULL. Upstream HUC12 polygons (HUC10 query). NULL when basin is within a single HUC10.
sf data.frame or NULL. Upstream HUC12 polygons (HUC08 query). NULL when basin is within a single HUC08.
sf data.frame. Catchments between outlet and HUC12 outlets.
sf data.frame. Split catchment at HUC12 outlet(s).
data.frame. Full upstream flowline attributes.
sf data.frame or NULL. NHDPlusV2 catchment polygons
for the full upstream network. NULL when catchments = FALSE.
numeric or NULL. Flowline measure (0–100) for the gage on its outlet flowline. NULL for non-gage starts.
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).
sf data.frame. HUC12 pour points upstream of outlet.
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.
# \donttest{
# Black Earth Creek
start <- list(featureSource = "nwissite", featureID = "USGS-05406500")
result <- get_drainage_area_estimates(start)
#> Resolving start feature via NLDI...
#> Outlet catchment flowline measure: 8.19
#> Distance to outlet: 110 m (threshold 100 m => split needed)
#> Finding HUC12 pour points upstream via NLDI...
#> Fetching flowline attributes for 70 upstream COMIDs...
#> 70 flowlines, totdasqkm = 114.34
#> Found 1 HUC12 outlets
#> Finding immediately-upstream HUC12 outlets...
#> 1 immediately-upstream HUC12 outlets (of 1 total)
#> Inferred type 'huc12_nhdplusv2' from ID length and version suffix
#> HUC12 query: 1 HUC12s, total = 65.66 sq km, contributing = 65.66 sq km
#> Splitting catchments at 1 HUC12 outlet(s)...
#> Navigating network upstream of HUC12 outlets...
#> 31 extra catchments between outlet and HUC12 outlets
#> Splitting outlet catchment at gage point...
#> Outlet split: full=1.07 km2, upstream=1.05 km2, removed=0.01 km2
#> Fetching extra catchment geometries...
#> HUC12 DA = 118.03, contributing = 118.03
#> Network DA = 114.34
#> Computing NHDPlusHR drainage area estimate...
#> Fetching NHDPlusHR network for full AOI...
#> Fetched 294 HR flowlines
#> defaulting to comid rather than permanent_identifier
#> HR outlet NHDPlusID = 22001100015000 (TotDASqKM = 107.07950025)
#> Navigating upstream on HR network...
#> defaulting to comid rather than permanent_identifier
#> Found 139 HR flowlines upstream
#> Fetching NHDPlusHR catchments...
#> NHDPlusHR DA = 107.08
result$da_huc10_sqkm
#> [1] NA
result$network_da_sqkm
#> [1] 114.3378
# }