Water Use models • nwaa

library(nwaa)

The Water Use family covers five sectoral models, all returned at HUC12 resolution in millions of gallons per day (mgd). The five models cover three sectors (irrigation, public supply, thermoelectric) split between water withdrawals and consumptive use.

The five models

nwaa_wu_models()

#> # A tibble: 5 x 4
#>   model_id            model_label                                  start_ym end_ym 
#>   <chr>               <chr>                                        <chr>    <chr>  
#> 1 wu-irrigation-cu    Crop Irrigation Consumptive Water-Use Model  2000-01  2020-12
#> 2 wu-irrigation-wd    Crop Irrigation Withdrawals Water-Use Model  2000-01  2020-12
#> 3 wu-public-supply-cu Public Supply Consumptive Water-Use Model    2009-01  2020-12
#> 4 wu-public-supply-wd Public Supply Withdrawals Water-Use Model    2000-01  2020-12
#> 5 wu-thermoelectric   Thermoelectric Power Water-Use Model         2008-01  2020-12

For each model, nwaa_wu_variables() returns its variable IDs, units, and human-readable names:

nwaa_wu_variables("wu-irrigation-wd")

#> # A tibble: 3 x 4
#>   model_id         variable_id unit  variable_name                            
#>   <chr>            <chr>       <chr> <chr>                                    
#> 1 wu-irrigation-wd irrwdtot    mgd   Crop irrigation total withdrawals        
#> 2 wu-irrigation-wd irrwdgw     mgd   Crop irrigation groundwater withdrawals  
#> 3 wu-irrigation-wd irrwdsw     mgd   Crop irrigation surface-water withdrawals

nwaa_wu_variables("wu-thermoelectric")

#> # A tibble: 7 x 4
#>   model_id          variable_id unit  variable_name                                       
#>   <chr>             <chr>       <chr> <chr>                                               
#> 1 wu-thermoelectric tecufgw     mgd   Thermoelectric fresh groundwater consumptive use    
#> 2 wu-thermoelectric tecufsw     mgd   Thermoelectric fresh surface-water consumptive use  
#> 3 wu-thermoelectric tecuftot    mgd   Thermoelectric fresh water total consumptive use    
#> 4 wu-thermoelectric tewdfgw     mgd   Thermoelectric fresh groundwater withdrawals        
#> 5 wu-thermoelectric tewdfsw     mgd   Thermoelectric fresh surface-water withdrawals      
#> 6 wu-thermoelectric tewdftot    mgd   Thermoelectric fresh water total withdrawals        
#> 7 wu-thermoelectric tewdssw     mgd   Thermoelectric saline surface-water withdrawals

Common arguments

All five Water Use queries share the same argument structure:

Argument	Purpose
`model_id`	one of the five Water Use model IDs
`variable_ids`	character vector of variables for that model
`location_type`	`"huc2"`, `"huc4"`, `"huc6"`, `"huc8"`, `"huc10"`, `"huc12"`, `"statecd"`, or `"countycd"`
`location_id`	identifier for the chosen `location_type`
`time_res`	`"monthly"`, `"annualwy"` (water year), or `"annualcy"` (calendar year)
`range`	`"recent"`, `"historical"`, or `"custom"`
`start`, `end`	only used with `range = "custom"`
`intersection`	`"overlap"` (default) or `"envelop"`, only meaningful for state and county selectors
`format`	`"csv"` (default), `"json"`, or `"geojson"`

1. Irrigation withdrawals

irrwd <- nwaa_water_use(
  model_id      = "wu-irrigation-wd",
  variable_ids  = c("irrwdtot", "irrwdgw", "irrwdsw"),
  location_type = "huc8",
  location_id   = "18030001",
  time_res      = "annualwy",
  range         = "custom",
  start         = "2018",
  end           = "2020"
)
head(irrwd)

2. Irrigation consumptive use

irrcu <- nwaa_water_use(
  model_id      = "wu-irrigation-cu",
  variable_ids  = "irrcutot",
  location_type = "huc8",
  location_id   = "18030001",
  time_res      = "annualwy",
  range         = "historical"
)
head(irrcu)

3. Public supply withdrawals

pswd <- nwaa_water_use(
  model_id      = "wu-public-supply-wd",
  variable_ids  = c("pswdtot", "pswdgw", "pswdsw"),
  location_type = "countycd",
  location_id   = "06029",
  time_res      = "annualcy",
  range         = "recent"
)
head(pswd)

4. Public supply consumptive use

pscu <- nwaa_water_use(
  model_id      = "wu-public-supply-cu",
  variable_ids  = "pscutot",
  location_type = "countycd",
  location_id   = "06029",
  time_res      = "annualcy",
  range         = "historical"
)
head(pscu)

5. Thermoelectric

thermo <- nwaa_water_use(
  model_id      = "wu-thermoelectric",
  variable_ids  = c("tewdftot", "tecuftot"),
  location_type = "statecd",
  location_id   = "ca",
  time_res      = "annualcy",
  range         = "historical",
  intersection  = "overlap"
)
head(thermo)

Switching geographic scope

The same call works at HUC, state, or county scope. The API aggregates HUC12 outputs to whichever boundary is requested:

state_irrig <- nwaa_water_use(
  model_id      = "wu-irrigation-wd",
  variable_ids  = "irrwdtot",
  location_type = "statecd",
  location_id   = "ca",
  time_res      = "annualcy",
  range         = "historical",
  intersection  = "envelop"  # stricter: only HUC12s ≥98% inside California
)
head(state_irrig)

Looping across counties

A common workflow is pulling the same query across several counties and combining the results. Native vector input on location_id is on the roadmap. Until then, this idiom works:

library(purrr)
library(dplyr)

county_fips <- c("06029", "06031", "06107", "06019")  # Kern, Kings, Tulare, Fresno

irrig_sjv <- map_dfr(county_fips, function(fips) {
  nwaa_water_use(
    model_id      = "wu-irrigation-wd",
    variable_ids  = c("irrwdtot", "irrwdgw", "irrwdsw"),
    location_type = "countycd",
    location_id   = fips,
    time_res      = "annualwy",
    range         = "historical"
  ) |>
    mutate(county_fips = fips)
})

head(irrig_sjv)

Date-range modes

Three values are supported for the range argument:

range = "recent" returns one timepoint, the most recent in the model’s catalog. For Water Use models this is 2020-12 (monthly), 2020 (calendar year), or water year 2020.
range = "historical" returns the full available period. The first complete water year is the year after the catalog start (Water Year labeling: WY 2020 covers Oct 1 2019 to Sep 30 2020).
range = "custom" requires start and end. Monthly takes "YYYY-MM"; annual takes "YYYY".

# Just the most recent calendar year
recent_pswd <- nwaa_water_use(
  model_id      = "wu-public-supply-wd",
  variable_ids  = "pswdtot",
  location_type = "countycd",
  location_id   = "06029",
  time_res      = "annualcy",
  range         = "recent"
)