gpdRisk              package:fExtremes              R Documentation

_G_P_D _D_i_s_t_r_i_b_u_t_i_o_n_s _f_o_r _E_x_t_r_e_m_e _V_a_l_u_e _T_h_e_o_r_y

_D_e_s_c_r_i_p_t_i_o_n:

     A collection and description to functions to compute tail risk
     under the GPD approach. 

     The GPD modelling functions are:

       'gpdQPlot'         estimation of high quantiles,
       'gpdQuantPlot'     variation of high quantiles with threshold,
       'gpdRiskMeasures'  prescribed quantiles and expected shortfalls,
       'gpdSfallPlot'     expected shortfall with confidence intervals,
       'gpdShapePlot'     variation of shape with threshold,
       'gpdTailPlot'      plot of the tail,
       'tailPlot'         ,
       'tailSlider'       ,
       'tailRisk'         .

_U_s_a_g_e:

     gpdQPlot(x, p = 0.99, ci = 0.95, type = c("likelihood", "wald"),  
         like.num = 50)
     gpdQuantPlot(x, p = 0.99, ci = 0.95, models = 30, start = 15, end = 500,
         doplot = TRUE, plottype = c("normal", "reverse"), labels = TRUE,
         ...) 
     gpdSfallPlot(x, p = 0.99, ci = 0.95, like.num = 50)
     gpdShapePlot(x, ci = 0.95, models = 30, start = 15, end = 500,
         doplot = TRUE, plottype = c("normal", "reverse"), labels = TRUE,
         ...) 
     gpdTailPlot(object, plottype = c("xy", "x", "y", ""), doplot = TRUE, 
         extend = 1.5, labels = TRUE, ...)

     gpdRiskMeasures(object, prob = c(0.99, 0.995, 0.999, 0.9995, 0.9999))

     tailPlot(object, p = 0.99, ci = 0.95, nLLH = 25, extend = 1.5, grid =
     TRUE, labels = TRUE, ...) 
     tailSlider(x)
     tailRisk(object, prob = c(0.99, 0.995, 0.999, 0.9995, 0.9999), ...)

_A_r_g_u_m_e_n_t_s:

      ci: the probability for asymptotic confidence band; for no 
          confidence band set to zero. 

  doplot: a logical. Should the results be plotted? 

  extend: optional argument for plots 1 and 2 expressing how far x-axis
           should extend as a multiple of the largest data value. This 
          argument must take values greater than 1 and is useful for
          showing estimated quantiles beyond data. 

    grid: ... 

  labels: optional argument for plots 1 and 2  specifying whether or
          not axes should be labelled. 

like.num: the number of times to evaluate profile likelihood. 

  models: the number of consecutive gpd models to be fitted. 

    nLLH: ... 

  object: [summary] - 
           a fitted object of class '"gpdFit"'. 

       p: a vector of probability levels, the desired probability for
          the  quantile estimate (e.g. 0.99 for the 99th percentile). 

 reverse: should plot be by increasing threshold ('TRUE') or number  of
          extremes ('FALSE'). 

    prob: a numeric value. 

plottype: a character string. 

start, end: the lowest and maximum number of exceedances to be
          considered. 

    type: a character string selecting the desired estimation mehtod,
          either '"mle"' for the maximum likelihood mehtod or '"pwm"'
          for  the probability weighted moment method. By default, the
          first will  be selected. Note, the function 'gpd' uses
          '"ml"'.     

       x: [dgpd] - 
           a numeric vector of quantiles. 
           [gpdFit] - 
           the data vector. Note, there are two different names for the
          first argument 'x' and 'data' depending  which function name
          is used, either 'gpdFit' or the  EVIS synonyme 'gpd'. 
           [print][plot] - 
           a fitted object of class '"gpdFit"'. 

     ...: control parameters and plot parameters optionally passed to
          the  optimization and/or plot function. Parameters for the
          optimization function are passed to components of the
          'control' argument of 'optim'.   

_D_e_t_a_i_l_s:

     *Generalized Pareto Distribution:* 

      Compute density, distribution function, quantile function and 
     generates random variates for the Generalized Pareto Distribution.

     *Simulation:* 

      'gpdSim' simulates data from a Generalized Pareto  distribution. 

     *Parameter Estimation:* 

      'gpdFit' fits the model parameters either by the probability 
     weighted moment method or the maxim log likelihood method.  The
     function returns an object of class '"gpd"'  representing the fit
     of a generalized Pareto model to excesses over  a high threshold.
     The fitting functions use the probability weighted  moment method,
     if method 'method="pwm"' was selected, and the  the general
     purpose optimization function 'optim' when the  maximum likelihood
     estimation, 'method="mle"' or 'method="ml"'  is chosen. 

     *Methods:* 

      'print.gpd', 'plot.gpd' and 'summary.gpd' are print,  plot, and
     summary methods for a fitted object of class 'gpdFit'.  The plot
     method provides four different plots for assessing fitted  GPD
     model.  

     *gpd* Functions:* 

      'gpdqPlot' calculates quantile estimates and confidence intervals
      for high quantiles above the threshold in a GPD analysis, and
     adds a  graphical representation to an existing plot. The GPD
     approximation in  the tail is used to estimate quantile. The
     '"wald"' method uses  the observed Fisher information matrix to
     calculate confidence interval.  The '"likelihood"' method
     reparametrizes the likelihood in terms  of the unknown quantile
     and uses profile likelihood arguments to  construct a confidence
     interval.  

     'gpdquantPlot' creates a plot showing how the estimate of a  high
     quantile in the tail of a dataset based on the GPD approximation 
     varies with threshold or number of extremes. For every model 
     'gpdFit' is called. Evaluation may be slow. Confidence intervals 
     by the Wald method may be fastest. 

     'gpdriskmeasures' makes a rapid calculation of point estimates  of
     prescribed quantiles and expected shortfalls using the output of
     the function 'gpdFit'. This function simply calculates point
     estimates  and (at present) makes no attempt to calculate
     confidence intervals for  the risk measures. If confidence levels
     are required use 'gpdqPlot'  and 'gpdsfallPlot' which interact
     with graphs of the tail of a loss distribution and are much
     slower.   

     'gpdsfallPlot' calculates expected shortfall estimates, in other
     words tail conditional expectation and confidence intervals for
     high   quantiles above the threshold in a GPD analysis. A
     graphicalx representation to an existing plot is added. Expected
     shortfall is  the expected size of the loss, given that a
     particular quantile of the  loss distribution is exceeded. The GPD
     approximation in the tail is used  to estimate expected shortfall.
     The likelihood is reparametrised  in  terms of the unknown
     expected shortfall and profile likelihood arguments  are used to
     construct a confidence interval.  

     'gpdshapePlot' creates a plot showing how the estimate of shape 
     varies with threshold or number of extremes. For every model 
     'gpdFit' is called. Evaluation may be slow.   

     'gpdtailPlot' produces a plot of the tail of the underlying 
     distribution of the data.

_V_a_l_u_e:

     'gpdSim' 
      returns a vector of datapoints from the simulated  series.

     'gpdFit'  
      returns an object of class '"gpd"' describing the  fit including
     parameter estimates and standard errors. 

     'gpdQuantPlot' 
      returns invisible a table of results.

     'gpdShapePlot' 
      returns invisible a table of results.

     'gpdTailPlot' 
      returns invisible a list object containing  details of the plot
     is returned invisibly. This object should be  used as the first
     argument of 'gpdqPlot' or 'gpdsfallPlot'  to add quantile
     estimates or expected shortfall estimates to the  plot.

_A_u_t_h_o_r(_s):

     Alec Stephenson for the functions from R's 'evd' package, 
       Alec Stephenson for the functions from R's 'evir' package, 
       Alexander McNeil for the EVIS functions underlying the 'evir'
     package, 
       Diethelm Wuertz for this R-port.

_R_e_f_e_r_e_n_c_e_s:

     Embrechts, P., Klueppelberg, C., Mikosch, T. (1997); _Modelling
     Extremal Events_, Springer. 

     Hosking J.R.M., Wallis J.R., (1987); _Parameter and quantile
     estimation for the generalized Pareto distribution_,   
     Technometrics 29, 339-349.

_E_x_a_m_p_l_e_s:

     ## Load Data:
        danish = as.timeSeries(data(danishClaims))

     ## Tail Plot:
        x = as.timeSeries(data(danishClaims))
        fit = gpdFit(x, u = 10)
        tailPlot(fit)

     ## Try Tail Slider:
        # tailSlider(x)   

     ## Tail Risk:
        tailRisk(fit)

