Skip to content

Latest commit

 

History

History
201 lines (161 loc) · 7.49 KB

README.md

File metadata and controls

201 lines (161 loc) · 7.49 KB

CRSSIO

Stable version (v0.9.1): R build status Codecov test coverage

Development version: R build status Codecov test coverage

R Package to manipulate the CRSS input and output data.

Installation

Only available from GitHub. Use the following to install:

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.

library(CRSSIO)
flows <- crss_nf(CoRiverNF::monthlyInt["1988/"])
#> nfd: Natural Flow Data
#>  ----------------------
#>  n traces: 1 
#>  dates: Jan 1988 - Dec 2019 
#>  flow space:
#>  - monthly intervening
ism_flows <- ism(flows, n_years_keep = 15)
#> nfd: Natural Flow Data
#>  ----------------------
#>  n traces: 32 
#>  dates: Jan 1988 - Dec 2002 
#>  flow space:
#>  - monthly intervening
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:
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

  • 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