Test Spatial Propagation of Rogue Wave Events

Tests whether rogue wave events at one station are followed by rogue events at another station within a time window consistent with wave propagation. Uses a permutation test: the null hypothesis is that rogue events at the second station are uniformly distributed over time (no clustering with the first station).

For each station pair, the theoretical propagation lag is estimated as distance_km / propagation_speed_kmh (default 30 km/h for deep-water swell group velocity). Co-occurrence is counted when a station-2 rogue event falls within [lag - tolerance, lag + tolerance] hours of a station-1 event.

Usage

test_rogue_propagation(
  data,
  rogue_threshold = 2,
  min_wave_height = 2,
  station_pairs = NULL,
  propagation_speed_kmh = 30,
  n_permutations = 500,
  station_info = NULL
)

Arguments

data

Data frame with columns: time (POSIXct), station_id (character), wave_height (numeric), hmax (numeric).

rogue_threshold

Hmax/Hs ratio threshold for rogue classification (default: 2.0).

min_wave_height

Minimum significant wave height in metres for a qualifying observation (default: 2.0).

station_pairs

Optional list of character vectors, each of length 2, specifying directed pairs c(source, receiver). If NULL, uses default focus pairs: M6->M2, M6->M3, M6->M5, M2->M3, M3->M5.

propagation_speed_kmh

Assumed deep-water group velocity in km/h (default: 30).

n_permutations

Number of permutations for the test (default: 500).

station_info

Optional data frame from get_station_info(). If NULL, uses the default 5-station network.

Value

List with:

h3_table

Data frame with columns: station1, station2, distance_km, theoretical_lag_hrs, n_rogue_s1, n_rogue_s2, co_occurrence_count, co_occurrence_rate, marginal_rate, perm_mean_rate, p_value, h3_significant (logical), h3_verdict.

rogue_events

Data frame of all detected rogue wave events.

n_rogue_total

Total number of rogue events across all stations.

Examples

if (FALSE) { # \dontrun{
con <- connect_duckdb()
data <- query_buoy_data(con, variables = c("time", "station_id", "wave_height", "hmax"))
result <- test_rogue_propagation(data)
result$h3_table
DBI::dbDisconnect(con)
} # }