Introduction to {resourcecode}

#> Note: Examples in this vignette require that the `resourcecodedata`
#> package be installed. The system currently running this vignette does
#> not have that package installed, so code examples will not be
#> evaluated.

The goal of {resourcecode} is to provide an easy access to the ResourceCODE hindcast database of sea-states. More information on the database can be found here. We will explain in this vignette the way to retrieve data from this database and some the functionalities offered by this package.

This package depends on data in a data package {resourcecodedata} that is available through a drat repository on GitHub. To use the {resourcecode} package, you will need to install {resourcecodedata} on your computer, using the following install.packages function (and later update it using the update.packages function):

install.packages("resourcecodedata",
  repos = "https://resourcecode-project.github.io/drat/",
  type = "source"
)

Once the packages are installed, we can proceed as usual:

library(resourcecodedata)
library(resourcecode)
library(ggplot2)

Database configuration: nodes, bathymetry…

There are two grids in the ResourceCODE hindcast database: the full, dense, FIELD grid, which is the grid where the numerical WWIII model is run and where sea-state parameters and only 1D spectra are available. The second grid, SPEC, is coarser, but contains the full 2D spectral data at each node.

  • FIELD grid

The variable rscd_field contains the coordinates of the FIELD grid, along with the depth of these points and d50, the bottom sediment type.

str(rscd_field)
head(rscd_field)

At each location, a large number of sea-state parameters are available, described in rscd_variables:

str(rscd_variables)
head(rscd_variables)

The available location can be plotted on a map using the following code. It can be noticed here that the variables rscd_coastline and rscd_islands contain the path of the coast line and the islands, respectively.

lim_lon <- c(-5.25, -4.25)
lim_lat <- c(47.75, 48.75)
field_bzh <- ggplot(rscd_field, aes(x = longitude, y = latitude)) +
  geom_point(size = .1, col = "lightblue") +
  geom_path(data = rscd_coastline, linewidth = .2) +
  geom_path(data = rscd_islands, aes(group = .data$ID), linewidth = .2) +
  coord_sf(xlim = lim_lon, ylim = lim_lat, expand = FALSE, crs = sf::st_crs(4326)) +
  theme_void()
field_bzh
  • SPEC grid

The spectral grid, or SPEC grid is coarser, with more than 24,000 nodes where the full 2D spectra are available. The grid can be added to the previous plot to see the differences in the spatial coverage.

str(rscd_spectral)
head(rscd_spectral)
field_bzh + geom_point(data = rscd_spectral, col = "orange", size = .1)
  • Helpers to find points

When one is interested in some location, we also provide helpers to find the closest point in each of the grid, via the closest_point_FIELD() and closest_point_SPEC() functions.

Getting data

We have two different sources of data, the FIELD grid, and the SPEC grid. We will cover each use case here.

  • Sea-state parameters from the FIELD can be retrieved using the get_parameters() function, which allows to download a time series easily at a given location. For the moment (Sept. 2023), the 1D spectra on this grid are not available to direct download.

For example, if one is interested in the time series of sea-state parameters at some location, the following code can be adapted:

point_of_interest <- c(longitude = -4.6861533, latitude = 48.3026514)
node <- closest_point_field(point_of_interest)
node
ts <- get_parameters(node = node$point, parameters = c("hs", "tp", "dp", "cge"))
ggplot(tidyr::pivot_longer(ts, -1), aes(x = time, y = value, col = name)) +
  geom_line() +
  coord_cartesian(expand = FALSE) +
  facet_wrap(~name, ncol = 2, scales = "free_y") +
  scale_x_datetime(name = NULL, date_breaks = "month") +
  scale_y_continuous(name = NULL) +
  theme_minimal() +
  theme(
    legend.position = "none",
    axis.text.x = element_text(angle = 60, hjust = 1)
  )
  • 1D and 2D spectra of the SPEC grid can be downloaded directly from IFREMER FTP using functions get_1Dspectrum() and get_2Dspectrum(). We also provide a plotting function for the 2D spectrum.
node_spectral_grid <- closest_point_spec(point_of_interest)

Then one can extract the 1D spectrum time-series and see the contents of these downloaded data.

spec_1d <- get_1d_spectrum(node_spectral_grid$point, start = "1994-01-01", end = "1994-02-28")
str(spec_1d)

The same applies to 2D spectra.

spec_2d <- get_2d_spectrum(node_spectral_grid$point, start = "1994-01-01", end = "1994-02-28")
str(spec_2d)

In addition, it is possible to plot the wave elevation directional spectra for any given time, which can be specified by the time index or directly the date:

plot_2d_specta(spec_2d, "1994-01-15 18:00")