return_curve_est: Derives return curves that capture uncertainty

In rjaneUCF/MultiHazard: Tools for modeling compound events

Derives return curves that capture uncertainty

Description

Calculates return level curves using two extremal dependence models: (1) Heffernan and Tawn (2004) (hereon in HT04) and (2) Wadsworth and Tawn (2013) (hereon in WT13) as outlined in Murphy-Barltrop et al. (2023).

Usage

return_curve_est(
  data,
  q,
  rp,
  mu,
  n_sim,
  n_grad,
  n_boot,
  boot_method,
  boot_replace,
  block_length,
  boot_prop,
  decl_method_x,
  decl_method_y,
  window_length_x,
  window_length_y,
  u_x = NA,
  u_y = NA,
  sep_crit_x = NA,
  sep_crit_y = NA,
  alpha = 0.1,
  most_likely = F,
  n_interp = 1000,
  n = 10^6,
  n_ensemble = 0,
  x_lab = colnames(data)[2],
  y_lab = colnames(data)[2],
  x_lim_min = min(data[, 2], na.rm = T),
  x_lim_max = max(data[, 2], na.rm = T) + 0.3 * diff(range(data[, 2], na.rm = T)),
  y_lim_min = min(data[, 3], na.rm = T),
  y_lim_max = max(data[, 3], na.rm = T) + 0.3 * diff(range(data[, 3], na.rm = T)),
  plot = T
)

Arguments

data	Data frame of raw data detrended if necessary. First column should be of class Date.
q	Numeric vector of length one specifying quantile level for fitting GPDs and the HT04 and WT13 models.
rp	Numeric vector of length one specifying return period of interest.
mu	Numeric vector of length one specifying the (average) occurrence frequency of events in Data. Default is 365.25, daily data.
n_sim	Numeric vector of length one specifying the number of simulations for HT model. Default is 50.
n_grad	Numeric vector of length one specifying number of number of rays along which to compute points on the curve. Default is 50.
n_boot	Numeric vector of length one specifying number of bootstrap samples. Default is 100.
boot_method	Character vector of length one specifying the bootstrap method. Options are "basic" (default), "block" or "monthly".
boot_replace	Character vector of length one specifying whether bootstrapping is carried out with "T" or without "F" replacement. Only required if boot_method = "basic". Default is NA.
block_length	Numeric vector of length one specifying block length. Only required if boot_method = "block". Default is NA.
boot_prop	Numeric vector of length one specifying the minimum proportion of non-missing values of at least of the variables for a month to be included in the bootstrap. Only required if boot_method = "monthly". Default is 0.8.
decl_method_x	Character vector of length one specifying the declustering method to apply to the first variable. Options are the storm window approach "window" (default) and the runs method "runs".
decl_method_y	Character vector of length one specifying the declustering method to apply to the second variable. Options are the storm window approach "window" (default) and the runs method "runs".
window_length_x	Numeric vector of length one specifying the storm window length to apply during the declustering of the first variable if decl_method_x = "window".
window_length_y	Numeric vector of length one specifying the storm window length to apply during the declustering of the second variable if decl_method_y = "window".
u_x	Numeric vector of length one specifying the threshold to adopt in the declustering of the first variable if decl_method_x = "runs". Default is NA.
u_y	Numeric vector of length one specifying the threshold to adopt in the declustering of the second variable if decl_method_y = "runs". Default is NA.
sep_crit_x	Numeric vector of length one specifying the separation criterion to apply during the declustering of the first variable if decl_method_x = "runs". Default is NA.
sep_crit_y	Numeric vector of length one specifying the separation criterion to apply during the declustering of the second variable if decl_method_y = "runs". Default is NA.
alpha	Numeric vector of length one specifying the 100(1-alpha)% confidence interval. Default is 0.1.
most_likely	Character vector of length one specifying whether to estimate the relative likelihood of events along the curves. For the ht04 curve probabilites are estimated by simulating from the ht04 model while for the wt13 curve a two-sided conditional sampling (using q as the threshold for both samples) copula theory is adopted. Default is FALSE.
n_interp	Numeric vector of length one specifying the resolution of the interpolation of the curves Default is 1000 thus the curve will be composed of 1000 points. The interpolation is only carried out if most-likely = T.
n	Numeric vector of length one specifying the size of the sample from the fitted joint distributions used to estimate the density along an return curves. Default is 10^6
n_ensemble	Numeric vector of length one specifying the number of possible design events sampled along the two curves. Default is 0
x_lab	Character vector specifying the x-axis label. Default is colnames(data)[2].
y_lab	Character vector specifying the y-axis label. Default is colnames(data)[3].
x_lim_min	Numeric vector of length one specifying x-axis minimum. Default is min(data[,2],na.rm=T).
x_lim_max	Numeric vector of length one specifying x-axis maximum. Default is max(data[,2],na.rm=T)+0.3*diff(range(data[,3],na.rm=T)).
y_lim_min	Numeric vector of length one specifying y-axis minimum. Default is min(data[,3],na.rm=T).
y_lim_max	Numeric vector of length one specifying y-axis maximum. Default is max(data[,3],na.rm=T)+0.3*diff(range(data[,3],na.rm=T)).
plot	Logical; whether to plot return curves. Default is "TRUE".

Value

List comprising the median curve based on the HT04 model median_ht04, and the upper ub_ht04 and lower lb_ht04 bound of its 100(1-alpha)% confidence interval. Analogous results for the curve based on the WT13 method median_wt13, ub_wt13 and lb_wt13. If plot=T the median return level curve and associated 100(1-alpha)% confidence intervals are plotted for both extremal dependence models. If most-likely=T, the relative probability of events on the two curves is also returned contour_ht04 and contour_wt13 along with the "most-likely"design event most_likely_ht04 and most_likely_wt13, and an ensemble of possible "design events"sampled along the curve ensemble_ht04 and ensemble_wt13.

Details

The HT04 model is fit to two conditional samples. One sample comprises the declustered time series of the first variable paired with concurrent values of the other variable. The second sample is obtained in the same way but with the variables reversed.

Examples

#Data starts on first day of 1948
head(S22.Detrend.df)

#Dataframe ends on 1948-02-03
tail(S22.Detrend.df)

#Adding dates to complete final month of combined records
final.month = data.frame(seq(as.Date("2019-02-04"),as.Date("2019-02-28"),by="day"),NA,NA,NA)
colnames(final.month) = c("Date","Rainfall","OsWL","Groundwater")
S22.Detrend.df.extended = rbind(S22.Detrend.df,final.month)
#Derive return curves
return_curve_est(data=S22.Detrend.df.extended[,1:3],
                 q=0.985,rp=100,mu=365.25,n_sim=100,
                 n_grad=50,n_boot=100,boot_method="monthly",
                 boot_replace=NA, block_length=NA, boot_prop=0.8,
                 decl_method_x="runs", decl_method_y="runs",
                 window_length_x=NA,window_length_y=NA,
                 u_x=0.95, u_y=0.95,
                 sep_crit_x=36, sep_crit_y=36,
                 alpha=0.1, x_lab=NA, y_lab=NA)

rjaneUCF/MultiHazard documentation built on March 29, 2025, 3:22 p.m.