Design_Event_2D: Derives a single or ensemble of bivariate design events

View source: R/Design_Event_2D.R

Design_Event_2DR 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.

Usage

Design_Event_2D(
  Data,
  Data_Con1,
  Data_Con2,
  u1,
  u2,
  Thres1 = NA,
  Thres2 = NA,
  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_Con_2 = NA,
  Tab1 = NA,
  Tab2 = NA,
  mu = 365.25,
  GPD_Bayes = FALSE,
  Decimal_Place = 2,
  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,
  Isoline_Type = "Combined"
)

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.

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.

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. Only one of u1, Thres1, GPD1 and Tab1 is required.

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. Only one of u2, Thres2, GPD2 and Tab2 is required.

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.

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.

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").

Rate_Con2

Numeric vector of length one specifying the occurrence rate of observations in Data_Con2. Default is NA.

Decimal_Palace

Numeric vector specifying the number of decimal places to which to specifiy the isoline. Defulat is 2.

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.

See Also

Copula_Threshold_2D Diag_Non_Con Diag_Non_Con_Trunc

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(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 Aug. 17, 2024, 2:14 p.m.