Fit a Max-Stable Process to Station Annual Maxima

Fits a Brown-Resnick max-stable process model to annual block maxima of wave heights across multiple stations. Margins are first transformed to unit Frechet using the empirical CDF. If the Brown-Resnick model fails to converge, a Schlather model (Whittle-Matern covariance) is tried as fallback.

Limitation: Max-stable models require many spatial locations (typically= 20) for reliable estimation. With only 5 buoy stations, results areillustrative and the information matrix is often singular.

Usage

fit_spatial_maxstable(
  data,
  variable = "wave_height",
  station_info = NULL,
  min_years = 5
)

Arguments

data

Data frame with columns: time (POSIXct), station_id (character), and the variable specified by variable.

variable

Variable to analyze (default: "wave_height").

station_info

Optional data frame with station metadata (from get_station_info()). Must contain station_id, lat, lon. If NULL, uses the default 5-station network.

min_years

Minimum number of complete years required across all stations (default: 5).

Value

List with:

fitted

Logical: whether a max-stable model was successfully fitted.

fit

The fitted model object (from SpatialExtremes::fitmaxstab), or NULL if fitting failed.

model_type

Character: "brown_resnick", "schlather", or NA.

parameters

Named numeric vector of fitted parameters, or NULL.

annual_maxima

Data frame of annual maxima per station (long format).

coords

Coordinate matrix (lon, lat) used for fitting.

limitation

Character string describing the illustrative nature of results with few stations.

If fitting fails entirely, fitted = FALSE and a reason field explains why.

Examples

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