Download CTD data from the GTSPP server

This function downloads CTD data from the GRSPP server at https://www.ncei.noaa.gov/data/oceans/gtspp/bestcopy/. This website is somewhat challenging to use; see ‘Details’.

Usage

dod.ctd.gtspp(
  basin,
  year,
  month,
  file = NULL,
  destdir = ".",
  index = FALSE,
  nc = NULL,
  age = 0,
  quiet = FALSE,
  debug = 0
)

Arguments

basin: character value indicating the ocean basin in which the data were acquired. This must be one of "at", "pa" or "in", for the Atlantic, Pacific and Indian basins, respectively. NB. basin is ignored if nc is #' provided, and is a full URL.
year: integer value giving the year in which the data were acquired. NB. year is ignored if nc is #' provided, and is a full URL.
month: integer or character value giving the month in which the data were acquired. If in character form, a two-digit value is required, with the first digit being "0" for early months of the year. NB. month is ignored if nc is #' provided, and is a full URL.
file: character value giving the name to be used for the downloaded file.
destdir: a character value indicating the directory in which to store downloaded files.
index: a boolean value indicating whether the index should be downloaded. This is FALSE by default. Note that nc is ignored if index is TRUE. NB. index is ignored if nc is #' provided, and is a full URL.
nc: character value either naming a netcdf file in a directory inferred from basin, year and month, or a URL that leads directly to such a file. The latter case is recognized by nc starting with "http". Note that index is ignored if nc is provided. See “Examples”.
age: a numerical value indicating a time interval, in days. If the file to be downloaded from the server already exists locally, and was created less than age days in the past, it will not be downloaded again. Setting age=0 forces a download, so that existing files will always be updated. By contrast, setting age to a negative number prevents the updating of files that already exist locally, regardless of their age.
quiet: a logical value, passed to curl::curl_download(), which does the downloading. If this is TRUE (the default), then the work is done quietly. Until version version 0.1.12, this parameter was called silent, but it was renamed to match the corresponding argument in curl::curl_download(), which may be more familiar to users.
debug: an integer value indicating the level of debugging. If this exceeds 0, then some debugging messages will be printed. This value is passed down to related functions, but with 1 subtracted for each pass.

Value

dod.ctd.gtspp() returns the local name of the downloaded file.

Details

The .zip files provided on the NCEI server are not readible on a macOS machine, which might also indicate problems on other machines. Therefore, inventory files are read in .txt format, which increases download and read time by over an order of magnitude.

Author

Dan Kelley

Examples

if (interactive()) { # pkgdown::build_site() cannot handle downloads
    # Two examples are shown here.  The first specifies the remote file by a full
    # URL, and the second infers such a URL from a subset of an index file. Since
    # downloading an index is slow, a common approach is to combine the approaches,
    # re-downloading the index perhaps only once a week to gain access to the most
    # recent data.

    library(dod)
    library(oce)
    library(ncdf4)

    # First, define a function to read, summarize and plot CTD
    # data stored in a netcdf file.
    process <- function(datafile) {
        nc <- nc_open(datafile)
        S <- ncvar_get(nc, "salinity")
        T <- ncvar_get(nc, "temperature")
        z <- ncvar_get(nc, "z")
        lon <- ncvar_get(nc, "longitude")
        lat <- ncvar_get(nc, "latitude")
        p <- swPressure(z, lat)
        ctd <- as.ctd(S, T, p, longitude = lon, latitude = lat)
        summary(ctd)
        plot(ctd)
    }

    # Example A: get a data file from a known URL.
    url <- paste0(
        "https://www.ncei.noaa.gov/data/oceans/",
        "gtspp/bestcopy/atlantic/2022/01/gtspp_47477452_te_111.nc"
    )
    dataFileA <- dod.ctd.gtspp(nc = url)
    # above is equivalent to dod.ctd("at", 2022, 01, nc="gtspp_47477452_te_111.nc")
    process(dataFileA)

    # Example B: get an index, find a file of interest, and then get it
    # Get an index file for Atlantic Ocean observations in January 2022.
    ## # EG https://www.ncei.noaa.gov/data/oceans/gtspp/bestcopy/inventory/at198501_gtsppinv.zip
    indexFile <- dod.ctd.gtspp(basin = "at", year = 2022, month = 1, index = TRUE)
    col.names <- strsplit(gsub("#", "", readLines(indexFile, n = 1L)), ",")[[1]]
    index <- read.csv(indexFile, skip = 1L, col.names = col.names, header = FALSE)
    # Plot sampling locations near Halifax, Nova Scotia
    if (requireNamespace("ocedata", quietly = TRUE)) {
        data(coastlineWorldFine, package = "ocedata")
        hlon <- -63.5728
        hlat <- 44.6476
        plot(coastlineWorldFine, clongitude = hlon, clatitude = hlat, span = 2000)
        points(index$longitude, index$latitude, col = 4)
        # Focus on the point nearest Halifax
        # https://www.ncei.noaa.gov/data/oceans/gtspp/bestcopy/atlantic/\
        # 2022/01/gtspp_47477452_te_111.nc
        dist <- geodDist(index$longitude, index$latitude, hlon, hlat)
        focus <- index[which.min(dist), ]
        dataFile <- dod.ctd.gtspp(nc = focus$data_URL)
        process(dataFile)
    }
}