cond_returnlevel_plot: Create conditional return level plots
In SpatialModelsZAMG: Spatial Modeling of Extreme Events

Description Usage Arguments Value References See Also Examples

this function creates a conditional return level plot.

the q-year conditional return level of variable Z1 at location x1 given variable Z2 at location x2, is defined as the threshold B, such that the conditional probability that Z1(x1) exceeds this threshold, given that Z2(x2) is in the interval (cond_B,cond_B_2), is 1/q :

Pr[Z1(x1) > B | Z2(x2) in (cond_B,cond_B_2)] = 1/q .

cond_returnlevel_plot(location, GEVparam, cond_location,
                      cond_GEVparam, same_var, cor_coeff,
                      cond_B, cond_B_2 = Inf, obs = NULL, 
                      var = NULL, period_range = c(1,128), 
                      model = "ext-t", 
                      printObjectives = FALSE, 
                      plottitle = NULL, save_name = NULL, 
                      save_dir = getwd(), printPlot = TRUE)

`location`	a vector with certain location characteristics as entries. characteristics are for example: longitude, latitude and altitude
`GEVparam`	a named vector with the GEV parameters of the variable for which conditional return levels are calculated. names are `loc`, `scale` and `shape`
`cond_location`	a vector with the characteristics of the conditioned location. characteristics should be the same as in `location`
`cond_GEVparam`	a named vector with the GEV parameters of the conditioned variable. names are `loc`, `scale` and `shape`
`same_var`	logical value; if `TRUE`, the conditioned variable is the same as the unconditioned variable. this has to be known in order to use the right correlation function
`cor_coeff`	a named vector with the correlation parameters. for the Huesler-Reiss model: `alpha`, `kappa` and `lambda12` ; for the Extremal-Gaussian model: `alpha`, `sd_kappa`, `swe_kappa` and `rho12` ; for the Extremal-t model: `alpha`, `sd_kappa`, `swe_kappa`, `rho12` and `nu`
`cond_B`	a real number as the lower barrier of the conditioned variable (e.g. the return level)
`cond_B_2`	a real number as the upper barrier of the conditioned variable. default is `cond_B_2 = Inf`
`obs`	a vector with empirical observations. if provided, sample quantiles of this vector are added to the plot as points
`var`	a character string being either `"sd"` or `"swe"` whenever `same_var = TRUE` and `model = "ext-t"` or `"ext-gauss"`. that is, if the conditioned variable is the same as the unconditioned variable, for the Extremal-Gaussian and Extremal-t model it has to be known which variable it is
`period_range`	the range of the return period to be plotted. a vector with start and end point, which should be numbers greater or equal than 1. default is `period_range = c(1,128)`
`model`	a character string; chose which bivariate max-stable model should be used to calculate the conditional return levels. this should be either `"hr"` for the Huesler-Reiss, `"ext-gauss"` for the Extremal-Gaussian or `"ext-t"` (default) for the Extremal-t model
`printObjectives`	logical value; if `TRUE`, a summary of the values f(B) = abs(1/q - Pr[Z1(x1) > B \| Z2(x2) in (cond_B,cond_B_2)]) is printed, where B is the found conditional return level and Pr[Z1(x1) > B \| Z2(x2) in (cond_B,cond_B_2)] is the conditional probability that Z1(x1) (e.g. sd or swe) exceeds B, given that Z2(x2) (e.g. swe or sd) is in between cond_B and cond_B_2; by the minimaization of the function f we find the 1/q quantile of this conditional distribution, thus we want small values. default is `FALSE`
`plottitle`	a character string defining the title of the plot. default is `plottitle = "conditional return level plot"`. if no plottitle is wanted, use `plottitle = ""`
`save_name`	a character string defining the saving name of the plot.
`save_dir`	a character string defining the directory for the plot to be saved. default is the working directory
`printPlot`	logical value; if `TRUE` (default), the plot is printed

a conditional return level plot

Genton, M.G. & Padoan, S.A. & Sang, H. (2015): Multivariate max-stable spatial processes. Biometrika 102(1): 215-230.

http://repository.kaust.edu.sa/kaust/bitstream/10754/552385/1/2013.GPS.Biometrika.Rev_14.pdf

GEVparameters_from_models, cond_returnlevel_map, returnlevel_plot

# load function output from optimizer_biv_hr_model
data("optim_hr")

# define coefficients
sd_coeff  = optim_hr$coefficients$sd_coeff
swe_coeff = optim_hr$coefficients$swe_coeff
cor_coeff = optim_hr$coefficients$cor_coeff

# conditional sd return level at arlberg
# given swe > swe_rl50 in ibk

# arlberg
arl = c("lon" = 10.211, "lat" = 47.13, "alt" = 1979,
        "mdday" = 15.781, "sd_mmax" = 245.6,
        "swe_mmax" = 506.75)
sd_GEVparam_arl  = GEVparameters_from_models(arl, sd_coeff)
swe_GEVparam_arl = GEVparameters_from_models(arl, swe_coeff)

# innsbruck
ibk = c("lon" = 11.392778, "lat" = 47.267222, "alt" = 574,
        "mdday" = 6.12, "sd_mmax" = 16.8, "swe_mmax" = 29)
sd_GEVparam_ibk  = GEVparameters_from_models(ibk, sd_coeff)
swe_GEVparam_ibk = GEVparameters_from_models(ibk, swe_coeff)

# create plot
cond_B = returnlevels(GEVparam = swe_GEVparam_ibk, q = 50)
cond_returnlevel_plot(location = arl, GEVparam = sd_GEVparam_arl,
                      cond_location = ibk,
                      cond_GEVparam = swe_GEVparam_ibk,
                      same_var = FALSE, cond_B = cond_B,
                      cor_coeff = cor_coeff, model = "hr",
                      save_name = "sd_cond_return_level_plot_arl_given_ibk",
                      plottitle = "sd cond rl at arlberg given swe > swe_rl50 in ibk",
                      printPlot = FALSE)