atvpar                  package:evd                  R Documentation

_P_a_r_a_m_e_t_r_i_c _D_e_p_e_n_d_e_n_c_e _F_u_n_c_t_i_o_n_s _o_f _T_r_i_v_a_r_i_a_t_e _E_x_t_r_e_m_e
_V_a_l_u_e _M_o_d_e_l_s

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

     Calculate or plot the dependence function A for the trivariate
     logistic and trivariate asymmetric logistic models.

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

     atvpar(x = rep(1/3,3), dep, asy, model = c("log", "alog"), plot =
         FALSE, col = heat.colors(12), blty = 0, grid = if(blty) 150 else 50,
         lower = 1/3, ord = 1:3, lab = as.character(1:3), lcex = 1)

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

       x: A vector of length three or a matrix with three columns, in
          which case the dependence function is evaluated across the
          rows (ignored if plot is 'TRUE'). The elements/rows of the
          vector/matrix should be positive and should sum to one, or
          else they should have a positive sum, in which case the rows
          are rescaled and a warning is given. A(1/3,1/3,1/3) is
          returned by default since it is often a useful summary of
          dependence.

     dep: The dependence parameter(s). For the logistic model, should
          be a single value. For the asymmetric logistic model, should
          be a vector of length four, or a single value, in which case
          the value is used for each of the four parameters (see
          'rmvevd').

     asy: The asymmetry parameters for the asymmetric logistic model.
          Should be a list with seven vector elements; three of length
          one, three of length two and one of length three, containing
          the asymmetry parameters for each separate component (see
          'rmvevd' and *Examples*).

   model: The specified model; a character string. Must be either
          '"log"' (the default) or '"alog"' (or any unique partial
          match), for the logistic and asymmetric logistic models
          respectively. The definition of each model is given (for
          general dimensions) in 'rmvevd'.

    plot: Logical; if 'TRUE' the function is plotted. The minimum
          (evaluated) value is returned invisibly. If 'FALSE' (the
          default), the following arguments are ignored.

     col: A list of colours (see 'image'). The first colours in the
          list represent smaller values, and hence stronger dependence.
          Each colour represents an equally spaced interval between
          'lower' and one.

    blty: The border line type, for the border that surrounds the
          triangular image. By default 'blty' is zero, so no border is
          plotted. Plotting a border leads to (by default) an increase
          in 'grid' (and hence computation time), to ensure that the
          image fits within it.

    grid: For plotting, the function is evaluated at 'grid^2' points.

   lower: The minimum value for which colours are plotted. By defualt
          'lower' = 1/3 as this is the theoretical minimum of the
          dependence function of the trivariate extreme value
          distribution.

     ord: A vector of length three, which should be a permutation of
          the set {1,2,3}. The points (1,0,0), (0,1,0) and (0,0,1) (the
          vertices of the simplex) are depicted clockwise from the top
          in the order defined by 'ord'.

     lab: A character vector of length three, in which case the 'i'th
          margin is labelled using the 'i'th component, or 'NULL', in
          which case no labels are given. The actual location of the
          margins, and hence the labels, is defined by 'ord'.

    lcex: A numerical value giving the amount by which the labels
          should be scaled relative to the default. Ignored if 'lab' is
          'NULL'.

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

     Let z = (z1,z2,z3) and w = (w1,w2,w3). Any trivariate extreme
     value distribution can be written as

 G(z) = exp{-(y1+y2+y3) A[y1/(y1+y2+y3),y2/(y1+y2+y3), y3/(y1+y2+y3)]}

     for some function A defined on the simplex S_3 = {w: w1 + w2 + w3
     = 1}, where 

                    yi = {1+si(zi-ai)/bi}^(-1/si)

     for 1+si(zi-ai)/bi > 0 and i = 1,2,3, and where the (generalized
     extreme value) marginal parameters are given by (ai,bi,si), bi >
     0. If si = 0 then yi is defined by continuity.

     A is called (by some authors) the dependence function. It follows
     that A(1,0,0) = A(0,1,0) = A(0,0,1) = 1, and that A is a convex
     function with max(w1,w2,w3) <= A(w) <= 1 for all w in S_3. The
     lower and upper limits of A are obtained under complete dependence
     and mutual independence respectively. A does not depend on the
     marginal parameters.

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

     'atvpar' calculates or plots the dependence function for the
     trivariate logistic and trivariate asymmetric logistic models, at
     specified parameter values.

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

     'atvnonpar', 'abvpar', 'rmvevd', 'image'

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

     atvpar(dep = 0.5, model = "log")
     s3pts <- matrix(rexp(30), nrow = 10, ncol = 3)
     s3pts <- s3pts/rowSums(s3pts)
     atvpar(s3pts, dep = 0.5, model = "log")
     ## Not run: atvpar(dep = 0.05, model = "log", plot = TRUE, blty = 1)
     atvpar(dep = 0.95, model = "log", plot = TRUE, lower = 0.94)

     asy <- list(.4, .1, .6, c(.3,.2), c(.1,.1), c(.4,.1), c(.2,.3,.2))
     atvpar(s3pts, dep = 0.15, asy = asy, model = "alog")
     atvpar(dep = 0.15, asy = asy, model = "al", plot = TRUE, lower = 0.7)

