This short document is intended to get you started with using
RavenR to aid your analysis with the Raven Hydrologic Modelling Framework. This tutorial will get you up and running with the
RavenR package and comfortable running a few commands. Some knowledge or R is presumed in this document. If you are not comfortable with R, take a look at any number of R training and Introductory resources, such as the tRaining repository) on Github.
This exercise will use the Nith River modelled output available from within the RavenR package, thus the functions to read in data from csv files are not required. However, it is recommended that you download the Nith river model files, and try to both run the model and read in the output files. The Nith river model can be downloaded from the Raven Tutorial #2.
Note that the
RavenR package is focused on handling Raven input/output files, model diagnostics, and generating plots with the
ggplot2 library. The dependencies required by the package are kept at a relative minimum to preserve stability. An additional package,
RavenR.extras, is available on Github and contains additional functionality.
If you don’t have RavenR yet installed in your R library, run the following commands to install the RavenR package directly from the Comprehensive R Archive Network (CRAN), which is available on CRAN.
For those interested in the latest versions of RavenR or in contributing to the development of RavenR, the package may be found on Github at https://github.com/rchlumsk/RavenR. Packages on Github may also be installed from within R using the
devtools library with the code below.
# install.packages("devtools") library(devtools) devtools::install_github("rchlumsk/RavenR")
Load the RavenR library from the console and view its contents with the following commands:
library(RavenR) # view first 20 functions in RavenR ls("package:RavenR") %>% head(., 20)
Each function in the package is documented, which includes a description of the function, its inputs and outputs, and an example. You can look at any of the function examples by typing out the name of the function beginning with a question mark, which will show the help information at the right of the RStudio environment.
The name of each external function in the RavenR package begins with the “rvn_” prefix, so you in practice ‘search’ for functions by beginning to type them out. Try this to see what functions are available with “rvn_rvh_”.
The RavenR package contains a number of sample data files, which are useful for training purposes and testing of functions. The package contains sample data both in R format (under RavenR/data) and as raw data files in their native formats (RavenR/inst/extdata). The sample data set from the RavenR package (in R format) can be loaded in using the data function (with either quotes or just the name of the data), e.g.,
data("rvn_forcing_data") # ?rvn_forcing_data plot(rvn_forcing_data$forcings$temp_daily_ave, main="Daily Avg. Temperature")
Notice as well that the sample data set in R format also has a built in help file to describe the data.
To locate the raw data from the RavenR package, we will use a syntax to find the data by file name in the RavenR package directory, which ends up looking more similar to a raw file call. This raw data file comes from the inst/extdata folder in the RavenR package. Note that this is done so that the sample data in raw format can be used and tested with functions, and the syntax to locate the data file is more portable across various computer operating systems.
# read in hydrograph sample csv data from RavenR package ff <- system.file("extdata","run1_Hydrographs.csv", package = "RavenR") # ff is a simple string, which can be substituted with any file location ff
##  "C:/Users/rober/AppData/Local/Temp/RtmpYN2xv5/Rinst33f4514d4a16/RavenR/extdata/run1_Hydrographs.csv"
# read in sample rvi file from the RavenR package rvi_file <- system.file("extdata", "Nith.rvi", package = "RavenR") # show first 6 lines of the file readLines(rvi_file) %>% head()
##  "# ----------------------------------------------" ##  "# Raven Input file" ##  "# HBV-EC Nith River emulation test case" ##  "# ----------------------------------------------" ##  "# --Simulation Details -------------------------" ##  ":StartDate 2002-10-01 00:00:00"
system.file command will simply build a file path for where this data file is located on your machine with the RavenR package installation, which can then be passed to any function as required to provide a file location. This command will be used throughout this tutorial in place of local files for portability, however, your own data files may be swapped in place of the system.file locations. For example, you may wish to pass files from other Raven Tutorial files by changing the file paths throughout this tutorial.
Now you are ready to start using RavenR to directly visualize and manipulate model output. This section of the exercise will make use of raw sample data in the RavenR package to illustrate some of the diagnostics and plotting capabilities of RavenR.
Start by finding the raw run1_ForcingFunctions.csv file with the
system.file command. Note that this can be replaced with your own forcing functions file location if preferred. We will store the forcing functions data into an object called ff (and obtain just the subobject using the ‘$’ operator), and then view the first few rows using the head function. We will show only the first six columns of the data for brevity.
ff <- system.file("extdata","run1_ForcingFunctions.csv", package = "RavenR") # ff <- "C:/TEMP/Nith/output/ForcingFunctions.csv" # replace with your own file ff_data <- RavenR::rvn_forcings_read(ff) head(ff_data$forcings[,1:6])
## Warning: timezone of object (UTC) is different than current timezone ().
## day_angle rain snow temp temp_daily_min temp_daily_max ## 2002-10-01 4.70809 3.468690 0 22.5956 17.92510 27.2662 ## 2002-10-02 4.70809 3.468690 0 22.5956 17.92510 27.2662 ## 2002-10-03 4.72530 1.189180 0 19.2076 15.40780 23.0075 ## 2002-10-04 4.74251 2.083260 0 13.3714 11.49870 15.2440 ## 2002-10-05 4.75973 6.474310 0 19.0304 12.50970 25.5510 ## 2002-10-06 4.77694 0.125591 0 11.0186 7.43466 14.6024
Now we can plot the forcing data using the rvn_forcings_plot function. This creates an output of the five main forcings from the data set, from which we can plot one or more forcings, including a plot of the whole set of plots. This is typically a reasonable reality check on the model forcings.
Here, we plot the PET from the set of created plots.
myplots <- rvn_forcings_plot(ff_data$forcings) # myplots$Temperature # myplots$Radiation # myplots$AllForcings myplots$PET
The legend for the forcing plot functions is turned off by default, but can be added back in using the
theme function from
ggplot2 to add the legend to the plot.
## Warning: package 'ggplot2' was built under R version 4.1.2
myplots <- rvn_forcings_plot(ff_data$forcings) myplots$Radiation + theme(legend.position = "bottom")
We can similarly access the hydrograph fit. Here the hydrograph sample data is located with the usual
system.file command, then read into R with the
rvn_hyd_read function intended for reading Hydrographs file. The flows from a specific subbasin can be extracted using the
rvn_hyd_extract function, which is done here for subbasin 36. The precipitation can be extracted similarly.
ff <- system.file("extdata","run1_Hydrographs.csv", package = "RavenR") # ff <- "mydirectory/Hydrographs.csv" # replace with your own file hy <- rvn_hyd_read(ff) head(hy$hyd)
## Warning: timezone of object (UTC) is different than current timezone ().
## precip Sub36 Sub36_obs Sub43 Sub43_obs ## 2002-10-01 NA 5.96354 NA 11.25050 NA ## 2002-10-02 3.468690 11.96430 0.801 18.59070 3.07 ## 2002-10-03 1.189180 15.43700 0.828 25.74430 2.99 ## 2002-10-04 2.083260 8.76948 0.860 18.68610 3.06 ## 2002-10-05 6.474310 4.66501 0.903 9.82648 2.93 ## 2002-10-06 0.125591 4.20829 1.040 7.90952 3.15
flow36 <- rvn_hyd_extract("Sub36",hy) precip <- hy$hyd$precip
The hydrograph object flow36 now stores the simulated hydrograph (
flow36$sim) and the observed hydrograph (
flow36$obs), and the null subobject (
flow36$inflow). The precip object stores the entire time series of watershed-averaged precip (
precip$sim). We can plot the simulated and observed hydrograph with the following commands in base R, extracting the date:
plot(lubridate::date(flow36$sim), flow36$sim,col='red', type='l', panel.first=grid()) lines(lubridate::date(flow36$obs), flow36$obs,col='black')
A ggplot format plot can also be created using the
rvn_hyd_plot function in the RavenR library. This function can save some of the trouble of plotting the precipitation on the secondary axis.
rvn_hyd_plot(sim=flow36$sim, obs=flow36$obs, precip = precip)
There are some other helpful functions in RavenR for understanding our hydrographs. For example, the ‘spaghetti’ plot overlays the hydrographs from the supplied series and plots them against day of year on the x-axis, facilitating a comparison across multiple years.
The annual quantiles function compute the flow quantiles for a given time series for each day of the year, and plot those quantiles with the corresponding plot function. This provides a similar look to the spaghetti plot, but with smooth quantiles instead of overlaying time series.
rvn_annual_quantiles(flow36$sim) %>% rvn_annual_quantiles_plot(., ribboncolor = 'magenta')
Other plots indicate the agreement between peak flows in the modelled and observed.
rvn_annual_peak(flow36$sim, obs = flow36$obs)
## $df_peak ## date.end sim.peak obs.peak ## 1 2003-09-30 98.1327 74.4 ## 2 2004-09-30 155.3560 168.0 ## ## $p1
rvn_annual_peak_event(flow36$sim, obs = flow36$obs)
## $df_peak_event ## obs.dates sim.peak.event obs.peak.event ## 1 2003-03-23 35.7503 74.4 ## 2 2004-03-07 98.9858 168.0 ## ## $p1
We can also use some of the Raven plots to get some diagnostics and comparisons on the simulated and observed hydrographs. For example, the plots below compare the annual cumulative flow and the monthly volume bias, respectively.
rvn_cum_plot_flow(flow36$sim, obs = flow36$obs)
rvn_monthly_vbias(flow36$sim, obs = flow36$obs)
## $df.mvbias ## mvbias ## Jan 14.218038 ## Feb -31.634886 ## Mar 15.934117 ## Apr -36.526804 ## May -61.526206 ## Jun -55.782838 ## Jul -69.457872 ## Aug -70.455088 ## Sep 35.169824 ## Oct 1.325446 ## Nov 83.761819 ## Dec 29.171061 ## ## $plot