Package {nwaa}

nwaa: USGS NWAA Data Download

Description

Download and parse model outputs from the U.S. Geological Survey (USGS) National Water Availability Assessment (NWAA) Data Companion web services. Provides typed, validated wrappers for the published NWAA models across the Water Use, Water Quantity, and Integrated Water Availability families, returning results at HUC12 spatial resolution.

Author(s)

Maintainer: Laljeet Sangha lsanghah2o@gmail.com

See Also

Useful links:

• https://laljeet.github.io/nwaa/

• https://github.com/laljeet/nwaa

• Report bugs at https://github.com/laljeet/nwaa/issues

Download Atmospheric Forcing model output (WRF CONUS404-BA)

Description

Convenience wrapper for the atmospheric forcing model wqn-conus404-ba. Returns precipitation aggregated to HUC12 polygons.

Usage

nwaa_atmos(
  variable_ids,
  location_type,
  location_id,
  time_res = "monthly",
  range = c("recent", "historical", "custom"),
  start = NULL,
  end = NULL,
  intersection = NULL,
  skip = 0,
  format = "csv",
  quiet = TRUE,
  model_id = "wqn-conus404-ba"
)

Arguments

Details

This wrapper validates variable_ids against the model's catalog entry before sending the request, and validates that time_res is supported by the model.

Value

Parsed data. For format = "csv", a tibble.

See Also

nwaa_catalog, nwaa_water_use, nwaa_hydro, nwaa_iwa

Examples

# Monthly precipitation for one HUC12, calendar year 2020
df <- nwaa_atmos(
  variable_ids = "precip",
  location_type = "huc12",
  location_id = "180300010602",
  time_res = "monthly",
  range = "custom",
  start = "2020-01",
  end = "2020-12",
  format = "csv"
)

# Full historical record for a single HUC12
df_hist <- nwaa_atmos(
  variable_ids = "precip",
  location_type = "huc12",
  location_id = "180300010602",
  range = "historical"
)

NWAA model catalog

Description

Master catalog of all NWAA Data Companion models supported by this package, across all three families:

• wu (Water Use): irrigation, public supply, thermoelectric.

• wqn (Water Quantity): atmospheric forcing, the hydrologic ensemble, and its NHM-PRMS and WRF-Hydro component models.

• iwa (Integrated Water Availability): water budget assessment.

Usage

nwaa_catalog()

Details

Each row describes one model: its identifier, label, family, the variable IDs it produces, the units those variables are reported in (units appear as a suffix on column names in API responses, e.g. irrwdtot_mgd), the start and end of available data, and the temporal resolutions the model is published at.

This catalog is the single source of truth used internally by request validation and date-range resolution.

Value

A tibble with columns:

model_id

API model identifier (string).

model_label

Human-readable model name.

family

One of "wu", "wqn", "iwa".

start_ym, end_ym

Earliest and latest available data, format "YYYY-MM".

temporal

List-column of supported temporal resolutions: combinations of "monthly", "annualcy", "annualwy".

variables

List-column of variable ID character vectors.

variable_name

List-column of human-readable variable names.

units

List-column of unit-suffix character vectors aligned to variables.

Temporal resolutions

All models are published monthly and, in addition, expose calendar-year annual (annualcy) and water-year annual (annualwy) aggregations. For Water Use models the upstream READMEs explicitly describe annual mean derivation from monthly values. For the Water Quantity and Integrated Water Availability models the annual aggregations are computed server-side by the NWAA data endpoint; live probes confirmed every one of these models returns annual (year) output for both annualcy and annualwy. The catalog therefore lists all three resolutions for every model.

Units verification

Unit suffixes for all variables in this catalog have been verified against actual API responses. The hydrologic ensemble model (wqn-ensemble-conus-nwaa-v1) was originally inferred from one README example (actet_mm/mo); a live probe in May 2026 confirmed all six variables match the catalog suffixes. The actual unit suffix is always returned as part of the column name in API responses, so users never need to rely on the catalog for unit information at runtime.

Examples

nwaa_catalog()

# All Water Use models
cat <- nwaa_catalog()
cat[cat$family == "wu", c("model_id", "model_label")]

Fetch NWAA data

Description

Low-level HTTP wrapper. Sends a query to the NWAA Data Companion service and parses the response according to query$format. Most users should use the family wrappers (nwaa_water_use, nwaa_atmos, nwaa_hydro, nwaa_iwa), which validate the request before calling this function.

Usage

nwaa_get_data(query, quiet = TRUE, timeout = 300, max_tries = 3)

Arguments

Value

Parsed response. For format = "csv", a tibble; geographic identifier columns (e.g. huc12_id) are returned as character so that HUC and FIPS codes keep any leading zeros and are never rendered in scientific notation. For format = "json", a list. For format = "geojson", an sf object (requires the sf package).

Network resilience

Each request enforces a generous timeout (default 300 seconds, since large HUC12-resolution aggregations on the USGS server can take minutes), and retries up to two times with exponential backoff for transient errors (HTTP 429, 500, 502, 503, 504). Permanent errors (4xx other than 429) abort immediately with the server's response body included in the message.

User agent

Each request includes a User-Agent header identifying the package and version. This helps USGS attribute traffic to the package for capacity planning and would let them reach out if a future API change requires a coordinated package update.

Download Hydrologic Model Ensemble output (NHM-PRMS and WRF-Hydro)

Description

Convenience wrapper for the hydrologic models in the wqn family. Defaults to the ensemble wqn-ensemble-conus-nwaa-v1, and also serves the two component models via model_id: wqn-nhmprms-conus-nwaa-v1 (NHM-PRMS) and wqn-wrfhydro-conus-nwaa-v1 (WRF-Hydro). Returns hydrologic flux and state variables (evapotranspiration, baseflow, quickflow, snow water equivalent, soil moisture, runoff, recharge) aggregated to HUC12 polygons.

Usage

nwaa_hydro(
  variable_ids,
  location_type,
  location_id,
  time_res = "monthly",
  range = c("recent", "historical", "custom"),
  start = NULL,
  end = NULL,
  intersection = NULL,
  skip = 0,
  format = "csv",
  quiet = TRUE,
  model_id = "wqn-ensemble-conus-nwaa-v1"
)

Arguments

Details

This wrapper validates variable_ids against the model's catalog entry before sending the request, and validates that time_res is supported by the model.

Value

Parsed data. For format = "csv", a tibble.

Available variables

Ensemble (wqn-ensemble-conus-nwaa-v1):

• actet - actual evapotranspiration (mm/mo)

• incbsflow - incremental baseflow (mm/mo)

• incqkflow - incremental quickflow (mm/mo)

• incrunoff - incremental runoff (mm/mo)

• swe - snow water equivalent (mm)

• soilmstfr - soil moisture fraction (unitless)

The component models (wqn-nhmprms-conus-nwaa-v1, wqn-wrfhydro-conus-nwaa-v1) additionally provide:

• soilmst - soil moisture (mm)

• recharge - recharge (mm/mo)

See Also

nwaa_catalog, nwaa_water_use, nwaa_atmos, nwaa_iwa

Examples

# Monthly evapotranspiration for one HUC12 across the full record
df_et <- nwaa_hydro(
  variable_ids = "actet",
  location_type = "huc12",
  location_id = "180300010602",
  range = "historical"
)

# Multiple hydrologic variables for a county
df_county <- nwaa_hydro(
  variable_ids = c("actet", "incrunoff", "swe"),
  location_type = "countycd",
  location_id = "06029",
  time_res = "monthly",
  range = "custom",
  start = "2018-01",
  end = "2020-12",
  intersection = "overlap"
)

# Recharge and soil moisture from the NHM-PRMS component model
# (not available from the ensemble)
df_recharge <- nwaa_hydro(
  model_id = "wqn-nhmprms-conus-nwaa-v1",
  variable_ids = c("recharge", "soilmst"),
  location_type = "huc12",
  location_id = "180300010602",
  time_res = "monthly",
  range = "custom",
  start = "2020-01",
  end = "2020-12"
)

Intersection types for polygon selectors

Description

Used when location_type selects a polygon extent (example: "statecd" or "countycd"). The API returns HUC12s, and intersection controls which HUC12s count as "inside".

Usage

nwaa_intersection_types()

Value

A tibble with intersection codes and meanings.

Examples

nwaa_intersection_types()

Download Integrated Water Availability Assessment outputs

Description

Convenience wrapper for the integrated water availability model iwa-assessment-outputs-conus-2025. Returns water-budget results and the surface water supply and use index (SUI) at HUC12 resolution.

Usage

nwaa_iwa(
  variable_ids,
  location_type,
  location_id,
  time_res = "monthly",
  range = c("recent", "historical", "custom"),
  start = NULL,
  end = NULL,
  intersection = NULL,
  skip = 0,
  format = "csv",
  quiet = TRUE,
  model_id = "iwa-assessment-outputs-conus-2025"
)

Arguments

Details

This wrapper validates variable_ids against the model's catalog entry before sending the request, and validates that time_res is supported by the model.

Value

Parsed data. For format = "csv", a tibble.

Available variables

• sui - surface water supply and use index (fraction)

• availab - total water availability (mm/mo)

• strflow - streamflow (mm/mo)

• consum - total water consumption (mm/mo)

See Also

nwaa_catalog, nwaa_water_use, nwaa_atmos, nwaa_hydro

Examples

# All four IWA variables for one HUC12, full historical record
df <- nwaa_iwa(
  variable_ids = c("sui", "availab", "strflow", "consum"),
  location_type = "huc12",
  location_id = "180300010602",
  range = "historical"
)

# SUI only for an entire county
df_sui <- nwaa_iwa(
  variable_ids = "sui",
  location_type = "countycd",
  location_id = "06029",
  time_res = "monthly",
  range = "custom",
  start = "2018-01",
  end = "2020-09",
  intersection = "overlap"
)

List valid location types used by the NWAA API

Description

Returns the set of location_type values accepted by the API, along with brief usage notes. The API returns HUC12 results for any selector; HUC2 through HUC12 act as polygon containers, and statecd and countycd also act as polygon containers (use the intersection argument to control inclusion).

Usage

nwaa_location_types()

Value

A tibble with columns type and notes.

Examples

nwaa_location_types()

State abbreviations for use with location_type = "statecd"

Description

The NWAA API uses lowercase 2-letter state abbreviations (example: "ca", "al"). This helper returns a lookup between full state names and the lowercase abbreviation expected by the API.

Usage

nwaa_statecd()

Value

A tibble with columns state_name and statecd.

Examples

nwaa_statecd()

Download Water Use model output from the NWAA Data Companion

Description

Convenience wrapper for the Water Use (wu) family of NWAA models. Validates that model_id, variable_ids, and time_res are valid for this family before sending the request. County and state extents act as polygon selectors and return results at HUC12 resolution.

Usage

nwaa_water_use(
  model_id,
  variable_ids,
  location_type,
  location_id,
  time_res = "monthly",
  range = c("recent", "historical", "custom"),
  start = NULL,
  end = NULL,
  intersection = NULL,
  skip = 0,
  format = "csv",
  quiet = TRUE
)

Arguments

Details

Learn options inside the package:

• Models: nwaa_wu_models

• Variables by model: nwaa_wu_variables

• Location types: nwaa_location_types

The USGS NWAA Data Companion "Subset and Download" tool generates valid request URLs interactively and is a useful reference when composing queries.

Value

Parsed data. For format = "csv", a tibble. For format = "json", a list. For format = "geojson", an sf object.

See Also

nwaa_wu_models, nwaa_wu_variables, nwaa_atmos, nwaa_hydro, nwaa_iwa

Examples

# Discover models and variables (offline)
nwaa_wu_models()
nwaa_wu_variables("wu-irrigation-wd")


# County selector, annual water-year, custom range
df <- nwaa_water_use(
  model_id = "wu-irrigation-wd",
  variable_ids = c("irrwdgw", "irrwdsw", "irrwdtot"),
  location_type = "countycd",
  location_id = "06029",
  time_res = "annualwy",
  range = "custom",
  start = "2001",
  end = "2020",
  intersection = "overlap",
  format = "csv",
  quiet = FALSE
)

# HUC12 selector, most recent timepoint
df_recent <- nwaa_water_use(
  model_id = "wu-irrigation-wd",
  variable_ids = "irrwdtot",
  location_type = "huc12",
  location_id = "180300010602",
  time_res = "annualwy",
  range = "recent",
  format = "csv"
)

# Stricter polygon selection
df_envelop <- nwaa_water_use(
  model_id = "wu-irrigation-wd",
  variable_ids = c("irrwdgw", "irrwdsw", "irrwdtot"),
  location_type = "countycd",
  location_id = "06029",
  time_res = "annualwy",
  range = "custom",
  start = "2001",
  end = "2020",
  intersection = "envelop",
  format = "csv"
)

List Water Use models and their available date ranges

Description

Convenience view that returns the Water Use rows of nwaa_catalog restricted to the columns most relevant for picking a model.

Usage

nwaa_wu_models()

Value

A tibble with model_id, model_label, start_ym, and end_ym.

Examples

nwaa_wu_models()

List variables for a Water Use model

Description

Looks up one Water Use model in nwaa_catalog and returns a long-form tibble of its variable IDs, units, and human-readable names.

Usage

nwaa_wu_variables(model_id)

Arguments

Value

A tibble with one row per variable. Columns: model_id, variable_id, unit, variable_name.

Examples

nwaa_wu_variables("wu-irrigation-wd")