gevglmFit             package:fExtremes             R Documentation

_M_a_x_i_m_u_m-_l_i_k_e_l_i_h_o_o_d _F_i_t_t_i_n_g _o_f _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:

     This is a collection of functions to model the Generalized Extreme
      Value, GEV, distribution by maximum likelihood approximation
     based  on R's 'ismev' package. In addition to 'gevFit' the
     parameter  estimation allows to include generalized linear
     modelling of each  parameter, therefore the name 'gevglmFit'. 

     The functions are:

       1  'gevglmFit'         fits empirical or simulated data to the distribution,
       2  'print'             print method for a fitted GEV object of class ...,
       3  'plot'              plot method for a fitted GEV object,
       4  'summary'           summary method for a fitted GEV object,
       5  'gevglmprofPlot'    profile log-likelihoods for return levels,
       6  'gevglmprofxiPlot'  profile log-likelihoods for shape parameters.

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

     gevglmFit(x, y = NULL, gumbel = FALSE, mul = NULL, sigl = NULL, shl = NULL, 
         mulink = identity, siglink = identity, shlink = identity, show = FALSE, 
         method = "Nelder-Mead", maxit = 10000, ...)

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

     gevglmprofPlot(object, m, xlow, xup, conf = 0.95, nint = 100)
     gevglmprofxiPlot(object, xlow, xup, conf = 0.95, nint = 100)

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

    conf: [gevglmprof*Plot] - the confidence coefficient of the plotted
          profile confidence  interval. 

  doplot: a logical. Should the results be plotted? 

  gumbel: [gevglmFit] -  a logical, should a Gumbel fit be created? In
          this case the shape parameter equals zero, and the arguments
          'shl' and and  'shlink' are omitted. 

       m: [gevglmprofPlot] - the return level; i.e. the profile
          likelihood is for the value  that is exceeded with
          probability 1/'m'. 

   maxit: [gevglmFit] - the maximum number of iterations. 

  method: [gevglmFit] -  the optimization method (see 'optim' for
          details). 

mul, sigl, shl: [gevglmFit] -  numeric vectors of integers, giving the
          columns of 'ydat' that contain covariates for generalized
          linear modelling of the location, scale and shape parameters
          repectively (or 'NULL' (the default) if the corresponding
          parameter is stationary). 

mulink, siglink, shlink: [gevglmFit] -  inverse link functions for
          generalized linear modelling of the  location, scale and
          shape parameters repectively. 

    nint: [gevglmprof*Plot] - the number of points at which the profile
          likelihood is evaluated. 

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

    show: [gevglmFit] - a logical; if 'TRUE' (the default), print
          details of the fit. 

       x: [gevglmFit] - a numeric vector of data to be fitted. 
           [print][plot] - a fitted object of class '"gevglmFit"'. 

xlow, xup: [gevglmprof*Plot] - the least and greatest value at which to
          evaluate the profile  likelihood. 

       y: [gevglmFit] - a matrix of covariates for generalized linear
          modelling of the parameters (or 'NULL' (the default) for
          stationary fitting). The number of rows should be the same as
          the length of 'xdat'. 

   which: [plot][summary] - a vector of logicals, one for each plot,
          denoting which plot  should be displayed. 

     ...: [gevglmFit] - 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:

     *Simulation:* 

      To simulate a GEV series use the function 'gevSim'.  

     *Parameter Estimation:* 

      'gevglmFit' fits by the Maximum-likelihood approach the
     generalized  extreme value distribution, including generalized
     linear modelling  of each parameter.  

     *Methods:* 

      'print.gevglm', 'plot.gevglm' and 'summary.gevglm'  are print,
     plot, and summary methods for a fitted object of class 
     'gevglmFit'. 

     *Profile Likelihood:* 

      'gevglmprofPlot' and 'gevglmprofxiPlot' produce profile 
     log-likelihoods for shape parameters and 'm' year/block return 
     levels for stationary GEV models using the output of the function 
     'gevFit'. 

     *Nonstationary Models:* 

      For non-stationary fitting it is recommended that the covariates
     within the generalized linear models are (at least approximately)
     centered and scaled (i.e. the columns of 'ydat' should be
     approximately centered and scaled).

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

     'gevglmFit' 
      returns a list containing the following components. A subset of
     these components are printed after the fit. If 'show'  is 'TRUE',
     then assuming that successful convergence is indicated, the
     components 'nllh', 'mle' and 'se' are always printed.

   trans: an logical indicator for a non-stationary fit. 

   model: a list with components 'mul', 'sigl' and 'shl'. 

    link: a character vector giving inverse link functions. 

    conv: the convergence code, taken from the list returned by
          'optim'. A zero indicates successful convergence. 

    nllh: the negative logarithm of the likelihood evaluated at the
          maximum likelihood estimates. 

    data: the data that has been fitted. For non-stationary models, the
          data is standardized. 

     mle: a vector containing the maximum likelihood estimates. 

     cov: the covariance matrix. 

      se: a vector containing the standard errors. 

    vals: a matrix with three columns containing the maximum likelihood
          estimates of the location, scale and shape parameters at each
          data point. 


     For stationary models four plots are produced; a probability plot,
     a quantile plot, a return level plot and a histogram of data with
     fitted density. For non-stationary models two plots  are produced;
     a residual probability plot and a residual quantile  plot. 

     'gevglmprofPlot'
      'gevglmprofxiPlot'
      a plot of the profile likelihood is produced, with a horizontal
     line  representing a profile confidence interval with confidence
     coefficient  'conf'.

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

     Alec Stephenson for the code implemented from R's ismev package, 
      Stuart Scott for the original code, and 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.

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

     'gevFit', 'gevFamily'.

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

     ## Simulated GEV Data:
        xmpExtremes("\nStart: Simulte GEV Sample >")
        x = gevSim(model = list(shape = 0.25, location = 0, scale = 1), n = 1000)
        par(mfrow = c(2, 2))
        plot(x, main = "Simulated GEV Data")
        # Fit GEV Data:
        fit = gevglmFit(x) 
        print(fit)
        # Summarize Results:
        summary(fit, which = c(TRUE, TRUE, TRUE, FALSE))
        
     ## Simulated GEV Data:
        xmpExtremes("\nNext: Estimate Parameters >")
        ##> x = gevSim(model = list(shape = 0, location = 0, scale = 1), n = 1000)
        ##> par(mfrow = c(2, 2))
        ##> plot(x, main = "Simulated Gumbel Data")
        # Fit GEV Data:
        ##> fit = gevglmFit(x, gumbel = TRUE) 
        ##> print(fit)
        # Summarize Results:
        ##> summary(fit, which = c(TRUE, TRUE, TRUE, FALSE))
        
     ## Portpirie Data:
        xmpExtremes("\nNext: Fit Portpirie Data >")
        par(mfrow = c(2, 1))
        data(portpirie)
        fit = gevglmFit(portpirie[, 2])
        gevglmprofPlot(fit, m = 10, 4.1, 5)
        title(main = "Portpirie")
        gevglmprofxiPlot(fit, -0.3, 0.3)
        title(main = "Portpirie")
        
     ## Interactive Plot:
        ##> par(mfrow = c(2, 2))
        ##> plot(fit)

