In IMMM-SFA/starfit: Storage Target and Release Function Inference Tool

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

starfit

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:

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).

your_path_to_USRDATS <- "../../../../../__collaborations/USRDATS"

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().

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:

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)