MdaPlots              package:fExtremes              R Documentation

_H_i_l_l _a_n_d _S_h_a_p_e _P_a_r_a_m_e_t_e_r _P_l_o_t_s

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

     A collection and description of functions for the  estimation of
     the tail index of extreme data using  the maximum domain of
     attraction, MDA, method. Included  are the Pickands,
     Einmal-Decker-deHaan, and Hill estimators together with several
     plot variants. 

     The functions are:

       'hillPlot'     shape parameter and Hill estimate of the tail index,
       'shaparmPlot'  variation of shape parameter with tail depth.

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

     hillPlot(x, option = c("alpha", "xi", "quantile"), start = 15,
         end = NA, reverse = FALSE, p = NA, ci = 0.95, autoscale = TRUE, 
         labels = TRUE, ...)
         
     shaparmPlot(x, revert = FALSE, standardize = FALSE, tails = 0.01*(1:10), 
         doplot = <<see below>>, which = <<see below>>, doprint = TRUE, 
         both.tails = TRUE, xi.range = c(0, 10), alpha.range = c(-0.5, 1.5)) 

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

       x: [hillPlot][shaparmPlot] - 
           the data from which to calculate the shape parameter, a
          numeric vector. 

autoscale: [hillPlot] - 
           whether or not plot should be automatically scaled; if not,
          'xlim' and 'ylim' graphical parameters may be entered. 

      ci: [hillPlot] - 
           probability for asymptotic confidence band; for no
          confidence band set 'ci' to zero. 

  labels: [hillPlot] - 
           whether or not axes should be labelled. 

  option: [hillPlot] - 
           whether 'alpha', 'xi' (1/alpha) or 'quantile' (a quantile
          estimate) should be plotted. 

       p: [hillPlot] - 
           probability required when option 'quantile' is chosen. 

 reverse: [hillPlot] - 
           whether plot is to be by increasing threshold, 'TRUE', or 
          increasing number of order statistics 'FALSE'. 

start, end: [hillPlot] - 
           lowest and highest number of order statistics at which to
          plot a point. 

     ...: [hillPlot] - 
           other graphics parameters. 

alpha.range, xi.range: [saparmPlot] - 
           plotting ranges. 

both.tails: [shaparmPlot] - 
           a logical, decides whether or not both tails should be 
          investigated. By default TRUE. If FALSE only the lower tail
          will be investigated. 

  doplot: [shaparmPlot] - 
           a vector of logicals of the same lengths as tails defining
          for wich tail depths plots should be created, by default
          plots will be generated for a tail depth of 5 percent. By
          default 'c(FALSE, FALSE, FALSE, FALSE,  TRUE, FALSE, FALSE,
          FALSE, FALSE, FALSE)'. 

 doprint: [shaparmPlot] - 
           a logical, decides whether or not for all tail depths the
          result for the shape parameter '1/alpha' should be printed. 

  revert: [shaparmPlot] - 
           a logical value, by default FALSE, if set to TRUE the sign
          of the vector will be reverted: 'x = -x'. 

standardize: [shaparmPlot] - 
           a logical value, by default FALSE, if set to  TRUE the
          vector 'x' will be standardized:  'x =
          (x-mean(x))/sqrt(var(x))'. 

   tails: [shaparmPlot] - 
           a numeric vector of tail depths to be considered; by default
          ten values ranging from 0.1 to 1.0 in steps of 0.1
          corresponding to values ranging from 1 to 10 percent. 

   which: [shaparmPlot] - 
           a vector of 3 logicals indicating which plots from the 
          three methods will be created. The first entry decides for
          the Pickands estimator, the second for the Hill  estimator,
          and the last for the Deckers-Einmahl-deHaan estimator. By
          default all three will be created. By default 'c(TRUE, TRUE,
          TRUE)'. 

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

     *Hill Plot:* 

      The function 'hillPlot' investigates the shape parameter and 
     plots the Hill estimate of the tail index of heavy-tailed data, or
      of an associated quantile estimate. This plot is usually
     calculated  from the alpha perspective. For a generalized Pareto
     analysis of  heavy-tailed data using the 'gpdFit' function, it
     helps to  plot the Hill estimates for 'xi'.  

     *Shape Parameter Plot:* 

      The function 'shaparmPlot' investigates the shape parameter and 
     plots for the upper and lower tails the shape parameter as a
     function  of the taildepth. Three approaches are considered, the
     _Pickands_  estimator, the _Hill_ estimator, and the
     _Decker-Einmal-deHaan_ estimator.

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

     'hillPlot' 
      displays a plot.

     'shaparmPlot'  
      returns a list with one or two entries, depending on the
     selection of the input variable 'both.tails'. The two  entries
     'upper' and 'lower' determine the position of  the tail. Each of
     the two variables is again a list with entries  'pickands',
     'hill', and 'dehaan'. If one of the  three methods will be
     discarded the printout will display zeroes.

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

     Alec Stephenson for R's evir package, 
      Alexander Mcneil for the original EVIS code, 
      Diethelm Wuertz for this R-port.

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

     Coles S. (2001); _Introduction to Statistical Modelling of Extreme
     Values_, Springer.

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

_S_e_e _A_l_s_o:

     'gpdFit'.

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

     ## hillPlot -
        xmpExtremes("\nStart: Hill Estimator >")
        # Hill plot of heavy-tailed Danish fire insurance data 
        # and BMW stock data for estimated 0.999 quantile
        par(mfrow = c(2, 2))
        data(bmw)
        hillPlot(bmw)
        hillPlot(bmw, option = "quantile", end = 500, p = 0.999)
        data(danish)
        hillPlot(danish)
        hillPlot(danish, option = "quantile", end = 500, p = 0.999)
        
     ## shaparmPlot -
        xmpExtremes("\nNext: Shape Parameter Plots >")
        par(mfcol = c(3, 2), cex = 0.6)
        data(bmw)
        shaparmPlot(bmw)

     ## shaparmPlot -
        xmpExtremes("\nNext: Simulated Frechet Data >")
        par(mfcol = c(3, 2), cex = 0.6)
        set.seed(4711)
        x = rgev(10000, xi = 1/4)
        shaparmPlot(x, revert = TRUE, both.tails = FALSE)
        lines(c(0.01, 0.1), c(4, 4), col = "steelblue3") # True Value

