Title: Access to the 'RESOURCECODE' Hindcast Database
Version: 0.2.1
Date: 2024-11-29
Description: Utility functions to download data from the 'RESOURCECODE' hindcast database of sea-states, time series of sea-state parameters and time series of 1D and 2D wave spectra. See https://resourcecode.ifremer.fr for more details about the available data. Also provides facilities to plot and analyse downloaded data, such as computing the sea-state parameters from both the 1D and 2D surface elevation variance spectral density.
License: GPL (≥ 3)
URL: https://github.com/Resourcecode-project/r-resourcecode, https://resourcecode-project.github.io/r-resourcecode/
BugReports: https://github.com/Resourcecode-project/r-resourcecode/issues
Depends: R (≥ 3.6)
Imports: abind, curl, geosphere, ggplot2, jsonlite, ncdf4, pracma, Rcpp, rlang, sf, stats, tibble, tidyr
Suggests: knitr, rmarkdown, resourcecodedata, testthat, vdiffr
LinkingTo: Rcpp, RcppArmadillo
VignetteBuilder: knitr
Additional_repositories: https://resourcecode-project.github.io/drat/
Config/testthat/edition: 3
Config/testthat/parallel: true
Encoding: UTF-8
Language: en-US
LazyData: true
RoxygenNote: 7.3.2
NeedsCompilation: yes
Packaged: 2024-12-02 14:54:43 UTC; nraillar
Author: Nicolas Raillard ORCID iD [aut, cre]
Maintainer: Nicolas Raillard <nicolas.raillard@ifremer.fr>
Repository: CRAN
Date/Publication: 2024-12-03 19:00:05 UTC

resourcecode: Access to the 'RESOURCECODE' Hindcast Database

Description

logo

Utility functions to download data from the 'RESOURCECODE' hindcast database of sea-states, time series of sea-state parameters and time series of 1D and 2D wave spectra. See https://resourcecode.ifremer.fr for more details about the available data. Also provides facilities to plot and analyse downloaded data, such as computing the sea-state parameters from both the 1D and 2D surface elevation variance spectral density.

Author(s)

Maintainer: Nicolas Raillard nicolas.raillard@ifremer.fr (ORCID)

See Also

Useful links:

Value Matching

Description

Value Matching

Usage

x %nin% table

Arguments

x

value to search

table

table of values

Value

the opposite of x %in% table

Examples

1:10 %in% c(1, 3, 5, 9)
1:10 %nin% c(1, 3, 5, 9)

Find the closest point of the FIELD grid to the specified position

Description

Find the closest point of the FIELD grid to the specified position

Usage

closest_point_field(x, lat = NULL, closest = 1L, ...)

Arguments

x

vector of coordinates in the form longitude/latitude data frame

lat

alternatively, x and lat can be vector of the same length

closest

an integer to specify the number of point to output.

...

currently unused

Value

a list with two components: the closest point(s) of the grid and the distance (s).

Examples

# Ensure that data package is available before running the example.
#  If it is not, see the `resourcecode` package vignette for details
# on installing the required data package.
if (requireNamespace("resourcecodedata", quietly = TRUE)) {
  semrev_west <- closest_point_field(c(-2.786, 47.239))
  semrev_west
  }

Find the closest point of the SPEC grid to the specified position

Description

Find the closest point of the SPEC grid to the specified position

Usage

closest_point_spec(x, lat = NULL, closest = 1L, ...)

Arguments

x

vector of coordinates in the form longitude/latitude data frame

lat

alternatively, x and lat can be vector of the same length

closest

an integer to specify the number of point to output.

...

currently unused

Value

a list with two components: the closest point(s) of the grid and the distance (s).

Examples


  semrev_west <- closest_point_spec(c(-2.786, 47.239))
  semrev_west

Compute the orbital speed at a given depth from the wave elevation 1D spectra

Description

Compute the orbital speed at a given depth from the wave elevation 1D spectra

Usage

compute_orbital_speeds(spec, freq, z = 0, depth = Inf, output_speeds = FALSE)

Arguments

spec

1D spectral data: TxM matrix

freq

the M frequencies

z

distance above the floor at which we want the orbital speed (single numeric)

depth

depth time series (vector length T. Recycled if a single value is given)

output_speeds

TRUE if the spectral speed are needed. Otherwise, returns the RMS (default)

Value

depending on spec, a list with the spectral velocities for each component (if output_speeds==FALSE) or a data.frame with a time series of horizontal and vertical components of (spectral) orbital speed.

Examples

# Compute orbital speed for varying Hs
S <- t(sapply(1:10, \(h) jonswap(h)$spec))
orb_speeds <- compute_orbital_speeds(S, rscd_freq, depth = 100, z = 10)
plot(1:10, orb_speeds[, 1],
  type = "l",
  ylim = range(orb_speeds),
  xlab = "Hs (m)",
  ylab = "Orbital speed RMS (m/s)"
)
lines(1:10, orb_speeds[, 2], type = "l", col = "red")

Compute sea_state parameter from wave spectrum

Description

Compute sea_state parameter from wave spectrum

Usage

compute_sea_state_1d_spectrum(spec, ...)

Arguments

spec

1D spectrum data, e.g. from get_1Dspectrum

...

currently unused

Value

a tibble with the sea-state parameters computed from the time series of 2D spectrum

Examples

# Ensure that data package is available before running the example.
#  If it is not, see the `resourcecode` package vignette for details
# on installing the required data package.
if (requireNamespace("resourcecodedata", quietly = TRUE)) {
rscd_params <- get_parameters(
  node = "134865",
  start = "1994-01-01",
  end = "1994-01-31 23:00:00",
  parameters = c("hs", "tp", "cge", "t01", "dp", "dir")
)
spec <- resourcecodedata::rscd_1d_spectra
param_calc <- compute_sea_state_1d_spectrum(spec)
oldpar <- par(mfcol = c(2, 2))
plot(param_calc$time, param_calc$hs, type = "l", xlab = "Time", ylab = "Hs (m)")
lines(rscd_params$time, rscd_params$hs, col = "red")
plot(param_calc$time, param_calc$cge, type = "l", xlab = "Time", ylab = "CgE (kW/m)")
lines(rscd_params$time, rscd_params$cge, col = "red")
plot(param_calc$time, param_calc$tp, type = "l", xlab = "Time", ylab = "Tp (s)")
lines(rscd_params$time, rscd_params$tp, col = "red")
plot(param_calc$time, param_calc$dp, type = "l", xlab = "Time", ylab = "Peak direction (°)")
lines(rscd_params$time, rscd_params$dp, col = "red")
par(oldpar)
}

Compute sea_state parameter from wave directional spectrum

Description

Compute sea_state parameter from wave directional spectrum

Usage

compute_sea_state_2d_spectrum(spec, ...)

Arguments

spec

2D spectrum data, e.g. from get_2Dspectrum

...

currently unused

Value

a tibble with the sea-state parameters computed from the time series of 2D spectrum

Examples

# Ensure that data package is available before running the example.
#  If it is not, see the `resourcecode` package vignette for details
# on installing the required data package.
if (requireNamespace("resourcecodedata", quietly = TRUE)) {
 rscd_params <- get_parameters(
  node = "134865",
  start = "1994-01-01",
  end = "1994-01-31 23:00:00",
  parameters = c("hs", "tp", "cge", "t01", "dp", "dir")
)
spec <- resourcecodedata::rscd_2d_spectra
param_calc <- compute_sea_state_2d_spectrum(spec)
oldpar <- par(mfcol = c(2, 2))
plot(param_calc$time, param_calc$hs, type = "l", xlab = "Time", ylab = "Hs (m)")
lines(rscd_params$time, rscd_params$hs, col = "red")
plot(param_calc$time, param_calc$cge, type = "l", xlab = "Time", ylab = "CgE (kW/m)")
lines(rscd_params$time, rscd_params$cge, col = "red")
plot(param_calc$time, param_calc$tp, type = "l", xlab = "Time", ylab = "Tp (s)")
lines(rscd_params$time, rscd_params$tp, col = "red")
plot(param_calc$time, param_calc$dp, type = "l", xlab = "Time", ylab = "Dp (°)")
lines(rscd_params$time, rscd_params$dp, col = "red")
par(oldpar)
}

Converts a 2D spectrum time series to a 1D spectrum

Description

Converts a 2D spectrum time series to a 1D spectrum

Usage

convert_spectrum_2d1d(spec, ...)

Arguments

spec

a structure with the needed fields, as an output from 'get_2Dspectrum' for example

...

unused yet

Value

a structure comparable to 'get_1Dspectrum'.

Examples

# Ensure that data package is available before running the example.
#  If it is not, see the `resourcecode` package vignette for details
# on installing the required data package.
if (requireNamespace("resourcecodedata", quietly = TRUE)) {
spec <- resourcecodedata::rscd_2d_spectra
spec1D_RSCD <- resourcecodedata::rscd_1d_spectra
spec1D <- convert_spectrum_2d1d(spec)
# Check the differences, should be low
max(abs(spec1D_RSCD$ef - spec1D$ef))

# Plot the different spectrum
plot(spec1D$freq, spec1D$ef[, 1], type = "l", log = "xy")
lines(spec1D_RSCD$freq, spec1D_RSCD$ef[, 1], col = "red")

# Images
lims <- c(0, 360)
r <- as.POSIXct(round(range(spec1D$forcings$time), "hours"))
oldpar <- par(mfcol = c(2, 1))
image(spec1D$forcings$time, spec1D$freq, t(spec1D$th1m),
  zlim = lims,
  xlab = "Time",
  ylab = "Freq (Hz)",
  xaxt = "n",
  main = "Directionnal spreading"
)
axis.POSIXct(1, spec1D$forcings$time,
  at = seq(r[1], r[2], by = "week"),
  format = "%Y-%m-%d",
  las = 2
)
image(spec1D_RSCD$forcings$time, spec1D_RSCD$freq, t(spec1D_RSCD$th1m),
  zlim = lims,
  xlab = "Time",
  ylab = "Freq (Hz)",
  xaxt = "n"
)
axis.POSIXct(1, spec1D$forcings$time,
  at = seq(r[1], r[2], by = "week"),
  format = "%Y-%m-%d",
  las = 2
)
par(oldpar)
}

Compute the dispersion relation of waves Find k s.t. (2.pi.f)^2 = g.k.tanh(k.d)

Description

Compute the dispersion relation of waves Find k s.t. (2.pi.f)^2 = g.k.tanh(k.d)

Usage

dispersion(frequencies, depth, iter_max = 200, tol = 1e-06)

Arguments

frequencies

frequency vector

depth

depth (m)

iter_max

maximum number of iterations in the solver

tol

tolerance for termination.

Value

the wave numbers (same size as frequencies)

Examples

freq <- seq(from = 0, to = 1, length.out = 100)
k1 <- dispersion(freq, depth = 1)
k10 <- dispersion(freq, depth = 10)
kInf <- dispersion(freq, depth = Inf)
plot(freq, k1, type = "l")
lines(freq, k10, col = "red")
lines(freq, kInf, col = "green")

Fast implementation of pracma::trapz from the Armadillo C++ library

Description

Compute the area of a multivariate function with (matrix) values Y at the points x.

Usage

fastTrapz(x, Y, dim = 1L)

Arguments

x

x-coordinates of points on the x-axis (vector)

Y

y-coordinates of function values (matrix)

dim

an integer giving the subscripts which the function will be applied over. 1 indicates rows, 2 indicates columns

Value

a vector with one dimension less than Y

Examples

x = 1:10
Y = sin(pi/10*matrix(1:10,ncol=10,nrow=10))
fastTrapz(x*pi/10,Y,2)

Download the 1D spectrum data from IFREMER ftp

Description

Download the 1D spectrum data from IFREMER ftp

Usage

get_1d_spectrum(point, start = "1994-01-01", end = "1994-02-28")

Arguments

point

the location name (string) requested. Alternatively, the node number. The consistency is checked internally.

start

the starting date (as a string). The consistency is checked internally.

end

the ending date as a string

Value

A list with 12 elements:

longitude

Longitude

latitude

Latitude

frequency1

Lower frequency

frequency2

Upper frequency

ef

Surface elevation variance spectral density

th1m

Mean direction from first spectral moment

th2m

Mean direction from second spectral moment

sth1m

Mean directional spreading from first spectral moment

sth2m

Mean directional spreading from second spectral moment

freq

Central frequency

forcings

A data.frame with 14 variables:

time

Time

dpt

Depth, positive downward

wnd

Wind intensity, at 10m above sea level

wnddir

Wind direction, comes from

cur

Current intensity, at the surface

curdir

Current direction, going to

hs

Significant wave height

fp

Peak wave frequency

f02

Mean wave frequency

f0m1

Mean wave frequency at spectral moment minus one

th1p

Mean wave direction at spectral peak

sth1p

Directional spreading at spectral peak

dir

Mean wave direction

spr

Mean directional spreading

station

Station name

Examples


spec1D <- get_1d_spectrum("SEMREVO", start = "1994-01-01", end = "1994-02-28")
r <- as.POSIXct(round(range(spec1D$forcings$time), "month"))
image(spec1D$forcings$time, spec1D$freq, t(spec1D$ef),
  xaxt = "n", xlab = "Time",
  ylab = "Frequency (Hz)"
)
axis.POSIXct(1, spec1D$forcings$time,
  at = seq(r[1], r[2], by = "week"),
  format = "%Y-%m-%d", las = 2
)

Download the 2D spectrum data from IFREMER ftp

Description

Download the 2D spectrum data from IFREMER ftp

Usage

get_2d_spectrum(point, start = "1994-01-01", end = "1994-02-28")

Arguments

point

the location name (string) requested. Alternatively, the node number. The consistency is checked internally.

start

the starting date (as a string). The consistency is checked internally.

end

the ending date as a string

Value

A list with 9 elements:

longitude

Longitude

latitude

Latitude

frequency1

Lower frequency

frequency2

Upper frequency

ef

Surface elevation variance spectral density

th1m

Mean direction from first spectral moment

th2m

Mean direction from second spectral moment

sth1m

Mean directional spreading from first spectral moment

sth2m

Mean directional spreading from second spectral moment

freq

Central frequency

dir

Directionnal bins

forcings

A data.frame with 6 variables:

time

Time

dpt

Depth, positive downward

wnd

Wind intensity, at 10m above sea level

wnddir

Wind direction, comes from

cur

Current intensity, at the surface

curdir

Current direction, going to

station

Station name

Examples


spec2D <- get_2d_spectrum("SEMREVO", start = "1994-01-01", end = "1994-02-28")
image(spec2D$dir, spec2D$freq, spec2D$efth[, , 1],
  xlab = "Direction (°)",
  ylab = "Frequency (Hz"
)

Download time series of sea-state parameters from RESOURCECODE database

Description

Download time series of sea-state parameters from RESOURCECODE database

Usage

get_parameters(
  parameters = "hs",
  node = 42,
  start = as.POSIXct("1994-01-01 00:00:00", tz = "UTC"),
  end = as.POSIXct("1994-12-31 23:00:00", tz = "UTC")
)

Arguments

parameters

character vector of sea-state parameters

node

single integer with the node to get

start

starting date (as integer, character or posixct)

end

ending date (as integer, character or posixct)

Value

a tibble with N-rows and length(parameters) columns.

Examples


      ts <- get_parameters(parameters = c("hs", "tp"), node = 42)
      plot(ts$time,ts$hs,type='l')

JONWSAP spectrum

Description

Creates a JONWSAP density spectrum (one-sided), defined by its integral parameters.

Usage

jonswap(hs = 5, tp = 15, fmax = rscd_freq, df = NULL, gam = 3.3)

Arguments

hs

Hs (default: 5m)

tp

Period (default: 10s)

fmax

higher frequency of the spectrum or vector of frequencies (default to resourcecode frequency vector)

df

frequency step (unused if fmax=vector of frequencies)

gam

peak enhancement factor (default: 3.3)

Details

Reference :

Value

Density spectrum with corresponding parameters

Examples

S1 <- jonswap(tp = 15)
S2 <- jonswap(tp = 15, fmax = 0.95, df = 0.003)
plot(S1, type = "l", ylim = c(0, 72))
lines(S2, col = "red")
abline(v = 1 / 15)

Plot a wave density 2D spectrum

Description

Plot a wave density 2D spectrum

Usage

plot_2d_specta(
  spec,
  time = 1L,
  normalize = TRUE,
  trim = 0.01,
  cut_off = 0.4,
  ...
)

Arguments

spec

the spectral data, as an output from get_2Dspectrum

time

the time to plot. Either an integer or the date.

normalize

Should the spectrum be normalized to have maimum 1 before ploting

trim

removes the values of the spectral density lower than this value

cut_off

cut-off frequency above which the spectrum is not plotted

...

currently unused

Value

a ggplot object

Examples


    spec <-  get_2d_spectrum("SEMREVO", start = "1994-01-01", end = "1994-01-31")
    plot_2d_specta(spec, 1)

Resourcecode directional bins

Description

(equivalent to a directional resolution of 10°;

Usage

rscd_dir

Format

rscd_dir

An array of length 36 with the directionnal bins

Source

User Manual of the RESOURCECODE database https://archimer.ifremer.fr/doc/00751/86306/

Resourcecode frequency vector of 1D and 2D spectra

Description

The wave spectrum discretization considers 36 frequencies, starting from 0.0339 Hz up to 0.9526 Hz with a frequency increment factor of 1.1

Usage

rscd_freq

Format

rscd_freq

An array 36 elements with the frequencies values

Source

User Manual of the RESOURCECODE database https://archimer.ifremer.fr/doc/00751/86306/

Create a map of the provided variable on the RESOURCECODE field grid

Description

Create a map of the provided variable on the RESOURCECODE field grid

Usage

rscd_mapplot(
  z,
  name = "Depth (m)",
  zlim = NULL,
  palette = "YlOrRd",
  direction = 1,
  transform = "identity"
)

Arguments

z

the data ro plot: a vector of the same size as the grid (328,030 rows).

name

name of the variable plored, to be included in the legend.

zlim

limits of the scale. See continuous_scale for details.

palette

If a string, will use that named palette. See scale_colour_brewer for other options.

direction

Sets the order of colours in the scale. See scale_colour_brewer for details.

transform

Transformation to apply to the color scale. See continuous_scale for details.

Value

a ggplot2 object

Examples

# Ensure that data package is available before running the example.
# If it is not, see the `resourcecode` package vignette for details
# on installing the required data package.
if (requireNamespace("resourcecodedata", quietly = TRUE)) {
rscd_mapplot(resourcecodedata::rscd_field$depth)
}

Vector conversion

Description

Converts wind or current zonal and meridional velocity components to magnitude and direction according to meteorological convention.

Usage

zmcomp2metconv(u, v = NULL, names = c("wspd", "wdir"))

Arguments

u

zonal velocity (1D vector) or matrix with zonal and meridional velocity (Nx2 matrix)

v

meridional velocity (1D vector)

names

names to construct the resulting data.frame

Value

a Nx2 data.frame with the norm and direction (meteorological convention)

Examples

u <- matrix(rnorm(200), nrow = 100, ncol = 2)
vdir <- zmcomp2metconv(u)