R/shortcuts-get-data-hotssea.R

In pbs-assess/PACea: An R package of Pacific ecosystem information to help facilitate an ecosystem approach to fisheries management

#' Load or download the HOTSSea model output
#'
#' Loading and/or downloading model output from HOTSsea physical hindcast of the
#' Salish Sea model. Loads it into your R environment from your local cache, and if
#' it has not been previously downloaded will first download it from Zenodo
#' into your local cache.
#' To download all HOTSsea model output in one go (recommended), first use the
#'   function [hotssea_all_variables()]. See the hotssea vignette for further explanations.
#'
#' The Hindcast of the Salish Sea (HOTSSea) is a physical ocean model that
#' recreates conditions throughout the Salish Sea from 1980 to 2018, filling in
#' the gaps in patchy measurements Oldford et al., (in review). The model
#' predicts physical ocean properties with sufficient accuracy to be useful for
#' a variety of applications. It corroborates observed ocean temperature trends
#' and can examine areas with few observations. Results indicate that some
#' seasons and areas are warming faster than others. HOTSSea was developed using
#' the Nucleus for European Modelling of the Ocean (NEMO)
#' engine, and temperature and salinty outputs are included in pacea (from version
#'  1 of HOTSSea).
#'
#' The HOTSSea outputs in pacea are adapted from results
#' provided by Greig Oldford (Fisheries and Oceans Canada). For model details see
#' Oldford et al., (in review), which should
#' be read and cited if you use the results, and Greig and Andrew Edwards
#' should be consulted for any clarifications and uses of the results.
#'
#' The following 40 functions serve to download specific individual ocean
#' calculations related to temperature or salinity from the HOTSSea model. If a
#' variable has already been downloaded, the function will load data from the
#' `hotssea` subfolder in the user's
#' `pacea_cache()` folder into user's local R environment. Each file is around
#' 3-9 Mb, but should not take long to download.
##'
#' The 40 variables available are desribed below as their respective
#' functions. The variables are listed in the object `hotssea_data`.
#' The variables are stored on Zenodo, with [get_zenodo_data()]
#' automatically taking care of the DOI address for the one-time download.
#'#'
#' #'
#' \describe{
#'   \code{hotssea_*depth*_temperature()_*statistic*} Temperature in oC\cr
#'   \code{hotssea_*depth*_salinity()} Salinity in PSU\cr
#' }
#'
#' NOTE:\cr
#' \code{*depth*} must be replaced by one of the following depth categories:
#'
#' \describe{
#'   \code{surface}{sea surface, the top model cell at that location}\cr
#'   \code{avg0to30m}{depth-integrated average over 0-30 m}\cr
#'   \code{avg30to150m}{depth-integrated average over 30-150 m}\cr
#'   \code{150toBot} {depth-integrated from 150 m to the bottom cell}\cr
#'   \code{bottom}{sea bottom, the bottom model cell at that location}
#' }
#'
#' #' \code{*statistic*} must be replaced by one of the following statistics:
#'
#' \describe{
#'   \code{min}{minimum daily mean over the month}\cr
#'   \code{mean}{mean daily mean over the month}\cr
#'   \code{max}{maximum daily mean over the month}\cr
#'   \code{std} {standard deviation of the daily means for the month}\cr
#' }
#'
#' The five permissable depth values for four types of statistics for both
#' temperature and salinity yield the 40 different combinations.
#' For example, `hotssea_avg0to30m_temperature_max()` refers to the mean (over
#' the top 30 m) of each modelled depths' maximum (over the month) daily mean
#' temperature. See the hotssea vignette for explicit explanation of these
#' calculations; in particular the `*statistic* is calculated for all cells
#' before the depth averaging is performed.
#'
#' Explicit details of the vertical resolution of the original HOTSSea model
#' results are as follows (also see Oldford et al., in review). The vertical
#' grid for HOTSSea v1 is divided into 40 vertical levels that are gradually
#' stretched to achieve higher resolution at the surface, ranging from 1 m
#' vertical resolution in the upper 10 m to approximately 27 m widths at the
#' deepest level (~420 m). When time-dynamic variation is ignored, the 'surface'
#' '0-4 m' depth range is more precisely the 0-4.0000467 m depth range, the
#' '0-30 m' depth range is more precisely the 0-31.101 m depth range, and the
#' '0-150 m' depth range is more precisely the 0-147.089 m. Although depth
#' interpolation schemes may be used to extract model outputs from precise
#' depths, these schemes introduce biases, are potentially computationally
#' costly, and are unlikely to change the extracted values enough to be worth it
#' when working at monthly time scales. In addition, the thickness of each layer
#' is proportionally scaled at each time-step as sea surface height changes
#' using a nonlinear free-surface scheme referred to as the 'variable volume
#' option' in the NEMO model framework. The datum heights of model outputs
#' therefore vary dynamically in space and time because the NEMO model vertical
#' depth level widths vary dynamically with sea surface height. For example, if
#' sea surface height varies on the order of seconds or minutes due to, say,
#' wind-driven wave action, then hourly, daily, and monthly model depths are
#' time-integrated means for a given grid cells. The 'variable volume option' is
#' another reason why a simpler approach than depth interpolation was used when
#' extracting and wrangling HOTSSea v1 model outputs.

#' 'Surface' is defined in the monthly mean HOTSSea v1 outputs as 0 to ~4 m
#' (rather than, say 0 to ~1 m) because model biases are most pronounced at the
#' shallowest depth (0 to ~1 m). On the monthly scale, conditions throughout the
#' model domain are generally similar between 0.5 m and 4 m (mean
#' depth-integrated differences of approximately < 0.25 Celcius and 0.2 PSU) and
#' biases > 2 m are substantially lower. Vertical averaging of model results
#' from 0 to 4 m was therefore chosen based on analyses of spatial-temporal
#' model performance to lessen the impact of model error - more in-depth
#' analyses are given in Oldford et al. (in review).
#'
#' @format A simple features dataframe.
#'
#' @param update Logical. Would you like to check for a newer version of the layer?
#' @param ask Logical. Should the user be asked before downloading the data to local cache? Defaults to the value of interactive().
#' @param force Logical. Should download of data be forced? Overrides `ask` argument if TRUE.
#' @param version character Version number of data as saved on Zenodo. Only
#'   currently works for "01" as that's all that is currently available.
#' @param cache_subfolder character. Subfolder to put or look for the objects;
#'   defaults to `hotssea` and it is best to stick with this. The objects will
#'   be put in your `paste0(pacea::pacea_cache(), cache_subfolder)` directory.
#'
#' @return `sf` data object requested.
#' @export
#'
#' @source Oldford, G.L., Jarníková, T., Christensen, V., and Dunphy, M. (in review).
#' HOTSSea v1: a NEMO-based physical Hindcast of the Salish Sea (1980–2018)
#' supporting ecosystem model development. Preprint. https://doi.org/10.5194/gmd-2024-58
#'
#' @examples
#' \dontrun{
#' h <- hotssea_bottom_salinity_min()
#' plot(h)
#' }
hotssea_surface_salinity_min <- function(update = FALSE, ask = interactive(),
                                         force = FALSE, version = "01",
                                         cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_surface_salinity_min", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_surface_salinity_mean <- function(update = FALSE, ask = interactive(),
                                          force = FALSE, version = "01",
                                          cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_surface_salinity_mean", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_surface_salinity_max <- function(update = FALSE, ask = interactive(),
                                         force = FALSE, version = "01",
                                         cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_surface_salinity_max", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_surface_salinity_std <- function(update = FALSE, ask = interactive(),
                                         force = FALSE, version = "01",
                                         cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_surface_salinity_std", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_surface_temperature_min <- function(update = FALSE, ask = interactive(),
                                            force = FALSE, version = "01",
                                            cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_surface_temperature_min", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_surface_temperature_mean <- function(update = FALSE, ask = interactive(),
                                             force = FALSE, version = "01",
                                             cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_surface_temperature_mean", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_surface_temperature_max <- function(update = FALSE, ask = interactive(),
                                            force = FALSE, version = "01",
                                            cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_surface_temperature_max", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_surface_temperature_std <- function(update = FALSE, ask = interactive(),
                                            force = FALSE, version = "01",
                                            cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_surface_temperature_std", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg0to30m_salinity_min <- function(update = FALSE, ask = interactive(),
                                           force = FALSE, version = "01",
                                           cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg0to30m_salinity_min", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg0to30m_salinity_mean <- function(update = FALSE, ask = interactive(),
                                            force = FALSE, version = "01",
                                            cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg0to30m_salinity_mean", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg0to30m_salinity_max <- function(update = FALSE, ask = interactive(),
                                           force = FALSE, version = "01",
                                           cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg0to30m_salinity_max", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg0to30m_salinity_std <- function(update = FALSE, ask = interactive(),
                                           force = FALSE, version = "01",
                                           cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg0to30m_salinity_std", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg0to30m_temperature_min <- function(update = FALSE, ask = interactive(),
                                              force = FALSE, version = "01",
                                              cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg0to30m_temperature_min", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg0to30m_temperature_mean <- function(update = FALSE, ask = interactive(),
                                               force = FALSE, version = "01",
                                               cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg0to30m_temperature_mean", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg0to30m_temperature_max <- function(update = FALSE, ask = interactive(),
                                              force = FALSE, version = "01",
                                              cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg0to30m_temperature_max", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg0to30m_temperature_std <- function(update = FALSE, ask = interactive(),
                                              force = FALSE, version = "01",
                                              cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg0to30m_temperature_std", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg30to150m_salinity_min <- function(update = FALSE, ask = interactive(),
                                             force = FALSE, version = "01",
                                             cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg30to150m_salinity_min", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg30to150m_salinity_mean <- function(update = FALSE, ask = interactive(),
                                              force = FALSE, version = "01",
                                              cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg30to150m_salinity_mean", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg30to150m_salinity_max <- function(update = FALSE, ask = interactive(),
                                             force = FALSE, version = "01",
                                             cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg30to150m_salinity_max", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg30to150m_salinity_std <- function(update = FALSE, ask = interactive(),
                                             force = FALSE, version = "01",
                                             cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg30to150m_salinity_std", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg30to150m_temperature_min <- function(update = FALSE, ask = interactive(),
                                                force = FALSE, version = "01",
                                                cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg30to150m_temperature_min", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg30to150m_temperature_mean <- function(update = FALSE, ask = interactive(),
                                                 force = FALSE, version = "01",
                                                 cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg30to150m_temperature_mean", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg30to150m_temperature_max <- function(update = FALSE, ask = interactive(),
                                                force = FALSE, version = "01",
                                                cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg30to150m_temperature_max", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg30to150m_temperature_std <- function(update = FALSE, ask = interactive(),
                                                force = FALSE, version = "01",
                                                cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg30to150m_temperature_std", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg150toBot_salinity_min <- function(update = FALSE, ask = interactive(),
                                              force = FALSE, version = "01",
                                              cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg150toBot_salinity_min", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg150toBot_salinity_mean <- function(update = FALSE, ask = interactive(),
                                               force = FALSE, version = "01",
                                               cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg150toBot_salinity_mean", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg150toBot_salinity_max <- function(update = FALSE, ask = interactive(),
                                              force = FALSE, version = "01",
                                              cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg150toBot_salinity_max", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg150toBot_salinity_std <- function(update = FALSE, ask = interactive(),
                                              force = FALSE, version = "01",
                                              cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg150toBot_salinity_std", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg150toBot_temperature_min <- function(update = FALSE, ask = interactive(),
                                                 force = FALSE, version = "01",
                                                 cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg150toBot_temperature_min", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg150toBot_temperature_mean <- function(update = FALSE, ask = interactive(),
                                                  force = FALSE, version = "01",
                                                  cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg150toBot_temperature_mean", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg150toBot_temperature_max <- function(update = FALSE, ask = interactive(),
                                                 force = FALSE, version = "01",
                                                 cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg150toBot_temperature_max", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_avg150toBot_temperature_std <- function(update = FALSE, ask = interactive(),
                                                 force = FALSE, version = "01",
                                                 cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_avg150toBot_temperature_std", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_bottom_salinity_min <- function(update = FALSE, ask = interactive(),
                                        force = FALSE, version = "01",
                                        cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_bottom_salinity_min", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_bottom_salinity_mean <- function(update = FALSE, ask = interactive(),
                                         force = FALSE, version = "01",
                                         cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_bottom_salinity_mean", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_bottom_salinity_max <- function(update = FALSE, ask = interactive(),
                                        force = FALSE, version = "01",
                                        cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_bottom_salinity_max", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_bottom_salinity_std <- function(update = FALSE, ask = interactive(),
                                        force = FALSE, version = "01",
                                        cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_bottom_salinity_std", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_bottom_temperature_min <- function(update = FALSE, ask = interactive(),
                                           force = FALSE, version = "01",
                                           cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_bottom_temperature_min", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_bottom_temperature_mean <- function(update = FALSE, ask = interactive(),
                                            force = FALSE, version = "01",
                                            cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_bottom_temperature_mean", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_bottom_temperature_max <- function(update = FALSE, ask = interactive(),
                                           force = FALSE, version = "01",
                                           cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_bottom_temperature_max", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}

#' @rdname hotssea_surface_salinity_min
#' @export
hotssea_bottom_temperature_std <- function(update = FALSE, ask = interactive(),
                                           force = FALSE, version = "01",
                                           cache_subfolder = "hotssea"){
  get_zenodo_data("hotssea_bottom_temperature_std", update = update, ask = ask,
                  force = force, version = version, cache_subfolder = cache_subfolder)
}