The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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)')

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.