retrieve_data: Retrieve hourly observed or predicted water level from the...
In ccb60/SLRSIM: Tools to Analyse Sea Level Rise

Description Usage Arguments Details Value

This function encapsulates calling the NOAA API to assemble a data frame and optionally a CSV file containing historic observed water levels or predicted water levels for a NOAA water level station.

retrieve_data(
  .station,
  .first_yr,
  .last_yr,
  .which = c("observed", "predicted"),
  .datum = c("MSL", "MTL", "MHW", "MHHW", "MLLW", "MLW", "NAVD", "STND"),
  .units = c("metric", "english"),
  .timefmt = c("gmt", "lst", "lst_ldt"),
  .tz = "UTC"
)

`.station`	Numeric or Character. The code that uniquely identifies a NOAA water level station.
`.first_yr`	Integer. First year from which to retrieve data.
`.last_yr`	Integer. Last year from which to retrieve data.
`.which`	'observed' or 'predicted'
`.datum`	Character string, from a limited list of options. Specifies the vertical datum used for the returned data. "STND" is a station-specific datum anticipated to be below all observed or predicted water levels, so al lwater levels wil lbe positive numbers. "NAVD" is the National Vertical Datum, useful for relating tides to ground elevations from survey or LIDAR. The other choices are standard tidal datums.
`.units`	"metric" or "english". The default is "metric".
`.timefmt`	'gmt', 'lst', or 'lst_ldt'. How would you like the time coordinate defined? Choices are for greenwich mean time (also known as UTC, although that abbreviation does not work here), local standard time (with no adjustments for daylight savings time), or local clock time, which can be confusing, since the data returned is a string (not an internal `POSIXct` or `POSIXlt` object). Interpretting the data correctly requires care specifying the timezone.
`.tz`	An R timezone specification. Used only for converting text-based times deliverd from the API to POSIXct objects. Defaults to 'UTC', for consistency with the default `.timefmt = 'gmt'`. For local standard time, as specified via `.timefmt = 'lst'`, the easiest way is to specify an offset from UTC. For example, use 'Etc/GMT+5' for the U.S. East Coast. For `.timefmt = 'lst_ldt'` you will need to figure out how to define your local clock time as a time zone. For the U.S East Coast, `.tz = "America/New_York"` works. See `?timezone` for more information.

NOAA publishes coastal water level data for hundreds of water level monitoring stations through an API. The API restricts individual requests for high frequency data to relatively short time periods (generally one month for six minute data, and one year for hourly data). As a result, one needs to marshal repeated API calls to assemble a longer-term record. This function encapsulates the logic to assemble a longer record, by breaking a longer period of time into yearly blocks, and reassembling into a single data frame.

The interface here asks the user to specify only the first and last years of the desired data. This is simpler than specifying an exact first and last date, although it may sometimes return more data than really desired.

A dataframe with two columns: "datetime" and either "water_level" (for observed values) or "predicted" (for predicted tides).

ccb60/SLRSIM documentation built on Jan. 21, 2022, 1:31 a.m.