README.Rmd

---
title: "gstream"
output: github_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

Serving Gulf Stream datasets directly from R.

## Requirements

[R v4.1+](https://www.r-project.org/)

[rlang](https://CRAN.R-project.org/package=rlang)

[dplyr](https://CRAN.R-project.org/package=dplyr)

[sf](https://CRAN.R-project.org/package=sf)


## Installation

Use the [remotes](https://CRAN.R-project.org/package=remotes) package to install directly from github.

```         
remotes::install("BigelowLab/gstream)
```

## Data

The data for this package is manually curated - and we'll update it as needed.

### Getting the data

The data used for this package is maintained [here](https://drive.google.com/file/d/1bozOVwdVhT-amEI4Zax7IdDdQZcU5-EM/view?usp=share_link).  Manually download the data, [uncompress](https://github.com/BigelowLab/compressr) it and place it in your favorite data storage site. 

### Set your data path

Next we need to allow this package to **securely** know where you have saved the data.  We do this by placing a hidden text file in your **home** directory.  If you are sharing this data with others (say on a network drive) then each user of the package will need to set up this file.  So, into this file named `~/.gstream` place this content.  Obviously, you will want to replace the paths with ones appropriate for your platform.  

```
path: /mnt/s1/projects/ecocast/coredata/gstream
usn:
  datapath: /mnt/s1/projects/ecocast/coredata/gstream/usn
  rawpath: /mnt/s1/projects/ecocast/coredata/gstream/usn/raw
  dailyuri: https://ocean.weather.gov/gulf_stream_latest.txt
  ftpuri: https://ftp.opc.ncep.noaa.gov/grids/experimental/GStream
```

Now you can test if the package can find the path yout specified.

```{r}
suppressPackageStartupMessages({
  library(gstream)
  library(sf)
  library(dplyr)
  library(rnaturalearth)
})

path = gstream_path()
path
```



## Usage

The package contains a number of data sets compiled with the purpose of aiding Gulf Stream and AMOC analyses. Beyond access and simple plotting utilities, no effort has been made to include sophisticated analyses.

## Gulf Stream Index (GSI)

The [Gulf Stream Index](https://en.wikipedia.org/wiki/Latitude_of_the_Gulf_Stream_and_the_Gulf_Stream_north_wall_index) provides a positional index. Data are provides via the [ecodata](https://noaa-edab.github.io/ecodata/) R package. If the package is installed, then this package serves the data it provides with a convneient plotting routine.  If the package is not installed, then it is an error to try to read the GSI index with this package.


```{r, message=FALSE}
x = read_gsi() |>
  dplyr::glimpse()
```

```{r}
plot(x)
```

We can also plot from monthly and annual perspectives.

```{r}
plot(x, by = "month")
```

```{r}
plot(x, by = 'year')
```


## Gulf Stream SST Gradient Index (GSGI)

[Parfitt, Kwon, and Andres, 2022](https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2022GL100914) proposed a Gulf Stream Gradient Index.  Data is served for 2004-2019 [here](https://www2.whoi.edu/staff/ykwon/data/).

> Parfitt, R., Y.-O. Kwon, and M. Andres, 2022: A monthly index for the large-scale sea surface temperature gradient across the separated Gulf Stream. Geophys. Res. Lett., 49, e2022GL100914. https://doi.org/10.1029/2022GL100914.

```{r read_gsgi}
x = read_gsgi() |>
  dplyr::glimpse()
```

```{r plot_gsgi}
plot(x)
```

We also can plot from a climatology perspective.

```{r, plot_gsgi_month}
plot(x, by = "month")
plot(x, by = "year")
```

## Data from [RAPID](https://rapid.ac.uk)


### [RAPID-AMOC](https://rapid.ac.uk/rapidmoc)

Data from the RAPID AMOC monitoring project is funded by the Natural Environment Research Council and are freely available from www.rapid.ac.uk/rapidmoc.

Reference for Version v2020.2
>Moat B.I.; Frajka-Williams E., Smeed D.A.; Rayner D.; Johns W.E.; Baringer M.O.; Volkov, D.; Collins, J. (2022). Atlantic meridional overturning circulation observed by the RAPID-MOCHA-WBTS (RAPID-Meridional Overturning Circulation and Heatflux Array-Western Boundary Time Series) array at 26N from 2004 to 2020 (v2020.2), British Oceanographic Data Centre - Natural Environment Research Council, UK. doi:10.5285/e91b10af-6f0a-7fa7-e053-6c86abc05a09 

```{r, warning=FALSE}
x = read_moc_transports() |>
  dplyr::glimpse()
```

```{r}
plot(x)
```

### [RAPID-MOCHA](https://mocha.earth.miami.edu/mocha/data/index.html)

RAPID-MOCHA provides a heat transport timeseries.

```{r, mocha}
x = read_rapid_mocha() |>
  dplyr::glimpse()
```

```{r, plot_mocha}
plot(x)
```

```{r, plot_mocha_day}
plot(x, by = 'day')
```

```{r, plot_mocha_year}
plot(x, by = 'year')
```

## SST Patch Data

We defined two bounding boxes in the North Atlantic - one for the persistent "cold blob" centered south of Iceland and another for the "warm spot" south of New England and Martime Canada.  We extracted monthly [ERSST](https://www.ncei.noaa.gov/products/extended-reconstructed-sst) data and computed monthly [OISST](https://www.ncei.noaa.gov/products/optimum-interpolation-sst) sea surface temperature statistics for each.

```{r}
# read the boxes but exclude the northern hemisphere record
bb = read_patch_bbs() |>
  dplyr::filter(name != "nh")
bb
```
```{r}
x = read_patch_month() |>
  dplyr::glimpse()
```

```{r}
plot_patch_location(bb)
```

```{r}
plot(x)
```

## Data from US Navy

### Archived data

[NOAA's Ocean Prediction Center](https://ocean.weather.gov/) provides a FTP server](https://ftp.opc.ncep.noaa.gov/grids/experimental/GStream) for downloads by year.  We have downloaded these and repackaged into spatial format files - these are included with the `gstream` package. They also provide [daily updates](https://ocean.weather.gov/gulf_stream_latest.txt).

```{r, warn = FALSE}
x = read_usn(what = "orig") |>
  dplyr::glimpse()
```

This reads in all of the data stored with the package. We can then do a simple plot of all of the locations.

```{r}
bb = sf::st_bbox(x)
coast = rnaturalearth::ne_coastline(scale = "medium", returnclass = "sf")

plot(x['wall'], pch = ".", axes = TRUE, reset = FALSE)
plot(sf::st_geometry(coast), add = TRUE)
```

### Downloading daily updates and configuration

**Note** that you don't need to create the configuration file if you are not downloading data.

The daily data is hosted by by [NOAA's Ocean Prediction Center](https://ocean.weather.gov/) In particular they post the US Navy's [daily Gulf Stream point data](https://ocean.weather.gov/gulf_stream_latest.txt) for the north and south walls. These can be downloaded.  We provide a mechanism for storing the URL of the daily data, the path to where you want to store the downloads and a simple script for downloading.  The configuration can be stored anywhere, but by default we look for it isn `~/.gstream`.


```{r}
cfg = read_configuration()
cfg
```

Obviously, you will want to modify the `rawpath` to suit your own needs. We then set up a cron job to make the daily download at local 6pm.

```
# gstream data
0 18 * * * /usr/local/bin/Rscript /Users/ben/Library/CloudStorage/Dropbox/code/projects/gsi/inst/scripts/usn_daily_download.R >> /dev/null 2>&1
```


### Ordering USN data

The USN data is not ordered, that is the points for a given day are not following a polyline. 

```{r}
d = dplyr::filter(x, date == as.Date("2020-12-19"), wall == "north")
plot(sf::st_geometry(d), type = "l", axes = TRUE)
```

With thanks to [Dewey Dunnington](https://gist.github.com/paleolimbot/0be47836de5008f308959923dac02c5b#gistcomment-5079768) we can reorder them into a single `LINESTRING`.

```{r}
d = dplyr::filter(x, date == as.Date("2020-01-03"), wall == "north")
do = order_usn(d)
plot(sf::st_geometry(d), type = "l", axes = TRUE, reset= FALSE)
plot(sf::st_geometry(do), type = "l", add = TRUE, col = "orange")
```