Design_Event_2D_Grid: Derives a single or ensemble of bivariate design events
In rjaneUCF/MultiHazard: Tools for modeling compound events

Design_Event_2D_Grid

R Documentation

Derives a single or ensemble of bivariate design events

Description

Calculates the isoline and relative probability of events on the isoline, given the observational data, for one or more user-specified return periods. Outputs the single "most-likely" design event or an ensemble of possible design events obtained by sampling along the isoline according to these relative probabilities. The design event under the assumption of full dependence is also computed. Isoline is derived by calculating annual exceedance probabilities from both copula models on a user-specified grid rather by overlaying the partial isolines from the two copula models as in Design_Event_2D.

Usage

Design_Event_2D_Grid(
  Data,
  Data_Con1,
  Data_Con2,
  u1,
  u2,
  Thres1 = NA,
  Thres2 = NA,
  N_Both,
  Copula_Family1,
  Copula_Family2,
  Marginal_Dist1,
  Marginal_Dist2,
  Marginal_Dist1_Par = NA,
  Marginal_Dist2_Par = NA,
  Con1 = "Rainfall",
  Con2 = "OsWL",
  GPD1 = NA,
  GPD2 = NA,
  Rate_Con1 = NA,
  Rate_Con2 = NA,
  Tab1 = NA,
  Tab2 = NA,
  mu = 365.25,
  GPD_Bayes = FALSE,
  Decimal_Place = 2,
  Grid_x_min = NA,
  Grid_x_max = NA,
  Grid_y_min = NA,
  Grid_y_max = NA,
  Grid_x_interval = NA,
  Grid_y_interval = NA,
  RP,
  Interval = 10000,
  End = F,
  Resolution = "Low",
  x_lab = "Rainfall (mm)",
  y_lab = "O-sWL (mNGVD 29)",
  x_lim_min = NA,
  x_lim_max = NA,
  y_lim_min = NA,
  y_lim_max = NA,
  Isoline_Probs = "Sample",
  N = 10^6,
  N_Ensemble = 0,
  Sim_Max = 10,
  Plot_Quantile_Isoline = FALSE
)

Arguments

`Data`	Data frame of dimension `nx2` containing two co-occurring time series of length `n`.
`Data_Con1`	Data frame containing the conditional sample (declustered excesses paired with concurrent values of other variable), conditioned on the variable in the first column.
`Data_Con2`	Data frame containing the conditional sample (declustered excesses paired with concurrent values of other variable), conditioned on the variable in the second column. Can be obtained using the `Con_Sampling_2D` function.
`u1`	Numeric vector of length one specifying the threshold, expressed as a quantile, above which the variable in the first column was sampled in `Data_Con1`.
`u2`	Numeric vector of length one specifying the threshold, expressed as a quantile, above which the variable in the second column was sampled in `Data_Con2`.
`Thres1`	Numeric vector of length one specifying the threshold above which the variable in the first column was sampled in `Data_Con1`. Only one of `u1` and `Thres1` should be supplied. Default is `NA`.
`Thres2`	Numeric vector of length one specifying the threshold above which the variable in the second column was sampled in `Data_Con2`. Only one of `u2` and `Thres2` should be supplied. Default is `NA`.
`N_Both`	Numeric vector of length one specifying the number of data points that feature in both conditional samples.
`Copula_Family1`	Numeric vector of length one specifying the copula family used to model the `Data_Con1` dataset.
`Copula_Family2`	Numeric vector of length one specifying the copula family used to model the `Data_Con2` dataset. Best fitting of 40 copulas can be found using the `Copula_Threshold_2D` function.
`Marginal_Dist1`	Character vector of length one specifying (non-extreme) distribution used to model the marginal distribution of the non-conditioned variable in `Data_Con1`.
`Marginal_Dist2`	Character vector of length one specifying (non-extreme) distribution used to model the marginal distribution of the non-conditioned variable in `Data_Con2`.
`Con1`	Character vector of length one specifying the name of variable in the first column of `Data`.
`Con2`	Character vector of length one specifying the name of variable in the second column of `Data`.
`GPD1`	Output of `GPD_Fit` applied to variable `con1` i.e., GPD fit `con1`. Default `NA`. Only one of `u1`, `Thres1`, `GPD1` and `Tab1` is required.
`GPD2`	Output of `GPD_Fit` applied to variable `con2` i.e., GPD fit `con2`. Default `NA`. Only one of `u2`, `Thres2`, `GPD2` and `Tab2` is required.
`Rate_Con1`	Numeric vector of length one specifying the occurrence rate of observations in `Data_Con1`. Default is `NA`.
`Rate_Con2`	Numeric vector of length one specifying the occurrence rate of observations in `Data_Con2`. Default is `NA`.
`Tab1`	Data frame specifying the return periods of variable `con1`, when conditioning on `con1`. First column specifies the return period and the second column gives the corresponding levels. First row must contain the return level of `con1` for the inter-arrival time (1/rate) of the sample.
`Tab2`	Data frame specifying the return periods of variable `con2`, when conditioning on `con2`. First column specifies the return period and the second column gives the corresponding levels. First row must contain the return level of `con2` for the inter-arrival time (1/rate) of the sample.
`mu`	Numeric vector of length one specifying the (average) occurrence frequency of events in `Data`. Default is `365.25`, daily data.
`GPD_Bayes`	Logical; indicating whether to use a Bayesian approach to estimate GPD parameters. This involves applying a penalty to the likelihood to aid in the stability of the optimization procedure. Default is `FALSE`.
`Grid_x_min`	Numeric vector of length one specifying the minimum value of the variable in second column of `Data` contained in the grid.
`Grid_x_max`	Numeric vector of length one specifying the maximum value of the variable in second column of `Data` contained in the grid.
`Grid_x_interval`	Numeric vector of length one specifying the resolution of the grid in terms of the variable in first column of `Date`. Default is an interval `2` of between consecutive values.
`Grid_y_interval`	Numeric vector of length one specifying the resolution of the grid in terms of the variable in second column of `Date`. Default is an interval `0.1` of between consecutive values.
`RP`	Numeric vector specifying the return periods of interest.
`Interval`	Numeric vector specifying the number of equally spaced points comprising the combined isoline.
`x_lab`	Character vector specifying the x-axis label.
`y_lab`	Character vector specifying the y-axis label.
`x_lim_min`	Numeric vector of length one specifying x-axis minimum. Default is `NA`.
`x_lim_max`	Numeric vector of length one specifying x-axis maximum. Default is `NA`.
`y_lim_min`	Numeric vector of length one specifying y-axis minimum. Default is `NA`.
`y_lim_max`	Numeric vector of length one specifying y-axis maximum. Default is `NA`.
`N`	Numeric vector of length one specifying the size of the sample from the fitted joint distributions used to estimate the density along an isoline. Samples are collected from the two joint distribution with proportions consistent with the total number of extreme events conditioned on each variable. Default is `10^6`
`N_Ensemble`	Numeric vector of length one specifying the number of possible design events sampled along the isoline of interest.
`Sim_Max`	Numeric vector of length one specifying the maximum value, given as a multiple of the largest observation of each variable, permitted in the sample used to estimate the (relative) probabilities along the isoline.
`Plot_Quantile_Isoline`	Logical; indicating whether to first plot the quantile isoline. Default is `FALSE`.
`Decimal_Palace`	Numeric vector specifying the number of decimal places to which to specify the isoline. Default is `2`
`Isoline_Type`	Character vector of length one specifying the type of isoline. For isolines obtained using the overlaying method in Bender et al. (2016) use `"Combined"` (default). For quantile isoline from the sample conditioned on variable `Con1`\|(`Con2`) use `"Con1"`(`"Con2"`).

Value

Plot of all the observations (grey circles) as well as the declustered excesses above Thres1 (blue circles) or Thres2 (blue circles), observations may belong to both conditional samples. Also shown is the isoline associated with RP contoured according to their relative probability of occurrence on the basis of the sample from the two joint distributions, the "most likely" design event (black diamond), and design event under the assumption of full dependence (black triangle) are also shown in the plot. The function also returns a list comprising the design events assuming full dependence "FullDependence", as well as once the dependence between the variables is accounted for the "Most likley" "MostLikelyEvent" as well as an "Ensemble" of possible design events and relative probabilities of events on the isoline Contour. The quantile isolines with Quantile_Isoline_1 and Quantile_Isoline_2, and GPD thresholds with Threshold_1 and Threshold_2.

Examples

S22.Rainfall<-Con_Sampling_2D(Data_Detrend=S22.Detrend.df[,-c(1,4)],
                             Data_Declust=S22.Detrend.Declustered.df[,-c(1,4)],
                             Con_Variable="Rainfall",u=0.97)
S22.OsWL<-Con_Sampling_2D(Data_Detrend=S22.Detrend.df[,-c(1,4)],
                         Data_Declust=S22.Detrend.Declustered.df[,-c(1,4)],
                         Con_Variable="OsWL",u=0.97)
S22.Copula.Rainfall<-Copula_Threshold_2D(Data_Detrend=S22.Detrend.df[,-c(1,4)],
                                        Data_Declust=S22.Detrend.Declustered.df[,-c(1,4)],u1 =0.97,
                                        y_lim_min=-0.075,y_lim_max=0.25,
                                        Upper=c(2,9),Lower=c(2,10),GAP=0.15)$Copula_Family_Var1
S22.Copula.OsWL<-Copula_Threshold_2D(Data_Detrend=S22.Detrend.df[,-c(1,4)],
                                    Data_Declust=S22.Detrend.Declustered.df[,-c(1,4)],u2 =0.97,
                                    y_lim_min=-0.075, y_lim_max =0.25,
                                    Upper=c(2,9),Lower=c(2,10),GAP=0.15)$Copula_Family_Var2
Design.Event<-Design_Event_2D_Grid(Data=S22.Detrend.df[,-c(1,4)],
                                  Data_Con1=S22.Rainfall$Data, Data_Con2=S22.OsWL$Data,
                                  u1=0.97, u2=0.97,
                                  Copula_Family1=S22.Copula.Rainfall, Copula_Family2=S22.Copula.OsWL,
                                  Marginal_Dist1="Logis", Marginal_Dist2="Twe",
                                  RP=c(5,100),Interval=10000,N=10^6,N_Ensemble=10,
                                  Plot_Quantile_Isoline=FALSE)
#Extracting the 100-year isoline from the output
Design.Event$`100`$Isoline

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