cond_returnlevels: Calculate conditional return levels

In SpatialModelsZAMG: Spatial Modeling of Extreme Events

Description

this function calculates conditional return levels.

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 .

Usage

cond_returnlevels(locations, GEVparam, q,
                  cond_locations, cond_GEVparam, same_var,
                  cor_coeff, cond_B, cond_B_2 = Inf, 
                  var = NULL, model = "ext-t", 
                  printObjectives = FALSE)

Arguments

locations	a matrix or vector with certain location characteristics as columns/entries. each row corresponds to one location, columns are for example: longitude, latitude and altitude
GEVparam	a named matrix or vector with the GEV parameters of the variable for which the conditional return levels are calculated. each row corresponds to one location (same ones as in locations), columns are loc, scale and shape
q	the return period for the calculation of the conditional return levels – must be a number greater than 1
cond_locations	a matrix or a vector with the location characteristics of the conditioned locations. each row corresponds to one location, columns should be the same as in locations
cond_GEVparam	a named matrix or vector with the GEV parameters of the conditioned variable. each row corresponds to one location (same ones as in cond_locations), columns 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 vector of real numbers as the lower barriers of the conditioned variable (e.g. the return levels)
cond_B_2	a vector of real numbers as the upper barriers of the conditioned variable. default is cond_B_2 = Inf
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
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

Value

a vector with the conditional return levels

References

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

See Also

GEVparameters_from_models, cond_returnlevel_plot, cond_returnlevel_map,
returnlevels

Examples

# get covariables
lon = get(data(lon.at))
lon = as.vector(t(lon))
lat = get(data(lat.at))
lat = as.vector(t(lat))
alt = get(data(alt.at))
alt = as.vector(t(alt))

x = get(data(sample_grid_data))

mdday    = x$mdday
sd_mmax  = x$mmsd
swe_mmax = x$mmswe

# take only locations of the (Austrian) domain
lon = lon[which(!is.na(mdday))]
lat = lat[which(!is.na(mdday))]
alt = alt[which(!is.na(mdday))]
mdday    = mdday[which(!is.na(mdday))]
sd_mmax  = sd_mmax[which(!is.na(sd_mmax))]
swe_mmax = swe_mmax[which(!is.na(swe_mmax))]

# define matrix 'covariables'
covariables = cbind("lon" = lon, "lat" = lat, "alt" = alt,
                    "mdday" = mdday, "sd_mmax" = sd_mmax,
                    "swe_mmax" = swe_mmax)

# load function output from GEVparameters_from_models
sd_GEVparam  = get(data("sd_GEVparam"))
swe_GEVparam = get(data("swe_GEVparam"))

# 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

# define return period (same as in sd_GEVparam)
q = 100

# calculate return levels
sd_rl  = returnlevels(GEVparam = sd_GEVparam,  q = q)
swe_rl = returnlevels(GEVparam = swe_GEVparam, q = q)

# sd given swe at same locations
cond_rl_sd =
  cond_returnlevels(locations = covariables,
                    GEVparam = sd_GEVparam,
                    q = q, cond_locations = covariables,
                    cond_GEVparam = swe_GEVparam,
                    same_var = FALSE, cond_B = swe_rl,
                    cor_coeff = cor_coeff, model = "hr",
                    printObjectives = TRUE)

# swe given sd at same location
cond_rl_swe =
  cond_returnlevels(locations = covariables,
                    GEVparam = swe_GEVparam,
                    q = q, cond_locations = covariables,
                    cond_GEVparam = sd_GEVparam,
                    same_var = FALSE, cond_B = sd_rl,
                    cor_coeff = cor_coeff, model = "hr",
                    printObjectives = TRUE)

# sd given sd in ibk
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)
sd_rl_ibk = returnlevels(GEVparam = sd_GEVparam_ibk, q = q)

cond_rl_ibk =
  cond_returnlevels(locations = covariables,
                    GEVparam = sd_GEVparam,
                    q = q, cond_locations = ibk,
                    cond_GEVparam = sd_GEVparam_ibk,
                    same_var = TRUE, cond_B = sd_rl_ibk,
                    cor_coeff = cor_coeff, model = "hr",
                    printObjectives = TRUE)

SpatialModelsZAMG documentation built on Nov. 11, 2019, 3 p.m.