-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME.Rmd
141 lines (103 loc) · 7.28 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
---
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%"
)
```
# CRSSIO
<!-- badges: start -->
*Stable version (v0.9.1):* [](https://github.com/BoulderCodeHub/CRSSIO/actions)
[](https://codecov.io/gh/BoulderCodeHub/CRSSIO)
*Development version:* [](https://github.com/rabutler-usbr/CRSSIO/actions)
[](https://codecov.io/gh/rabutler-usbr/CRSSIO?branch=master)
<!-- badges: end -->
R Package to manipulate the CRSS input and output data.
## Installation
Only available from GitHub. Use the following to install:
```{r echo = TRUE, eval=FALSE}
install.packages('devtools')
library(devtools)
devtools::install_github('BoulderCodeHub/CRSSIO')
```
## Usage
The CRSSIO package includes functions for manipulating and creating input data necessary to run CRSS and for processing CRSS output data. It uses a "prefix_verb_noun" naming system for most functions. Functions that create input for CRSS use the `crssi_` prefix, while those that process CRSS output use the `crsso_` prefix. The `nf_`, `natsalt_`, and `ism_` prefixes are also used for multiple functions that deal with natural flow names, natural salt names, and with ISM related functions.
Functions that use the `create` verb will create files on the user's computer. Functions that use the `change` verb will edit files that already exist on the user's computer. Functions that use the `get` verb will return data.
The final noun of the function describes what is created or retrieved. Ex: `crssi_create_dnf_files()` creates the DNF (direct natural flow) files.
The package also includes other functions for conveniently manipulating other data related to CRSS, e.g., converting between elevation and storage for modeled reservoirs. Finally, the package provides several functions that extend/modify ggplots.
### Classes
CRSSIO defines three classes for storing multi-trace natural flow data: `nfd`, `crss_nf`, and `crssi`. `crss_nf` inherits from `nfd` and `crssi` inherits from both `nfd` and `crss_nf`. These classes intend to make working with CRSS input natural flow data easier and more uniform.
`nfd` stores multi-trace, multi-site data for annual and/or monthly time steps and for intervening and/or total natural flow (flow space). `nfd()` creates the object from arrays, matrices, or xts objects. The object can contain any/all of the four combinations of time step and flow space.
`crss_nf` objects require that there are exactly 29 sites: the 29 sites required for input into CRSS, and that there are monthly intervening natural flows, which are also required input to CRSS. Other time step and flow space combinations are allowed, but there must be monthly intervening data.
`crssi` objects add additional required input into CRSS: the Sacramento year type index and a scenario number.
Several methods exist to work with these objects. `reindex()` changes the underlying time component so that historical data can be used for future projections in CRSS; `ism()` applies the Index Sequential Method to a single trace; `plot()` will quickly show the data; `write_crssi()` will create the input files necessary for CRSS; `nfd_stats()` and `nfd_pdf()` compute statistics across the different traces and can then be plotted with `plot()`. `nf_to_total()` and `nf_to_intervening()` will convert between total and intervening flow.
#### Example
Apply ISM to the 1988-present period, and then plot the resulting statistics.
```{r statPlot, fig.height=5}
library(CRSSIO)
flows <- crss_nf(CoRiverNF::monthlyInt["1988/"])
ism_flows <- ism(flows, n_years_keep = 15)
hist_stats <- nfd_stats(flows, "Cameo", "intervening", "monthly")
ism_stats <- nfd_stats(ism_flows, "Cameo", "intervening", "monthly")
plot(ism_stats, ref = hist_stats, base_units = "acre-feet")
```
### `crssi_`
* Create CRSS input files with `crssi_create_dnf_files()`, `crssi_create_cmip_nf_files()`, and `crssi_create_hist_nf_xlsx()`
* These files can also be created with a GUI through an R Studio Addin (see `?crss_input_addin`)
* Modify existing CRSS natural flow input files with `crssi_change_nf_start_date()`, `crssi_change_nf_file_names()`, and `crssi_change_evap_files()`
### `crsso_`
* `sys_cond_matrix()` and `crsso_get_sys_cond_table()` help create the standard System Conditions Table from CRSS output. Commonly referred to as the "5-year table" but it can go through as many years as simulation data exists. Ex:
```{r echo=TRUE, warning=FALSE, message=FALSE}
library(CRSSIO)
library(RWDataPlyr) # install.packages("RWDataPlyr")
# create the RiverWare data aggregator
rwa <- sys_cond_rwa()
# use example data in RWDataPlyr to create system condition table
# first get all of the data
scenFolder <- "ISM1988_2014,2007Dems,IG,Most"
scenName <- "scenA"
scenPath <- system.file('extdata','Scenario/',package = 'RWDataPlyr')
sysData <- RWDataPlyr::rdf_aggregate(
rwa,
rdf_dir = file.path(scenPath, scenFolder),
scenario = scenName
)
# then create the system condition table
sysCondTable <- crsso_get_sys_cond_table(sysData, 2018:2022)
# sysCondTable[['limitedTable']] to access results
```
### Natural Flow and Salt Names
* Vectors of the natural flow gage names (`nf_gage_names()`), along with corresponding CRSS natural inflow input slot names (`nf_file_names()`), corresponding CRSS natural salt input slot names (`natsalt_file_names()`), and corresponding abbreviated, i.e., variable, names (`nf_gage_abbrv()`).
### Other CRSS Functions
* `elevation_to_storage()` and `storage_to_elevation()` convert between elevation and storage for reservoirs modeled in CRSS.
* `ism_get_site_matrix()` applies the index sequential method (ISM) to a single time series of data.
## Plotting
* `stat_boxplot_custom()` works with ggplots to add box and whisker plots. It differs from `ggplot2::stat_boxplot()` in that it extends the whiskers to specified percentiles instead of some scaled value of the IQR.
* `add_secondary_y_conversion()` adds a secondary y-axis to a plot. It ensures that the secondary axis is a conversion of the primary axis labels so the ticks match the grid lines from the primary axis.
## Log:
For details, see the [News](NEWS.md)
* 2022-06-01: version 0.9.0 available
* 2021-03-24: version 0.8.2 available
* 2021-03-19: version 0.8.1 available
* 2020-06-12: version 0.8.0 available
* 2020-01-24: version 0.7.4 available
* 2019-07-25: version 0.7.3 available
* 2019-02-07: version 0.7.2 available
* 2019-01-18: version 0.7.1 available
* 2019-01-17: version 0.7.0 available
* 2018-11-29: version 0.6.3 available
* 2018-03-23: version 0.6.2 available
* 2018-01-23: version 0.6.1 available
* 2018-01-17: version 0.6.0 available
* 2017-08-30: version 0.5.0 available
* 2017-05-10: version 0.4.1 available
* 2017-03-31: version 0.4.0 available
* 2016-10-04: version 0.3 available
* 2016-05-30: version 0.2.1 available
* 2016-05-05: version 0.2 available
* 2015-02-10: version 0.1 available