fbvpot                  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 _t_o _T_h_r_e_s_h_o_l_d _E_x_c_e_e_d_a_n_c_e_s

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

     Fit models for one of seven parametric bivariate extreme-value
     distributions using threshold exceedances, allowing any of the
     parameters to be held fixed if desired.

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

     fbvpot(x, threshold, model = "log", likelihood = "censored", start,
         ..., sym = FALSE, cshape = cscale, cscale = 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 with two columns. If this contains
          missing values, those values are treated as if they fell
          below the corresponding marginal threshold.

threshold: A vector of two thresholds.

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

likelihood: Unimplemented.

   start: A named list giving the initial values for all of the
          parameters in the model. 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).

  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 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 bivariate peaks over threshold models are fitted by maximizing
     the censored likelihood as given in e.g. Section 8.3.1 of
     Coles(2001).

     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 'scale1' and 'shape1'
     for the first margin, and 'scale2' and 'shape2' for the second
     margin.

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

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

     If 'dsm' is 'TRUE', three values are returned which summarize the
     dependence structure, based on the fitted dependence function A
     (see 'fbvevd' for details).

     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("bvpot","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. There is
     currently no plot method available.

     An object of class 'c("bvpot","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'.

threshold: The argument 'threshold'.

       n: The number of rows in 'x'.

     nat: The vector of length three containing the number of
          exceedances on the first, second and both margins
          respectively.

     sym: The argument 'sym'.

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

   model: The argument 'model'.

    call: The call of the current function.

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

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

     Chris Ferro and Alec Stephenson

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

     Coles, S. G. (2001) _An Introduction to Statistical Modelling of
     Extreme Values_, London: Springer-Verlag.

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

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

     'abvpar', 'anova.evd', 'fbvevd', 'optim', 'rbvevd'

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

     bvdata <- rbvevd(1000, dep = 0.5, model = "log")
     u <- apply(bvdata, 2,  quantile, probs = 0.9)
     M1 <- fbvpot(bvdata, u, model = "log")
     M2 <- fbvpot(bvdata, u, "log", dep = 0.5)
     anova(M1, M2)

