In BoulderCodeHub/CoRiverNF: Colorado River Natural Flow Data

Background

CoRiverNF is a data only package containing natural flow data for the Colorado River Basin. The data are included at the natural flow basin nodal level used by the Colorado River Simulation System (CRSS).

The purpose of the package is to streamline the process of getting the natural flow data in R, by providing the data as an R package. There are 6 data sets included in the package:

Monthly total natural flow: monthlyTot
Monthly intervening natural flow: monthlyInt
Calendar year total natural flow: cyAnnTot
Calendar year intervening natural flow: cyAnnInt
Water year total natural flow: wyAnnTot
Water year intervening natural flow: wyAnnInt

Using the Natural Flow Data

All of the provided natural flow data are saved as xts matrices with one variable for each natural flow node. The xts package is attached when attaching the CoRiverNF package. Storing the data as an xts object helps provide easy access to different time periods of data.

When loading the package, a message will post letting you know the source data for the natural flows.

library(CoRiverNF)

Variables

Each of the variable names reflects a variable name that simplifies the full USGS gage name that describes a natural flow sub-basin. The following table maps the natural flow sub-basin number to the full USGS gage names and to the abbreviated names that are used as the variables names in the xts objects. The following figure shows where each sub-basin is located with the Colorado River Basin.

nf_gage_table <- structure(
  c(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, 
    "Colorado River At Glenwood Springs, CO", "Colorado River Near Cameo, CO", 
    "Taylor River Below Taylor Park Reservoir, CO", 
    "Gunnision River Above Blue Mesa Reservoir,CO", 
    "Gunnison River At Crystal Reservoir,CO", 
    "Gunnison River Near Grand Junction, CO", 
    "Dolores River Near Cisco, UT", "Colorado River Near Cisco UT", 
    "Green R Bel Fontenelle Res WY", "Green R. Nr Green River, WY", 
    "Green River Near Greendale, UT", "Yampa River Near Maybell, CO", 
    "Little Snake River Near Lily, CO", "Duchesne River Near Randlett, UT", 
    "White River Near Watson, UT", "Green River At Green River, UT", 
    "San Rafael River Near Green River, UT", "San Juan River Near Archuleta,NM", 
    "San Juan River Near Bluff, UT", "Colorado R At Lees Ferry, AZ", 
    "Paria R At Lees Ferry, AZ", "Little Colorado River Near Cameron, AZ", 
    "Colorado River Near Grand Canyon, AZ", "Virgin River At Littlefield, AZ", 
    "Colorado River Below Hoover Dam, AZ-NV", 
    "Colorado River Below Davis Dam, AZ-NV", 
    "Bill Williams River Below Alamo Dam, AZ", 
    "Colorado River Below Parker Dam, AZ-CA", 
    "Colorado River Above Imperial Dam, AZ", "GlenwoodSprings", "Cameo", 
    "TaylorPark", "BlueMesa", "Crystal", "GrandJunction", "CiscoDolores", 
    "CiscoColorado", "Fontenelle", "GreenRiverWY", "Greendale", "Maybell", 
    "Lily", "Randlett", "Watson", "GreenRiverUTGreen", "GreenRiverUTSanRafael", 
    "Archuleta", "Bluff", "LeesFerry", "LeesFerryParia", "Cameron", 
    "GrandCanyon", "Littlefield", "Hoover", "Davis", "Alamo", "Parker", 
    "Imperial"
  ), 
  .Dim = c(29L, 3L), 
  .Dimnames = list(NULL, c("Natural Flow Sub-basin", "USGS Gage Name", "Abbreviated Name"))
)
knitr::kable(nf_gage_table)

knitr::include_graphics("CRSS_subbasins_Jan-8-2020_noTable.png")

These variable names and full USGS gage names can be accessed in CRSSIO::nf_gage_abbrv() and CRSSIO::nf_gage_names(), respectively.

Examples of Accessing Data

For example one can access the 2010 monthly total natural flow at Lees Ferry:

monthlyTot$LeesFerry['2010']

Or, the annual total natural flow on the Green River at Greendale from 1960-1970 is:

cyAnnTot$Greendale['1960/1970']

And finally, the beginning of the record until March 1907 or September 2015 until the end of the record are accessed with:

monthlyInt$Imperial['/1907-03']
monthlyTot$Bluff['2015-09/']

To get the flow in a single month for the entire time period, use xts::.indexmon. For example to select data for July of every year (head() shows only the first 6 rows):

head(monthlyInt$Cameo[.indexmon(monthlyInt$Cameo)==6]) # note its 0-based indexing

See the xts package documentation for additional information on accessing and using the xts object.

Examples of Aggregating Data

The xts package contains helpful functions for aggregating xts data. For example you can quickly convert the monthly data into annual data. The summed monthly data will match the provided annual data:

lfAnn <- xts::apply.yearly(monthlyTot$LeesFerry, sum)
# compare the two, but drop 1905 from lfAnn since it is not
# a full year
all.equal(lfAnn['1906/'], cyAnnTot$LeesFerry)

From the output of all.equal we see the only thing not equal is the sheet name that the original data was derived from.

Summing across a water year is slightly more involved:

lfWY <- xts::period.sum(monthlyTot$LeesFerry,endpoints(monthlyTot$LeesFerry, on="months",k=12))
# this time cut off data after WY 2012
range(lfWY['/2012-09']-wyAnnTot$LeesFerry)

The above use of endpoints only works because the data start at the beginning of a water year. Also, the values are compared instead of the entire object because some attributes are modified with the call to period.sum. A more robust solution to the water year sum is:

lf <- monthlyTot$LeesFerry
# get all the indeces for Septembers
myIndex <- lf[index(lf[.indexmon(lf)==8]), which.i=TRUE]
# summ using all Septembers as the endpoints for the summation
lfWY2 <- xts::period.sum(lf, myIndex)
# compare to the first solution
all.equal(lfWY, lfWY2)

This ensures your grabbing all of the Septembers (.indexmon()==8).

Currently, passing period.sum or apply.yearly to apply, e.g., apply(data, 2, period.sum), is not working. Thus it is difficult to get annual values for all nodes simultaneously.

Plotting

The include natural flow data will easily work with ggplot2 and dygraphs, among other plotting packages.

library(ggplot2)
ggplot(cyAnnTot, aes(x=index(cyAnnTot))) + 
  geom_line(aes(y=LeesFerry)) +
  scale_x_continuous() + 
  scale_y_continuous()

To compare intervening flow on the Colorado River at Cameo to the Gunnison River at Grand Junction using dygraphs:

library(dygraphs)
# column 2 is Cameo, column 6 is Grand Junction
dygraph(monthlyInt['2002/2005',c(2,6)])

Updating the Natural Flow Data

When new natural flow data are released, approximately every year, the package will be updated to include the new data. The code used to create the data in this package is available on the Github repository for this package. The getHistoricalNFData.R file can be updated to use the new source workbook.