Package 'PEcAn.data.water'

Title: PEcAn Functions Used for Querying Water Datasets
Description: Functions for querying databases and creating scenarios for models that take water level and flooding parameters as inputs.
Authors: Holmquist James [aut, cre] (ORCID: <https://orcid.org/0000-0003-2546-6766>)
Maintainer: Holmquist James <[email protected]>
License: BSD_3_clause + file LICENSE
Version: 0.0.0
Built: 2026-11-19 22:28:28 UTC
Source: https://github.com/PecanProject/pecan

Help Index


Tidal datum values for 125 NOAA stations

Description

Average annual datums for different types of water levels, recalculated from NOAA tide gauges using the TideHarmonics R package at average annual time steps.

Usage

annual_compiled_datums

Format

A data frame with 51482 rows and 10 columns:

Datum

Datum name, HHA=Higher High Annual, HOT=Highest Observed Tide, MSL=Mean Sea Level, LLA=Lower Low Annual, LOT=Lowest Observed Tide, HHS=Higher High Spring, HH=Higher High Daily, LH=Lower High Daily, HL=Higher Low Daily, LL=Lower Low Daily, LLS=Lower Low Spring

n_obs

Number of observations

observed

Observed water elevation in meters relative to NAVD88

n_pred

Number of predictions

predicted

Predicted water elevation in meters relative to NAVD88

risingTime

Average rising time of the flood stage (hours)

fallingTime

Average falling time of the flood stage (hours)

year

Calendar year (YYYY)

station_id

Unique numeric station identifier

station_name

Unique station name

Source

from https://github.com/Smithsonian/Tidal_Scenarios, compiled by James Holmquist


Projected sea level change under climate scenarios from IPCC Assessment Report 6

Description

Probabilistic and localized relative sea-level rise scenarios produced for NOAA tide gauges for the 6th IPCC Assesment Report by Kopp and Garner (2023). Scenarios were reprocessed by James Holmquist into long-form tables that could be more readily queried.

Usage

ar6_us_compiled_scenarios

Format

A data frame with 2,278,458 rows and 10 columns:

psmsl_id

Unique permanant service for mean sea level identifier

latitude

Gauge latitude in decimal degrees WGS84.

longitude

Gauge longitude in decimal degrees WGS84.

year

Calendar year (YYYY)

quantile

Value between 0 and 1 indicating position of the sea-level rise magnitude within the probability space of the scnenario.

sea_level_change_mm

Sea level change relative to the baseline period (1986–2005)

noaa_id

Unique NOOA numeric station identifier

noaa_name

Unique NOAA station name

scenario_name

Unique scenario name indicating a Shared Socioeconomic Pathway (ssp) or temperature limitation window (tlim). See source data for additional detail.

confidence

Indicates whether forecats are made propegating uncertainty at 'medium' or 'low' confidence

Source

Kopp, R. E., Garner, G. G., Hermans, T. H., Jha, S., Kumar, P., Reedy, A., ... & Smith, C. (2023). The Framework for Assessing Changes To Sea-level (FACTS) v1. 0: a platform for characterizing parametric and structural uncertainty in future global, relative, and extreme sea-level change. Geoscientific Model Development, 16(24), 7461-7489.

Reformatted in https://github.com/Smithsonian/Tidal_Scenarios, by James Holmquist


Find the nearest NOAA gauge to each site

Description

Finds the nearest long term NOAA gauge to each input site using sf::st_nearest_feature(), joins the corresponding gauge attributes to the site table, and calculates the straight-line distance between the site and gauge.

Usage

findNearestNoaaGauge(sites, site_lat = "latitude", site_lon = "longitude")

Arguments

sites

A data frame, tibble, or sf object containing site locations.

site_lat

Character. Name of the latitude column in sites. Default is "latitude".

site_lon

Character. Name of the longitude column in sites. Default is "longitude".

Details

sites may be data frame containing latitude and longitude columns or existing sf objects.

Distances are straight-line geographic distances. For coastal and estuarine applications, the nearest gauge by straight-line distance may not necessarily be the most hydrologically connected gauge. This also won't work outside the U.S.

Value

An data.frame object containing the original site attributes and geometry, attributes of the nearest gauge, and distance to the gauge in meters and kilometers.


Generate sea-level rise and tidal inundation scenarios

Description

Queries one or more NOAA tide gauges and generates annual sea-level and tidal inundation scenarios for each gauge.

Usage

generateFullTidalScenario(
  station_id = 9410660,
  run_hindcast = TRUE,
  run_forecast = TRUE,
  hindcast_start = 1928,
  forecast_start = 2026,
  forecast_end = 2100,
  scenario = c("ssp126", "ssp245"),
  confidence_level = "medium",
  target_quantile = c(0.25, 0.5, 0.75),
  include_lt_tidal_const = TRUE,
  datum_start_year = 1980,
  datum_end_year = 2025
)

Arguments

station_id

Vector of NOAA station identifiers.

run_hindcast

Logical. Generate historical sea-level data.

run_forecast

Logical. Generate forecast sea-level scenarios.

hindcast_start

First year of hindcast.

forecast_start

First year of forecast.

forecast_end

Final forecast year.

scenario

Character vector of AR6 scenarios.

confidence_level

Character vector of confidence levels.

target_quantile

Numeric vector of target quantiles.

include_lt_tidal_const

Include long-term tidal constituents.

datum_start_year

First year used to calculate tidal datums.

datum_end_year

Last year used to calculate tidal datums.

Value

A list containing:

  • scenario_curves: Combined scenario table for all gauges.

  • tidal_datums_summarized: Combined tidal datum table for all gauges.


Long term tidal constituents for NOAA tide gauges

Description

Harmonic constituents of long term tidal amplitude changes for NOAA tide gauges. 4.4 and 18.6 year cycles in tidal amplitude change are accounted for following formulas presented in Peng et al. (2018). Formulas are modified to fit harmonic constituents to different tidal flood and ebb types matching annual_compiled_datums.

Usage

long_term_tidal_constituents

Format

A data frame with 1000 rows and 17 columns:

station_id

Unique numeric NOAA station identifier

station_name

Unique NOAA station name

start_date

Calendar start date for observation (YYYYMMDD)

end_date

Calendar end date for observation (YYYYMMDD)

tide

Type of tide: HHA=Higher High Annual, HOT=Highest Observed Tide, MSL=Mean Sea Level, LLA=Lower Low Annual, LOT=Lowest Observed Tide, HHS=Higher High Spring, HH=Higher High Daily, LH=Lower High Daily, HL=Higher Low Daily, LL=Lower Low Daily, LLS=Lower Low Spring

mean_amp

Mean tidal amplitude for model 1 (4.4 and 18.6 year cycles accounted for)

amp18

18.6 year cycle amplitude of amplitude for model 1 (4.4 and 18.6 year cycles accounted for)

phase18

18.6 year cycle phase for model 1 (4.4 and 18.6 year cycles accounted for)

amp44

4.4 year cycle amplitude for model 1

phase44

4.4 year cycle phase for model 1

rse

Residual standard error for model 1 (4.4 and 18.6 year cycles accounted for)

r2

R-squared value for model 1 (4.4 and 18.6 year cycles accounted for)

mean_ampb

Mean tidal amplitude for model 2 (18.6 year cycle accounted for)

amp18b

18.6 year cycle amplitude of amplitude for model 2 (18.6 year cycle accounted for)

phase18b

18.6 year cycle phase for model 2 (18.6 year cycle accounted for)

rseb

Residual standard error for model 2 (18.6 year cycle accounted for)

r2b

R-squared value for model 2 (18.6 year cycle accounted for)

Source

Peng, D., Hill, E. M., Meltzner, A. J., & Switzer, A. D. (2019). Tide gauge records show that the 18.61‐year nodal tidal cycle can change high water levels by up to 30 cm. Journal of Geophysical Research: Oceans, 124(1), 736-749.

Recalculated in https://github.com/Smithsonian/Tidal_Scenarios, by James Holmquist


Locations, IDs, and available date ranges for 126 NOAA tidal stations

Description

Publically available NOAA tide gauge positional and temporal information organized into a single table.

Usage

noaa_us_gauge_info

Format

A data frame with 89 rows and 8 columns:

noaa_id

Unique numeric NOAA station identifier

startDate

Calendar start date for observation record (YYYYMMDD)

endDate

Calendar end date for observation record (YYYYMMDD)

noaa_name

Unique NOAA station name

latitude

Gauge latitude in decimal degrees WGS84

longitude

Gauge longitude in decimal degrees WGS84

state

State- or territory-level two letter abbreviation

has_NAVD88

Specifies whether NAVD88 datum is present.

Source

Queried from NOAA servers and organized in https://github.com/Smithsonian/Tidal_Scenarios, by James Holmquist