gevFit               package:fExtremes               R Documentation

_M_o_d_e_l_l_i_n_g _G_E_V _D_i_s_t_r_i_b_u_t_i_o_n

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

     This is a collection of functions to model the Generalized Extreme
      Value, GEV, distribution based on R's 'evir' package. Two  types
     of approaches for parameter estimation are provided: Maximum 
     likelihood estimation and  probability weighted moment method. 

     The functions are:

       1  'gevSim'         generates data from the GEV,
       2  'gevFit'         fits empirical or simulated data to the distribution,
       3  'print'          print method for a fitted GEV object,
       4  'plot'           plot method for a fitted GEV object,
       5  'summary'        summary method for a fitted GEV object,
       6  'gevrlevelPlot'  k-block return level with confidence intervals.

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

     gevSim(model = list(shape = 0.25, location = 0, scale = 1), n = 1000)
     gevFit(x, block = NA, type = c("mle", "pwm"), gumbel = FALSE, ...)

     ## S3 method for class 'gevFit':
     print(x, ...)
     ## S3 method for class 'gevFit':
     plot(x, which = "all", ...)
     ## S3 method for class 'gevFit':
     summary(object, doplot = TRUE, which = "all", ...)

     gevrlevelPlot(object, k.blocks = 20, add = FALSE, ...)

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

     add: [gevrlevelPlot] - whether the return level should be added
          graphically to a time series plot; if 'FALSE' a graph of the
          profile likelihood curve showing the return level and its
          confidence interval is produced. 

   block: [gevFit] - the block size. Only used if 'method="mle"' is
          selected. A numeric value is interpreted as the number of
          data values in each successive block. All the data is used,
          so the last block may not contain 'block' observations. If
          the 'data' has a 'times' attribute containing (in an object
          of class '"POSIXct"', or an object that can be converted to
          that class; see 'as.POSIXct') the times/dates of each
          observation, then 'block' may instead take the character
          values '"month"', '"quarter"', '"semester"' or '"year"'. 

  doplot: a logical. Should the results be plotted? 

  gumbel: [gevFit] - a logical, by default FALSE. To fit a Gumbel model
          with fixed 'shape=0' set 'gumbel=TRUE'. 

k.blocks: [gevrlevelPlot] - specifies the particular return level to be
          estimated; default  set arbitrarily to 20. 

   model: [gevSim] -  a list with components 'shape', 'location' and 
          'scale' giving the parameters of the GEV distribution. By
          default the shape parameter has the value 0.25, the location
          is zero and the scale is one. To fit random deviates from a
          Gumbel distribution set  'shape=0'. 

       n: [gevSim] - number of generated data points, an integer value. 

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

    type: a character string denoting the type of parameter estimation,
          either by maximum likelihood estimation '"mle"', the default
          value, or by the probability weighted moment menthod '"pwm"'. 

   which: [plot][summary] - a vector of logicals, one for each plot,
          denoting which plot  should be displayed. Alkternatively if
          'which="ask"' the user will be interactively asked which of
          the plots should be desplayed. By default 'which="all"'. 

       x: [gevFit] - data vector. In the case of 'method="mle"' the
          interpretation  depends on the value of block: if no block
          size is specified then  data are interpreted as block maxima;
          if block size is set, then data are interpreted as raw data
          and block maxima are calculated.  [print][plot] - a fitted
          object of class '"gevFit"'. 

     ...: [gevFit] - control parameters optionally passed to the 
          optimization function. Parameters for the optimization
          function are passed to components of the 'control' argument
          of 'optim'.  [plot][summary] - arguments passed to the plot
          function. 

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

     *Parameter Estimation:* 

      'gevFit' estimates the parameters either by the probability 
     weighted moment method, 'method="pwm"' or by maximum log 
     likelihood estimation 'method="mle"'.  As a limiting case the
     Gumbel distribution can be selected. The  summary method produces
     diagnostic plots for fitted GEV or Gumbel  models. 

     *Methods:* 

      'print.gev', 'plot.gev' and 'summary.gev' are print, plot, and
     summary methods for a fitted object of class  'gev'. Concerning
     the summary method, the data are  converted to unit exponentially
     distributed residuals under null  hypothesis that GEV fits. Two
     diagnostics for iid exponential data  are offered. The plot method
     provides two different residual plots  for assessing the fitted
     GEV model. Two diagnostics for  iid exponential data are offered.  

     *Return Level Plot:* 

      'gevrlevelPlot' calculates and plots the k-block return level 
     and 95% confidence interval based on a GEV model for block maxima,
      where 'k' is specified by the user. The k-block return level  is
     that level exceeded once every 'k' blocks, on average. The  GEV
     likelihood is reparameterized in terms of the unknown return 
     level and profile likelihood arguments are used to construct a 
     confidence interval.

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

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

     'gevFit' 
      returns an object of class 'gev' describing the fit. 

     'print.summary' 
      prints a report of the parameter fit. 

     'summary' 
      performs diagnostic analysis. The method provides two different 
     residual plots for assessing the fitted GEV model.   

     'gevrlevelPlot' 
      returns a vector containing the lower 95% bound of the confidence
      interval, the estimated return level and the upper 95% bound.

_N_o_t_e:

     If method '"mle"' is selected the parameter fitting in 'gevFit' 
     is passed to the internal function 'gev.mle' or 'gumbel.mle'
     depending on the value of 'gumbel', 'FALSE' or 'TRUE'. On the
     other hand, if method '"pwm"' is selected the parameter  fitting
     in 'gevFit' is passed to the internal function  'gev.pwm' or
     'gumbel.pwm' again depending on the value of  'gumbel', 'FALSE' or
     'TRUE'.

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

     This function is based on Alec Stephenson's R-package 'evir' 
     ported from the 'EVIS' library, _Extreme Values in S_, written by
     Alexander McNeil. The 'fExtremes' port and the  change and
     addition of some functions were done by Diethelm Wuertz.

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

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

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

     'gevglmFit', 'gevFamily'.

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

     ## Simulate GEV Data:
        xmpExtremes("\nStart: Simulte GEV Sample >")
        # Use default length n=1000
        x = gevSim(model = list(shape = 0.25, location =0 , scale = 1))
        # Fit GEV Data by Probability Weighted Moments:
        fit = gevFit(x, type = "pwm") 
        print(fit)
        # Summarize Results:
        par(mfcol = c(3, 2))
        summary(fit)
        
     ## Fit GEV Data by Max Log Likelihood Method:
        xmpExtremes("\nNext: Estimate Parameters >")
        fit = gevFit(x, type = "mle") 
        print(fit)
        # Summarize Results:
        summary(fit) 
         
     ## Simulate Gumbel Data:
        xmpExtremes("\nNext: Simulte Gumbel Sample >")
        # Use default length n=1000
        ##> x = gevSim(model = list(shape = 0, location = 0, scale = 1))
        # Fit Gumbel Data by Probability Weighted Moments:
        ##> fit = gevFit(x, type = "pwm", gumbel = TRUE) 
        ##> print(fit)
        # Summarize Results:
        ##> par(mfcol = c(3, 2))
        ##> summary(fit)  
        
     ## Fit Gumbel Data by Max Log Likelihood Method:
        xmpExtremes("\nNext: Estimate Parameters >")
        ##> fit = gevFit(x, type = "mle", gumbel = TRUE) 
        ##> print(fit)
        # Summarize Results:
        ##> summary(fit)     
        ##> xmpExtremes("Press any key to continue >") 
        
     ## Return levels based on GEV Fit:
        # BMW Stock Data:
        xmpExtremes("\nNext: Compute BMW Return Levels >")
        par(mfrow = c(2, 1))
        data(bmw)
        # Fit GEV to monthly Block Maxima:
        fit = gevFit(-bmw, block = "month") 
        # Calculate the 40 month return level
        gevrlevelPlot(fit, k.block = 40, main = "BMW: Return Levels")   
        
     ## Return levels based on GEV Fit:
        xmpExtremes("\nNext: Compute SIEMENS Return Levels >")
        # Siemens Stock Data:
        data(siemens)
        # Fit GEV to monthly Block Maxima:
        fit = gevFit(-siemens, block = "month") 
        # Calculate the 40 month return level
        gevrlevelPlot(fit, k.block = 40, main = "SIEMENS: Return Levels")
        
     ## Interactive Plot:
        ##> par(mfrow = c(1, 1), ask = TRUE)
        ##> plot(fit)

