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 `node`s in the selected database, along with all the `latitude`s and `longitude`s. 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.

### 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).

### See Also

Other things related to tides: `[[,tidem-method`, `[[<-,tidem-method`, `as.tidem()`, `plot,tidem-method`, `predict.tidem()`, `summary,tidem-method`, `tidalCurrent`, `tidedata`, `tidem-class`, `tidemAstron()`, `tidemVuf()`, `tidem`

### Examples

    ## Not run:
    ## 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(sprintf("prediction at %fN %fE", latitude, longitude), line=0.75, side=3)
    ## 2. map
    webtide(lon=-63.57,lat=44.65,xlim=c(-64,-63),ylim=c(43.0,46))

    ## End(Not run)

[Package oce version 1.7-2 Index]