R: Get a Tidal Prediction From a WebTide Database

webtide {oce}

R Documentation

Get a Tidal Prediction From a WebTide Database

Description

Get a tidal prediction from a WebTide database. This only works if the standalone WebTide application is installed, and if it is installed in a standard location. The details of installation are not within the oce purview.

Usage

webtide(
  action = c("map", "predict"),
  longitude,
  latitude,
  node,
  time,
  basedir = getOption("webtide"),
  region = "nwatl",
  plot = TRUE,
  tformat,
  debug = getOption("oceDebug"),
  ...
)

Arguments

`action`	An indication of the action, either `action="map"` to draw a map or `action="predict"` to get a prediction; see “Details”.
`longitude`, `latitude`	optional location at which prediction is required (ignored if `node` is given).
`node`	optional integer relating to a node in the database. If `node` is given, then neither `latitude` nor `longitude` may be given. If `node` is positive, then specifies indicates the node. If it is negative, `locator()` is called so that the user can click (once) on the map, after which the node is displayed on the map.
`time`	a vector of times (in the UTC timezone) at which prediction is to be made. If not supplied, this will be the week starting at the present time, computed with `presentTime()`, with a 15 minute increment.
`basedir`	directory containing the `WebTide` application.
`region`	database region, given as a directory name in the WebTide directory. For example, `h3o` is for Halifax Harbour, `nwatl` is for the northwest Atlantic, and `sshelf` is for the Scotian Shelf and Gulf of Maine.
`plot`	boolean indicating whether to plot.
`tformat`	optional argument passed to `oce.plot.ts()`, for plot types that call that function. (See `strptime()` for the format used.)
`debug`	an integer specifying whether debugging information is to be printed during the processing. This is a general parameter that is used by many `oce` functions. Generally, setting `debug=0` turns off the printing, while higher values suggest that more information be printed. If one function calls another, it usually reduces the value of `debug` first, so that a user can often obtain deeper debugging by specifying higher `debug` values.
`...`	optional arguments passed to plotting functions. A common example is to set `xlim` and `ylim`, to focus a map region.

Details

There are two methods of using this function. Case 1: action="map". In this case, if plot is FALSE, a list is returned, containing all the nodes in the selected database, along with all the latitudes and longitudes. This value is also returned (silently) if plot is true, but in that case, a plot is drawn to indicate the node locations. If latitude and longitude are given, then the node nearest that spot is indicated on the map; otherwise, if node is given, then the location of that node is indicated. There is also a special case: if node is negative and interactive() is TRUE, then locator() is called, and the node nearest the spot where the user clicks the mouse is indicated in the plot and in the return value.

Case 2: action="predict". If plot is FALSE, then a list is returned, indicating time, predicted elevation, velocity components u and v, node number, the name of the basedir, and the region. If plot is TRUE, this list is returned silently, and time-series plots are drawn for elevation, u, and v.

Naturally, webtide will not work unless WebTide has been installed on the computer.

Value

The value depends on action:

If action="map" the return value is a list containing the index of the nearest node, along with the latitude and longitude of that node. If plot is FALSE, this value is returned invisibly.
If action="predict", the return value is a list containing a vector of times (time), as well as vectors of the predicted elevation in metres and the predicted horizontal components of velocity, u and v, along with the node number, and the basedir and region as supplied to this function. If plot is FALSE, this value is returned invisibly.

Caution

WebTide is not an open-source application, so the present function was designed based on little more than guesses about the WebTide file structure. Users should be on the lookout for odd results.

Sample of Usage

# needs WebTide at the system level
library(oce)
# 1. prediction at Halifax NS
longitude <- -63.57
latitude <- 44.65
prediction <- webtide("predict", longitude=longitude, latitude=latitude)
mtext(paste0("prediction at ", latitude, "N and ", longitude, "E"), line=0.75, side=3)
# 2. map
webtide(lon=-63.57,lat=44.65,xlim=c(-64,-63),ylim=c(43.0,46))

Author(s)

Dan Kelley

Source

The WebTide software may be downloaded for free at the Department of Fisheries and Oceans (Canada) website at ⁠http://www.bio.gc.ca/science/research-recherche/ocean/webtide/index-en.php⁠ (checked February 2016 and May 2017).