GevFit               package:fExtremes               R Documentation

_M_o_d_e_l_l_i_n_g _t_h_e _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:

     A collection and description 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:

       'gevSim'         generates data from the GEV,
       'gevFit'         fits empirical or simulated data to the distribution,
       'print'          print method for a fitted GEV object,
       'plot'           plot method for a fitted GEV object,
       'summary'        summary method for a fitted GEV object,
       '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', 'GevDistribution'.

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

     ## gevSim -
     ## gevFit -
        # 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)
        
     ## gevFit -
        # Fit GEV Data by Max Log Likelihood Method:
        xmpExtremes("\nNext: Estimate Parameters >")
        fit = gevFit(x, type = "mle") 
        print(fit)
        # Summarize Results:
        summary(fit) 
         
     ## gevSim -
     ## gevFit -
        # 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)

