README.Rmd

---
output: github_document
---

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

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

# starfit <img src='man/figures/logo.png' align="right" height="101.5" />

<!-- badges: start -->
[![Travis build status](https://travis-ci.com/IMMM-SFA/starfit.svg?branch=master)](https://travis-ci.com/IMMM-SFA/starfit)
<!-- badges: end -->

`starfit` is a package that is designed to work with reservoir time series data in [USRDATS]() to infer operating storage targets and release functions.

## Installation

Install `starfit` using `devtools`:

``` r
devtools::install_github("IMMM-SFA/starfit")
```

#### Example - fit storage targets for Garrison Dam, North Dakota.

This example assumes that you have downloaded [USRDATS](). First, we'll use the `fit_targets()` function to infer parameters of weekly storage targets for this dam (which is GRanD ID 753).

```{r, echo = FALSE, show = FALSE}
your_path_to_USRDATS <- "../../../../../__collaborations/USRDATS"
```


```{r}
library(starfit)
fit_targets(your_path_to_USRDATS, dam_id = 753) -> fitted_targets

# take a look at the output:
str(fitted_targets)
```

Here we can see that the `fit_targets()` function has generated a list object with four items: (1) the GRanD ID of the reservoir, (2) a table of weekly, observed storage (given as % of storage capacity), (3) flood target parameters, and (4) conservation target parameters. Fitted parameters for (3) and (4) can be converted to storage targets using `convert_parameters_to_storage_targets()`.


```{r}
fitted_targets[["NSR upper bound"]] %>% 
  convert_parameters_to_targets("flood") -> flood_targets

fitted_targets[["NSR lower bound"]] %>% 
  convert_parameters_to_targets("conservation") -> conservation_targets
```


Then we can combine these targets with the weekly storage data to view the inferred rule curves and verify the fit:

```{r}
library(dplyr)
library(ggplot2)

fitted_targets[["weekly storage"]] %>% 
  left_join(flood_targets, by = "epiweek") %>% 
  left_join(conservation_targets, by = "epiweek") %>% 
  mutate(capacity = 100) %>%
  mutate(hydweek = factor(epiweek, levels = c(40:52, 1:39))) %>%
  ggplot(aes(epiweek, s_pct, group = year)) +
  geom_ribbon(aes(ymin = flood, ymax = capacity),
              fill = "darkgrey", alpha = 0.7, col = "black", linetype = 2) +
  geom_ribbon(aes(ymin = conservation, ymax = flood),
              fill = "dodgerblue", alpha = 0.7, col = "black", linetype = 1) +
  geom_ribbon(aes(ymin = 0, ymax = conservation),
              fill = "lightgrey", col = "black", linetype = 1, alpha = 0.7) +
  geom_point(alpha = 0.3) +
  scale_x_discrete(expand = c(0, 0)) +
  scale_y_continuous(expand = c(0, 0)) +
  theme_classic() +
  theme(axis.text.x = element_blank(),
        axis.ticks.x = element_blank()) +
  labs(title = "Garrison Dam, North Dakota", subtitle = "Storage (% of capacity)",
       y = NULL, x = "Hydrological Year (Oct -> Sep)") +
  annotate("text", label = "FLOOD POOL", x = 7, y = 90) +
  annotate("text", label = "CONSERVATION POOL", x = 26, y = 20)

```