---
title: "Introduction to the RivRetrieve R package"
author: 'Ryan M. Riggs and Simon Moulds'
date: "`r format(Sys.time(), '%B %d, %Y')`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{my-vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding[utf8]{inputenc}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",warning=FALSE,message=FALSE,fig.width=7
)
```

## 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.

```{r setup}
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:

```{r,echo=TRUE}
library(knitr)
## kable(raw[1:5,],caption='Raw Brazilian gauge data')

raw=original(discharge)
kable(raw[1:5,],caption='Raw US gauge data')
```

## Site locations for all agencies can also be found:

```{r,echo=TRUE}
## 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')
```

## Date defined retrieval

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

```{r}
# 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)')
```