README.Rmd

---
title: "bsw"
output: github_document
---

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

Provides for access to [Bended Sea Winds](https://www.ncei.noaa.gov/products/blended-sea-winds) online.

### [Citation](https://www.ncei.noaa.gov/products/blended-sea-winds)

### Requirements

From CRAN...

  + [R v4+](https://www.r-project.org/)
  + [rlang](https://CRAN.R-project.org/package=rlang)
  + [dplyr](https://CRAN.R-project.org/package=dplyr)
  + [stars](https://CRAN.R-project.org/package=stars)
  + [sf](https://CRAN.R-project.org/package=sf)
  
From github...

  + [xyzt](https://github.com/BigelowLab/xyzt)
  

### Installation

```
remotes::install_github("BigelowLab/bsw")
```

```{r}
suppressPackageStartupMessages({
  library(bsw)
  library(dplyr)
  library(sf)
  library(xyzt)
  library(stars)
})
```

#### Organization of Blended Sea Winds

Blended Sea Winds are organized by product and interval.  The two primary product types are `[u,v,w]` wind velocities and `[taux, taux, tau]` wind stresses.  Each product type is organized further by aggregation interval `[6h, daily, monthly]`.  Wind velocity also have a climatalogical aggregate mean (not served for stress.) Note that for 6h wind and 6h stress only `[u,v]` and `[taux, tauy]` are served.

```{r}
bsw_tally()
```


#### Working with points.  

See the [xyzt](https://github.com/BigelowLab/xyzt) package for more details on the example Southern US Atlantic Bight data.  Note we must transform the longitude values from [-180, 180] to [0,360] to work with BSW data.

```{r}
# read in example SAB points - note that time is required as a dimension
x <- xyzt::read_sab() |>
  dplyr::select(-time, -depth) |>
  dplyr::mutate(lon = xyzt::to_360(lon),
                time = as.POSIXct("1995-12-18 23:00:05", tz = "UTC")) |>
  xyzt::as_POINT(dims = "xyt")


# generate the BSW url for a given product
url <- bsw_url("Aggregation_of_6h_Ocean_Wind")


# open the resource (we can close it later)
X <- ncdf4::nc_open(url)

# extract the data 
covars <- bsw::extract(x, X, varname = c("u", "v"))

# bind to the input
(y <- dplyr::bind_cols(x, covars))
```

#### Working with bounding boxes (from points or polygons). 

Learn more about working with [stars](https://CRAN.R-project.org/package=stars) objects in the [vignettes](https://r-spatial.github.io/stars/).

```{r}
# read in example SAB points
x <- xyzt::read_sab() |>
  dplyr::select(-time, -depth) |>
  dplyr::mutate(lon = xyzt::to_360(lon),
                time = as.POSIXct("1995-12-18 23:00:05", tz = "UTC")) |> 
  xyzt::as_BBOX(dims = 'xyt')

(covars <- bsw::extract(x, X, varname = c("u", "v")))
```

Now let's see what it looks like.

```{r}
x <- xyzt::read_sab() |>
  dplyr::select(-time, -depth) |>
  dplyr::mutate(lon = xyzt::to_360(lon)) |>
  xyzt::as_POINT()
par(mfrow = c(1,2))
plot(covars, attr = 'u', axes = TRUE, reset = FALSE)
plot(sf::st_geometry(x), add = TRUE, col = "orange", pch = 19, cex = 2)
```



```{r}
# cleanup
ncdf4::nc_close(X)
```