---
title: "Water Use models"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Water Use models}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
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

```{r wu-models, eval = FALSE}
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:

```{r wu-vars-irrwd, eval = FALSE}
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
```

```{r wu-vars-thermo, eval = FALSE}
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

```{r wu-irrwd, eval = FALSE}
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

```{r wu-irrcu, eval = FALSE}
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

```{r wu-pswd, eval = FALSE}
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

```{r wu-pscu, eval = FALSE}
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

```{r wu-thermo, eval = FALSE}
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:

```{r wu-state, eval = FALSE}
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:

```{r wu-loop, eval = FALSE}
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"`.

```{r wu-recent, eval = FALSE}
# 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"
)
```