GpdGlmFit             package:fExtremes             R Documentation

_M_o_d_e_l_l_i_n_g _t_h_e _G_P_D _D_i_s_t_r_i_b_u_t_i_o_n _i_n_c_l_u_d_i_n_g _G_L_M

_D_e_s_c_r_i_p_t_i_o_n:

     a collection of functions to model the Generalized  Pareto
     Distribution, GPD, by maximum likelihood  approximation based on
     R's 'ismev' package. In  addition to the function 'gpdFit' the
     parameter  estimation allows to include generalized linear 
     modelling, glm, of each parameter. 

     The functions are:

       'gpdglmFit'         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,
       'gpdglmprofPlot'    profile log-likelihoods for return levels,
       'gpdglmprofxiPlot'  profile log-likelihoods for shape parameters.

_U_s_a_g_e:

     gpdglmFit(x, threshold = min(x), npy = 365, y = NULL, sigl = NULL,
         shl = NULL, siglink = identity, shlink = identity, show = FALSE,
         method = "Nelder-Mead", maxit = 10000, ...)

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

     gpdglmprofPlot(fit, m, xlow, xup, conf = 0.95, nint = 100, ...)
     gpdglmprofxiPlot(fit, xlow, xup, conf = 0.95, nint = 100, ...)

_A_r_g_u_m_e_n_t_s:

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

  doplot: a logical. Should the results be plotted? 

     fit: a fitted object either of class '"gpdglm"'. 

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

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

  method: [gpdglmFit] - 
           the optimization method; see 'optim' for details. 

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

     npy: [gpdglmFit] - 
           the number of observations per year/block. By default 365. 

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

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

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

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

threshold: [gpdglmFit] - 
           the threshold value; a single number or a numeric vector of
          the same length as 'xdat'. 

   which: [plot][summary] - 
           a vector of logicals, one for each plot, denoting which plot
           should be displayed. By default 'c(TRUE, TRUE, TRUE, TRUE, 
          TRUE)'. 

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

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

       y: [gpdglmFit] - 
           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'. 

     ...: [gpdglmFit] - 
           other control parameters for the optimization. These are
          passed to components of the 'control' argument of 'optim'. 

_D_e_t_a_i_l_s:

     *Simulation:* 

      To simulate a GPD series use the function 'gpdSim'. 

     *Parameter Estimation:* 

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

     *Methods:* 

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

     *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:

     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
     'nexc', 'nllh', 'mle', 'rate' and 'se' are always printed.

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

   model: A list with components 'sigl' and 'shl'. 

    link: A character vector giving inverse link functions. 

threshold: The threshold, or vector of thresholds. 

    nexc: The number of data points above the threshold. 

    data: The data that lie above the threshold. For non-stationary
          models, the data is standardized. 

    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. 

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

     mle: A vector containing the maximum likelihood estimates. 

    rate: The proportion of data points that lie above the threshold. 

     cov: he covariance matrix. 

      se: A vector containing the standard errors. 

       n: The number of data points (i.e. the length of 'xdat'). 

     npy: The number of observations per year/block. 

   xdata: The data that has been fitted. 


     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.

_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.

_E_x_a_m_p_l_e_s:

     ## SOURCE("fExtremes.54B-GpdGlmFit")

     ## Use Rain Data:
        data(rain)
        
     ## Fit GPD Model:
        xmpExtremes("Start: Parameter Estimation >")
        fit = gpdglmFit(x = rain, threshold = 10)
        print(fit)
        xmpExtremes("Next: Summary Report > ")
        
     ## Summarize Results:
        xmpExtremes("Next: Profile Likelihood >")
        par(mfrow = c(2, 2), cex = 0.75)
        summary(fit, which = "all")
        # Profile Lielihood:
        par(mfrow = c(2, 1), cex = 0.75)
        gpdglmprofPlot(fit, m = 10, xlow = 55, xup = 75)
        title(main = "Rain")
        gpdglmprofxiPlot(fit, xlow = -0.02, 0.15)
        title(main = "Rain")

