Introduction to the RivRetrieve R package

Ryan M. Riggs and Simon Moulds

April 22, 2024

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')
siteNumber="K027401001"
discharge=france(site=siteNumber,variable='discharge')
stage=france(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:

raw=original(discharge)
library(knitr)
## kable(raw[1:5,],caption='Raw Brazilian gauge data')
kable(raw[1:5,],caption='Raw French gauge data')
Raw French gauge data
code_site code_station date_obs_elab resultat_obs_elab date_prod code_statut libelle_statut code_methode libelle_methode code_qualification libelle_qualification longitude latitude grandeur_hydro_elab
K0274010 K027401001 1997-12-19 386 2024-02-28T12:02:09Z 16 Donnée validée 12 Interpolation 20 Bonne 3.962542 45.05748 QmJ
K0274010 K027401001 1997-12-20 400 2024-02-28T12:02:09Z 16 Donnée validée 12 Interpolation 20 Bonne 3.962542 45.05748 QmJ
K0274010 K027401001 1997-12-21 381 2024-02-28T12:02:09Z 16 Donnée validée 12 Interpolation 20 Bonne 3.962542 45.05748 QmJ
K0274010 K027401001 1997-12-22 356 2024-02-28T12:02:09Z 16 Donnée validée 12 Interpolation 20 Bonne 3.962542 45.05748 QmJ
K0274010 K027401001 1997-12-23 324 2024-02-28T12:02:09Z 16 Donnée validée 12 Interpolation 20 Bonne 3.962542 45.05748 QmJ

Site locations for all agencies can also be found:

## brazilSites=brazil(sites=TRUE)
franceSites=france(sites=TRUE)
## kable(brazilSites[1:10,],caption='Example Brazilian river gauge locations')
kable(franceSites[1:10,],caption='Example French river gauge locations')
Example French river gauge locations
site latitude longitude
1011000101 16.18940 -61.65899
1011000201 16.19583 -61.65195
1011000301 16.19395 -61.65561
1011000401 16.15827 -61.67278
1015000101 16.17600 -61.69320
1016000101 16.19914 -61.66644
1016000201 16.20282 -61.65723
1016000301 16.19343 -61.67339
1020000101 16.20512 -61.65309
1021000101 16.22531 -61.66868

Date defined retrieval

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

# Annual timeseries
## siteNumber='17050001'
siteNumber="K027401001"
start='2009-01-01'
end='2010-01-31'
## recent=brazil(site=siteNumber,variable='stage',start_date = start,end_date = end)
recent=france(site=siteNumber,variable='stage',start_date = start,end_date = end)
plot(recent$Date,recent$H,type='l', xlab='',ylab='Stage (m)')