Introduction to the RivRetrieve R package

Ryan M. Riggs and Simon Moulds

January 08, 2025

Here is a quick tutorial for RivRetrieve functions:

The RivRetrieve package is developed to efficiently access and download global river gauge data into an R environment. While numerous river data exists, our package is currently limited to daily measurements of river stage (meters) and discharge (cubic meters per second) for: Australia, Brazil, Canada, Chile, France, Japan, South Africa, the United Kingdom, and the United States.

library(RivRetrieve)
# Amazon River near Obidos, Brazil
## siteNumber='17050001'
## discharge=brazil(site=siteNumber,variable='discharge')
## stage=brazil(site=siteNumber,variable='stage')
## plot(discharge$Date,discharge$Q, type='l',xlab='',ylab='Discharge (cms)')

# Mississippi River near Baton Rouge, LA, USA
siteNumber="07374000"
discharge=usa(site=siteNumber,variable='discharge')
stage=usa(site=siteNumber,variable='stage')
plot(discharge$Date,discharge$Q, type='l',xlab='',ylab='Discharge (cms)')

RivRetrieve automatically outputs a dataframe containing a Date column of datetime values and either a H or Q numeric column for the stage and discharge variable, respectively.

Stage is provided in meters and discharge is provided in cubic meters per second.

Accessing the raw gauge data:

library(knitr)
## kable(raw[1:5,],caption='Raw Brazilian gauge data')

raw=original(discharge)
kable(raw[1:5,],caption='Raw US gauge data')
Raw US gauge data
agency_cd site_no Date X_00060_00003 X_00060_00003_cd
USGS 07374000 2004-03-17 726000 A
USGS 07374000 2004-03-18 752000 A
USGS 07374000 2004-03-19 769000 A
USGS 07374000 2004-03-20 786000 A
USGS 07374000 2004-03-21 799000 A

Site locations for all agencies can also be found:

## brazilSites=brazil(sites=TRUE)
## kable(brazilSites[1:10,],caption='Example Brazilian river gauge locations')

usaSites=usa(sites=TRUE)
kable(usaSites[1:10,],caption='Example US river gauge locations')
Example US river gauge locations
site latitude longitude
02479500 30.86241 -88.41779
02480020 30.63936 -88.39307
02479960 30.78713 -88.36696
02479431 31.16101 -88.36196
02479955 30.80852 -88.33668
02480000 30.72936 -88.33612
02479945 30.85602 -88.33390
02468000 32.43347 -88.33336
02479980 30.78019 -88.31890
02479950 30.81130 -88.31584

Date defined retrieval

Specific time periods can also be accessed if the entire time series is not needed.

# Annual timeseries
## siteNumber='17050001'
## recent=brazil(site=siteNumber,variable='stage',start_date = start,end_date = end)
## plot(recent$Date,recent$H,type='l', xlab='',ylab='Stage (m)')

siteNumber="07374000"
start='2009-01-01'
end='2010-01-31'
recent=usa(site=siteNumber,variable='stage',start_date = start,end_date = end)
plot(recent$Date,recent$H,type='l', xlab='',ylab='Stage (m)')