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:

     This is a collection 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:

       1  'hillPlot'     shape parameter and Hill estimate of the tail index,
       2  '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: [saparmPlot] - a logical, decides whether or not both tails
          should be  investigated. By default TRUE. If FALSE only the
          lower tail will be investigated. 

  doplot: [saparmPlot] -  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: [saparmPlot] - a logical, decides whether or not for all tail
          depths the result for the shape parameter '1/alpha' should be
          printed. 

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

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

   tails: [saparmPlot] - 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: [saparmPlot] -      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

