GpdModelling            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 the
     generalized Pareto distribution and to estimate its parameters.
     The functions compute  density, distribution function, quantile
     function  and generate random deviates for the GPD. Two 
     approaches for parameter estimation are provided:  Maximum
     likelihood estimation and the probability  weighted moment method. 

     The GPD modelling functions are:

       'gpdSim'   generates data from the GPD,
       'gpdFit'   fits empirical or simulated data to the distribution,
       'print'    print method for a fitted GPD object of class ...,
       'plot'     plot method for a fitted GPD object,
       'summary'  summary method for a fitted GPD object.

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

     gpdSim(model = list(xi = 0.25, mu = 0, beta = 1), n = 1000,
         seed = NULL)
     gpdFit(x, u = quantile(x, 0.95), type = c("mle", "pwm"), information = 
         c("observed", "expected"), title = NULL, description = NULL, ...)

     ## S4 method for signature 'fGPDFIT':
     show(object)
     ## S3 method for class 'fGPDFIT':
     plot(x, which = "ask", ...)
     ## S3 method for class 'fGPDFIT':
     summary(object, doplot = TRUE, which = "all", ...)

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

description: a character string which allows for a brief description. 

  doplot: a logical. Should the results be plotted? 

information: whether standard errors should be calculated with
          '"observed"' or '"expected"' information. This only applies
          to the maximum likelihood method; for the
          probability-weighted moments method '"expected"' information
          is used if possible. 

   model: [gpdSim] - 
           a list with components 'shape', 'location' and  'scale'
          giving the parameters of the GPD distribution. By default the
          shape parameter has the value 0.25, the location is zero and
          the scale is one.

       n: [rgpd][gpdSim - 
           the number of observations to be generated. 

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

    seed: [gpdSim] - 
           an integer value to set the seed for the random number
          generator. 

   title: a character string which allows for a project title. 

    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"'.     

       u: the threshold value.     

   which: if 'which' is set to '"ask"' the function will  interactively
          ask which plot should be displayed. By default this value is
          set to 'FALSE' and then those plots will be displayed for
          which the elements in the logical vector 'which' ar set to
          'TRUE'; by default all four elements are set to '"all"'. 

       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"'. 

xi, mu, beta: 'xi' is the shape parameter,  'mu' the location
          parameter, and 'beta' is the scale parameter. 

     ...: 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
     graphical  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:

     ## gpdSim  -
        x = gpdSim(model = list(xi = 0.25, mu = 0, beta = 1), n = 1000)
     ## gpdFit - 
        par(mfrow = c(2, 2), cex = 0.7)  
        fit = gpdFit(x, u = min(x), type = "pwm") 
        print(fit)
        summary(fit)   

