fbvevd                  package:evd                  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 _B_i_v_a_r_i_a_t_e _E_x_t_r_e_m_e _V_a_l_u_e _D_i_s_t_r_i_b_u_t_i_o_n_s

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

     Fit models for one of eight parametric bivariate extreme value
     distributions, including linear modelling of the marginal location
     parameters, and allowing any of the parameters to be held fixed if
     desired.

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

     fbvevd(x, model = "log", start, ..., sym = FALSE, nsloc1 = NULL,
         nsloc2 = NULL, cshape = cscale, cscale = cloc, cloc = FALSE,
         std.err = TRUE, dsm = TRUE, corr = FALSE, method = "BFGS",
         warn.inf = TRUE)

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

       x: A matrix or data frame, ordinarily with two columns, which
          may contain missing values. A data frame may also contain a
          third column of mode 'logical', which itself may contain
          missing values (see *More Details*).

   model: The specified model; a character string. Must be either
          '"log"' (the default), '"alog"', '"hr"', '"neglog"',
          '"aneglog"', '"bilog"', '"negbilog"' or '"ct"' (or any unique
          partial match), for the logistic, asymmetric logistic,
          Husler-Reiss, negative logistic, asymmetric negative
          logistic, bilogistic, negative bilogistic and Coles-Tawn
          models respectively. The definition of each model is given in
          'rbvevd'.

   start: A named list giving the initial values for the parameters
          over which the likelihood is to be maximized. If 'start' is
          omitted the routine attempts to find good starting values
          using marginal maximum likelihood estimators.

     ...: Additional parameters, either for the bivariate extreme value
          model or for the optimization function 'optim'. If parameters
          of the model are included they will be held fixed at the
          values given (see *Examples*).

     sym: Logical; if 'TRUE', the dependence structure of the models
          '"alog"', '"aneglog"' or '"ct"' are constrained to be
          symmetric (see *Details*). For all other models, the argument
          is ignored (and a warning is given).

nsloc1, nsloc2: A data frame with the same number of rows as 'x', for
          linear modelling of the location parameter on the
          first/second margin (see *Details*). The data frames are
          treated as covariate matrices, excluding the intercept. A
          numeric vector can be given as an alternative to a single
          column data frame.

  cshape: Logical; if 'TRUE', a common shape parameter is fitted to
          each margin.

  cscale: Logical; if 'TRUE', a common scale parameter is fitted to
          each margin, and the default value of 'cshape' is then
          'TRUE', so that under this default common scale and shape
          parameters are fitted.

    cloc: Logical; if 'TRUE', a common location parameter is fitted to
          each margin, and the default values of 'cshape' and 'cscale'
          are then 'TRUE', so that under these defaults common marginal
          parameters are fitted.

 std.err: Logical; if 'TRUE' (the default), the standard errors are
          returned.

     dsm: Logical; if 'TRUE' (the default), summaries of the dependence
          structure are returned.

    corr: Logical; if 'TRUE', the correlation matrix is returned.

  method: The optimization method (see 'optim' for details).

warn.inf: Logical; if 'TRUE' (the default), a warning is given if the
          negative log-likelihood is infinite when evaluated at the
          starting values.

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

     The dependence parameter names are one or more of 'dep', 'asy1',
     'asy2', 'alpha' and 'beta', depending on the model selected (see
     'rbvevd'). The marginal parameter names are 'loc1', 'scale1' and
     'shape1' for the first margin, and 'loc2', 'scale2' and 'shape2'
     for the second margin. If 'nsloc1' is not 'NULL', so that a linear
     model is implemented for the first marginal location parameter,
     the parameter names for the first margin are 'loc1', 'loc1'_x1_,
     ..., 'loc1'_xn_, 'scale' and 'shape', where _x1_, ..., _xn_ are
     the column names of 'nsloc1', so that 'loc1' is the intercept of
     the linear model, and 'loc1'_x1_, ..., 'loc1'_xn_ are the
     'ncol(nsloc1)' coefficients. When 'nsloc2' is not 'NULL', the
     parameter names for the second margin are constructed similarly.

     It is recommended that the covariates within the linear models for
     the location parameters are (at least approximately) centered and
     scaled (i.e. that the columns of 'nsloc1' and 'nsloc2' are
     centered and scaled), particularly if automatic starting values
     are used, since the starting values for the associated parameters
     are then zero. If 'cloc' is 'TRUE', both 'nsloc1' and 'nsloc2'
     must be identical, since a common linear model is then implemented
     on both margins.

     If 'cshape' is true, the models are constrained so that 'shape2 =
     shape1'. The parameter 'shape2' is then taken to be specified, so
     that e.g. the common shape parameter can only be fixed at zero
     using 'shape1 = 0', since using 'shape2 = 0' gives an error.
     Similar comments apply for 'cscale' and 'cloc'.

     If 'sym' is 'TRUE', the asymmetric logistic and asymmetric
     negative logistic models are constrained so that 'asy2 = asy1',
     and the Coles-Tawn model is constrained so that 'beta = alpha'.
     The parameter 'asy2' or 'beta' is then taken to be specified, so
     that e.g. the parameters 'asy1' and 'asy2' can only be fixed at
     '0.8' using 'asy1 = 0.8', since using 'asy2 = 0.8' gives an error.

     Bilogistic and negative bilogistic models constrained to symmetry
     are logistic and negative logistic models respectively. The mixed
     model (e.g. Tawn, 1998) is obtained by the asymmetric negative
     logistic model upon setting the dependence parameter to be one,
     and constraining the asymmetry parameters to be equal to each
     other. It can therefore be fitted using 'model = "anegl"' with
     'dep = 1' and 'sym = TRUE' (see *Examples*).

     If 'dsm' is 'TRUE', three values are returned which summarize the
     dependence structure, based on the fitted dependence function A
     (see 'abvpar'). Two are measures of the strength of dependence.
     The first (Dependence One) is given by 2(1-A(1/2)). The second
     (Dependence Two) is the integral of 4(1 - A(x)), taken over 0 <= x
     <= 1. Both measures are zero at independence and one at complete
     dependence.

     The third value (Asymmetry) is a measure of asymmetry, given by
     the integral of 4(A(x) - A(1-x))/(3 - 2 sqrt(2)), taken over 0 <=
     x <= 0.5. This lies in the closed interval [-1,1], with larger
     absolute values representing stronger asymmetry. For the logistic,
     Husler-Reiss and negative logistic models A(x) = A(1-x) for all 0
     <= x <= 0.5, so the value will be zero.

     For numerical reasons the parameters of each model are subject the
     artificial constraints given in Table 1 of the User's Guide.

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

     Returns an object of class 'c("bvevd","evd")'.

     The generic accessor functions 'fitted' (or 'fitted.values'),
     'std.errors', 'deviance', 'logLik' and 'AIC' extract various
     features of the returned object.

     The functions 'profile' and 'profile2d' can be used to obtain
     deviance profiles. The function 'anova' compares nested models,
     and the function 'AIC' compares non-nested models. The function
     'plot' produces diagnostic plots.

     An object of class 'c("bvevd","evd")' is a list containing the
     following components 

estimate: A vector containing the maximum likelihood estimates.

 std.err: A vector containing the standard errors.

   fixed: A vector containing the parameters that have been fixed at
          specific values within the optimization.

  fixed2: A vector containing the parameters that have been set to be
          equal to other model parameters.

   param: A vector containing all parameters (those optimized, those
          fixed to specific values, and those set to be equal to other
          model parameters).

deviance: The deviance at the maximum likelihood estimates.

dep.summary: A vector of three values, summarizing the dependence
          structure of the fitted model (see *Details*).

    corr: The correlation matrix.

convergence, counts, message: Components taken from the list returned
          by 'optim'.

    data: The data passed to the argument 'x'.

   tdata: The data, transformed to stationarity (for non-stationary
          models).

nsloc1, nsloc2: The arguments 'nsloc1' and 'nsloc2'.

       n: The number of rows in 'x'.

     sym: The argument 'sym'.

    cmar: The vector 'c(cloc, cscale, cshape)'.

   model: The argument 'model'.

    call: The call of the current function.

_M_o_r_e _D_e_t_a_i_l_s:

     If 'x' is a data frame with a third column of mode 'logical', then
     the model is fitted using the likelihood derived by Stephenson and
     Tawn (2004). This is appropriate when each bivariate data point
     comprises componentwise maxima from some underlying bivariate
     process, and where the corresponding logical value denotes whether
     or not the maxima were caused by the same event within that
     process.

     Under this scheme the diagnostic plots that are produced using
     'plot' are somewhat different to those described in 'plot.bvevd'.
     In particular, there is no comparative non-parametric dependence
     function estimate, and the conditional P-P plots condition on both
     the logical case and the given margin (which requires numerical
     integration at each data point).

_W_a_r_n_i_n_g:

     The standard errors and the correlation matrix in the returned
     object are taken from the observed information, calculated by a
     numerical approximation. They must be interpreted with caution
     when either of the marginal shape parameters are less than -0.5,
     because the usual asymptotic properties of maximum likelihood
     estimators do not then hold (Smith, 1985).

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

     Smith, R. L. (1985) Maximum likelihood estimation in a class of
     non-regular cases. _Biometrika_, *72*, 67-90.

     Stephenson, A. G. and Tawn, J. A. (2004) Exploiting Occurence
     Times in Likelihood Inference for Componentwise Maxima.
     _Biometrika_ (To Appear).

     Tawn, J. A. (1988) Bivariate extreme value theory: models and
     estimation. _Biometrika_, *75*, 397-415.

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

     'anova.evd', 'optim', 'plot.bvevd', 'profile.evd',
     'profile2d.evd', 'rbvevd'

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

     bvdata <- rbvevd(100, dep = 0.6, model = "log", mar1 = c(1.2,1.4,0.4))
     M1 <- fbvevd(bvdata, model = "log")
     M2 <- fbvevd(bvdata, model = "log", dep = 0.75)
     anova(M1, M2)
     par(mfrow = c(2,2))
     plot(M1)
     plot(M1, mar = 1)
     plot(M1, mar = 2)
     ## Not run: par(mfrow = c(1,1))
     ## Not run: M1P <- profile(M1, which = "dep")
     ## Not run: plot(M1P)

     trend <- (-49:50)/100
     rnd <- runif(100, min = -.5, max = .5)
     fbvevd(bvdata, model = "log", nsloc1 = trend)
     fbvevd(bvdata, model = "log", nsloc1 = trend, nsloc2 = data.frame(trend
     = trend,  random = rnd))
     fbvevd(bvdata, model = "log", nsloc1 = trend, nsloc2 = data.frame(trend
     = trend, random = rnd), loc2random = 0)

     bvdata <- rbvevd(100, dep = 1, asy = c(0.5,0.5), model = "anegl")
     anlog <- fbvevd(bvdata, model = "anegl")
     mixed <- fbvevd(bvdata, model = "anegl", dep = 1, sym = TRUE)
     anova(anlog, mixed)

