Download tide-gauge data

dod.tideGauge() downloads tide-gauge data from either Canadian (CHS) or American (NOAA) tide gauges.

Usage

dod.tideGauge(
  ID = NULL,
  variable = "water_level",
  agency = "CHS",
  start = NULL,
  end = NULL,
  resolution = NULL,
  file = NULL,
  destdir = ".",
  age = 0,
  quiet = FALSE,
  debug = 0
)

Arguments

ID: a character (or possibly integer) value specifying the numeric identifier of the tide gauge. For Canadian data, this is either the station number or the station name (e.g. number 491 corresponds to the "Bedford Institute" station). For American data, it is a numerical code.
variable: a character value indicating the name of the variable to be downloaded. This defaults to "water_level" for observed water level (called "wlo" on the CHS server and "water_level" on the NOAA server). Another permitted choice is "predictions" (called "wlp" by CHS and "predictions" by NOAA). In either of these two cases, time and QC are also stored alongside the variable. And there is a third case: if variable is "metadata", then the return value will a list containing information about the station, such as its code number, its official name, its datum, etc.
agency: a character value indicating the agency from which data will be sought. Use "CHS" for Canadian tide gauges (the default), or "NOAA" for American tide gauges.
start, end: POSIXt times or character values that can be converted to such times (via as.POSIXct() with tz="UTC") that indicate the time interval for the requested data. If end is not specified, then the present time is used. If start is not provided, then it is set to the present time minus 7 days. If start is a numeric value, then it is interpreted as the number of days to go back in time from the end time.
resolution: character value indicating the resolution, only used if agency="CHS". The choices are "ONE_MINUTE", "THREE_MINUTES" (the default), "FIVE_MINUTES", "FIFTEEN_MINUTES", and "SIXTY_MINUTES". The website that serves the data indicates that not all resolutions are available for all stations and/or time intervals, and that the maximum time range of a request depends on the requested resolution.
file: a character value indicating the name to be used for the downloaded data. If not provided, this is constructed as e.g. "tide_A_N_S_E_R_V.csv" where A is the value of the agency argument, N is the station ID number, S and E are the start and end dates written in 8-digit format (i.e. sans the "-" characters), R is the resolution in minutes, and V is the variable name.
destdir: a character value indicating the directory in which to store downloaded files.
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.tideGauge() returns a list, if value is "metadata" and agency is "CHS"; otherwise it returns a file name (with full path included). For the CHS case this is a constructed filename, since the CHS server provides data, not files. For the NOAA case, it is a downloaded file.

Details

Downloads are done from for either the Canadian Hydrographic Service (CHS) or from the American National Oceanographic and Atmospheric Agency (NOAA), respectively (see References 1 and 2). The resultant data are saved in either constructed filenames, or filenames provided by the user; in either case, if a recent file already exists with the indicated name, then no data are downloaded. For NOAA files, water level and predictions are provided on the same time sequence, but for CHS files, this is not the case, e.g. predictions (in the author's tests) are on 15 minute intervals, starting at an hour marker, but observations may be at a variety of times, depending start and end. Therefore, numerical comparision with CHS data will require interpolation (see ‘Examples’).

References

Author

Dan Kelley

Examples

# Download and plot tide-guage data for Halifax Harbour
if (interactive()) { # sidestep a pkgdown::build_site() error
    # NOTE: data file is removed at end, to pass CRAN checks
    library(dod)
    library(oce)
    destdir <- tempdir()
    ofile <- dod.tideGauge(491, destdir = destdir)
    pfile <- dod.tideGauge(491, "predictions", destdir = destdir)
    O <- read.csv(ofile)
    O$time <- as.POSIXct(O$Date.Time, "%Y-%m-%d %H:%M:%S", tz = "UTC")
    P <- read.csv(pfile)
    P$time <- as.POSIXct(P$Date.Time, "%Y-%m-%d %H:%M:%S", tz = "UTC")
    # Top panel: observation (black) and prediction (gray)
    par(mfrow = c(2, 1))
    oce.plot.ts(O$time, O$Water.Level, ylab = "Water Level [m]", xaxs = "i")
    lines(P$time, P$Predictions, col = "gray", type = "l")
    # Bottom panel: misfit. Note the interpolation to observation time.
    misfit <- O$Water.Level - approx(P$time, P$Predictions, O$time)$y
    oce.plot.ts(O$time, misfit, ylab = "Deviation [m]", xaxs = "i")
    unlink(destdir, recursive = TRUE)
}