---
title: "Accessing NOAA data"
author: "Troy D. Hill"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Accessing NOAA data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction 

The VulnToolkit R package provides tools for summarizing and analyzing tidal data. It also includes interfaces to [Permanent Service for Mean Sea Level (PSMSL)](https://www.psmsl.org) data and time series data and station-level summary data collected by [National Oceanic and Atmospheric Administration (NOAA) datasets](https://www.tidesandcurrents.noaa.gov/stations.html?type=Water+Levels). This vignette describes the functions that interact with NOAA and PSMSL databases.

## An important note

Functions that interact with web sites are challenging to work with and troubleshoot. There are many more potential sources of trouble, which makes problems difficult to isolate. Workplaces may block R from interacting with web sites. A user's internet or the web site may be down or be slow to respond. A recent change to the website may have been incompatible with the code.

One small step that can be taken to minimize these frustrating issues is to verify that your computer has curl installed and accessible. `VulnToolkit` uses curl to interact with web sites. The availability of curl can be checked by running the command `Sys.which("curl")` and verifying that the curl executable is listed.


## Accessing NOAA Tides and Currents data

NOAA stations are referred to by their station numbers, which are available on the Tides and Currents station page linked above. We'll use the New London, CT station (station no. 8461490).

Data can be downloaded with a call to `noaa`: 

```{r, echo = FALSE, message=FALSE, warning=FALSE, results = "hide", eval=FALSE}
library(VulnToolkit)

### 6-minute data
NL2013 <- noaa(begindate = 20130101, enddate = 20131231, 
  station = "8461490", interval = "6 minute", 
  units = "meters", datum = "MHW", time = "GMT")

### high/low tides
NL2013_HL <- noaa(begindate = 20130101, enddate = 20131231, 
  station = "8461490", interval = "HL", 
  units = "meters", datum = "MHW", time = "GMT")


### multiple stations can be downloaded at the same time using lapply:
stns <- c("8461490", "8518750")
### output is a list with an element for each station 
datList <- lapply(X = stns, FUN = noaa, 
          begindate = 20130101, enddate = 20131231, interval = "6 minute", 
          units = "meters", datum = "MHW", time = "LST")


```

```{r, echo = FALSE, include = FALSE}
library(VulnToolkit)
NL2013 <- NL_6min_2013
```


A benefit of `VulnToolkit` is that it accommodates NOAA download limits by breaking up large data requests into multiple smaller requests, and merging the result. By doing this, a user can quickly download multiple years of 6-minute data.


Some NOAA stations also collect meteorological data. If available (check with `noaa.parameters(stn = "8461490")`), meteorological data can be downloaded in the `noaa()` call by setting `met = TRUE`.


### NOAA station information

`VulnToolkit` provides access to station-level data such as tidal datums and harmonic constituents. 

``` {r, eval=FALSE}

bport.datums   <- noaa.datums(station = 8461490) # New London, CT
battery.datums <- noaa.datums(station = 8518750) # Battery, NYC

### retrieve harmonic constituents
bport.cons <- harcon(station = 8461490) # New London, CT
bport.cons

### calculate form number 
formDat  <- form.no(station = 8461490) # New London, CT
### Multiple stations at once:
stn.list <- c("8467150", "8461490", "9454240") 
formDat2 <- form.no(stn.list)

```


## Accessing Permanent Service for Mean Sea Level data

PSMSL data is accessed by two functions. `psmsl.stations` returns a dataframe with all of the PSMSL stations, and `psmsl` provides an interface to the actual sea level data. PSMSL data are in monthly or annual time scales, and span the globe.


```{r, eval = FALSE}
psmsl.stns <- psmsl.stations(country = "USA", sort.by = "name")
 
### using the psmsl.stations call to define stations
data.v1 <- psmsl(station = psmsl.stns[c(42, 70), 1])

### call stations by name or ID
data.v2 <- psmsl(station = c("DEPOE BAY", "JUNEAU"), interval = "monthly")
data.v3 <- psmsl(station = c(1372, 12), interval = "monthly")
data.v4 <- psmsl(station = c("DEPOE BAY", 12), interval = "monthly")


```