README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  dev = "ragg_png",
  fig.path = "man/figures/README-",
  fig.width = 6,
  dpi = 200,
  out.width = "100%"
)

extrafont::loadfonts(device = "win", quiet = TRUE)
```
# wd4tx

<!-- badges: start -->
[![lifecycle](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
[![R-CMD-check](https://github.com/TxWRI/wd4tx/actions/workflows/check-standard.yaml/badge.svg)](https://github.com/TxWRI/wd4tx/actions/workflows/check-standard.yaml)
[![license](https://img.shields.io/badge/license-MIT + file LICENSE-lightgrey.svg)](https://choosealicense.com/)
<!-- badges: end -->

`wd4tx` is an R interface for downloading data from the Texas Water Development Board's (TWDB) Water Data For Texas data portal (https://www.waterdatafortexas.org). Core functions include:

- `download_reservoir()`: Absolute and relative water supply reservoir storage (for individual reservoirs and aggregated by planning area, municipality, river basin, and climate region)
- `download_well()`: Groundwater well levels
- `download_lep()`: Precipitation and evaporation by quad
-  `download_coastal_site_data()`: TWDB coastal water quality (primarily salinity and dissolved oxygen) data
- `download_coastal_hydrology()`: TWDB freshwater inflow estimates for bays and estuaries

This package is not affiliated with the TWDB. Any questions or issues should be directed to: https://github.com/TxWRI/wd4tx/issues

# Installation

`wd4tx` is not on CRAN. In order to install, use `devtools`.

```{r install, eval=FALSE, include=TRUE}
install.packages("devtools")
devtools::install_github("TxWRI/wd4tx")
```


# Usage

## Download Reservoir Storage Data

TWDB provides data for the percent storage, reservoir storage (acre-feet), conservation storage (acre-feet), and conservation capacity (acre-feet) for the water supply (and some flood control) reservoirs used by the state of Texas. The data is available for individual reservoirs, or aggregated by state planning area, river basin, municipal supply, and climate regions. See https://www.waterdatafortexas.org/reservoirs/statewide for more details.


### Download individual reservoir storage data

```{r example1, echo=TRUE, message=FALSE, warning=FALSE, paged.print=FALSE}
library(wd4tx)
library(tidyverse)

df <- download_reservoir(reservoir = "limestone")
df <- df %>%
  mutate(date = as.Date(date),
         water_level = as.numeric(water_level),
         surface_area = as.numeric(surface_area))

ggplot(df) +
  geom_area(aes(date, percent_full), 
            fill = "dodgerblue",
            alpha = 0.50) +
  labs(y = "Percent Full", x = "Date",
       title = "Lake Limestone",
       subtitle = "Ratio of conservation storage to conservation capacity over time") +
  theme_minimal(base_family = "Source Sans Pro",
                base_size = 9)
```

### Download reservoir storage data aggregated by municipality

```{r example2, echo=TRUE, message=FALSE, warning=FALSE, paged.print=FALSE}

df <- download_reservoir(aggregate_by = "municipal",
                         region_name = "houston")
df <- df %>%
  mutate(date = as.Date(date))

ggplot(df) +
  geom_area(aes(date, percent_full), 
            fill = "dodgerblue",
            alpha = 0.50) +
  labs(y = "Percent Full", x = "Date",
       title = "Houston Reservoir Supply",
       subtitle = "Ratio of conservation storage to conservation capacity over time") +
  theme_minimal(base_family = "Source Sans Pro",
                base_size = 9)
```

## Download Individual Well Data

TWDB provides water level measurements from a statewide network of well level recorders. To download the information, all that is needed is the state well number. This information can be accessed with the `download_well_meta()` function. This will provide a `sf` dataframe:

```{r example3, echo=TRUE, message=FALSE, warning=FALSE, paged.print=FALSE}
df <- download_well_meta()

df

```

```{r example4, echo=TRUE, message=FALSE, warning=FALSE, paged.print=FALSE}
ggplot(df) +
  geom_sf(aes(color = status, fill = status), alpha = 0.5) +
  theme_void(base_family = "Source Sans Pro",
             base_size = 9)
```

```{r example5, echo=TRUE, message=FALSE, warning=FALSE, paged.print=FALSE}
df <- download_well("6507905")

df <- df %>%
  mutate(datetime = as.POSIXct(datetime))

ggplot(df) +
  geom_line(aes(datetime, `water_level(ft below land surface)`)) +
  scale_y_reverse() +
  labs(y = "Water Level (ft below surface)",
       x = "Date") +
  theme_minimal(base_family = "Source Sans Pro",
                base_size = 9)
```


## Download Evaporation and Precipitation Data

```{r example6, echo=TRUE, message=FALSE, warning=FALSE, paged.print=FALSE}
df <- download_lep(quad = "710", 
                   start_date = "2010-01",
                   end_date = "2018-12")
df <- df %>%
  pivot_longer(cols = -period,
               names_to = "label",
               values_to = "inches") %>%
  mutate(period = lubridate::ymd(period, truncated = 2))

ggplot(df) +
  geom_line(aes(period, inches, color = label, linetype = label)) +
  theme_minimal(base_family = "Source Sans Pro",
                base_size = 9) +
  theme(legend.position = "bottom",
        legend.direction = "horizontal",
        legend.title = element_blank())
```

## Download Coastal Freshwater Inflow Data

Estimated freshwater inflows and inflow balances for Texas estuaries are provided to support environmental and water planning studies. Details are here: https://www.waterdatafortexas.org/coastal/hydrology

A `geoid` argument is required to identify the watershed data is requested for. Use `download_coastal_geometry()` to download `sf` files which include the name, location, and id.
```{r example7, echo=TRUE, message=FALSE, warning=FALSE, paged.print=FALSE}
df <- download_coastal_geometry(type = "watershed")
df
```

Valid type arguments include `c(basin", "bay", "estuary", "sub_watershed", "watershed")`. Some types return simple features with topological errors. An example of one way to deal with this is shown below:

```{r example8, echo=TRUE, message=FALSE, warning=FALSE, paged.print=FALSE}
library(sf)
df <- df %>%
  st_transform(crs = 3081) %>%
  st_simplify()

ggplot(df) +
  geom_sf() +
  geom_sf_text(aes(label = id), size = 3) +
  theme_void(base_size = 9)
```

With a valid id number, `download_coastal_hydrology()` can be used to download freshwater inflow data for the specified feature.
```{r example9, echo=TRUE, message=FALSE, warning=FALSE, paged.print=FALSE}
df <- download_coastal_hydrology(geoid = "689")
df <- df %>%
  mutate(date = as.Date(date))

ggplot(df) +
  geom_line(aes(date, fresh_in)) +
    theme_minimal(base_family = "Source Sans Pro",
                base_size = 9) +
  labs(x = "Date", y = "Volume (acre-ft)") +
  theme(legend.position = "bottom",
        legend.direction = "horizontal",
        legend.title = element_blank())
```

## Download Coastal Water Quality Data

A list of sites is available with the `download_coastal_sites()` function:
```{r example10, echo=TRUE, message=FALSE, warning=FALSE, paged.print=FALSE}
df <- download_coastal_sites(all_stations = TRUE)
df
```

A list of parameters measured at that station are available using `download_coastal_site_parameters()`:

```{r example11, echo=TRUE, message=FALSE, warning=FALSE, paged.print=FALSE}
df <- download_coastal_site_parameters("SAB2")
df %>% select(units_name, code, name)
```

```{r example12, echo=TRUE, message=FALSE, warning=FALSE, paged.print=FALSE}
df <- download_coastal_site_data(station = "SAB2",
                                 parameter = "seawater_salinity",
                                 start_date = "2010-01-01",
                                 end_date = "2018-01-01",
                                 bin = "hour")
df %>%
  mutate(datetime_utc = as.POSIXct(datetime_utc))
```