bratt                  package:VGAM                  R Documentation

_B_r_a_d_l_e_y _T_e_r_r_y _M_o_d_e_l _W_i_t_h _T_i_e_s

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

     Fits a Bradley Terry model with ties (intercept-only model) by
     maximum likelihood estimation.

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

     bratt(refgp = "last", refvalue = 1, init.alpha = 1, i0 = 0.01)

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

   refgp: Integer whose value must be from the set  {1,...,M}, where
          there are M competitors. The default value indicates the last
          competitor is used-but don't input a character string, in
          general. 

refvalue: Numeric. A positive value for the reference group. 

init.alpha: Initial values for the alphas.  These are recycled to the
          appropriate length. 

      i0: Initial value for alpha_0.  If convergence fails, try another
          positive value. 

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

     There are several models that extend the ordinary Bradley Terry
     model to handle ties. This family function implements one of these
     models. It involves M competitors who either win or lose or tie
     against each other. (If there are no draws/ties then use 'brat').
     The probability that Competitor i beats Competitor j is alpha_i /
     (alpha_i + alpha_j + alpha_0), where all the alphas are positive. 
     The probability that Competitor i ties with Competitor j is
     alpha_0 / (alpha_i + alpha_j + alpha_0). Loosely, the alphas can
     be thought of as the competitors' `abilities', and alpha_0 is an
     added parameter to model ties. For identifiability, one of the
     alpha_i is set to a known value 'refvalue', e.g., 1.  By default,
     this function chooses the last competitor to  have this reference
     value. The data can be represented in the form of a  M by M matrix
     of counts, where winners are the rows and losers are the columns.
     However, this is not the way the data should be inputted (see
     below).

     Excluding the reference value/group, this function chooses
     log(alpha_j) as the first M-1 linear predictors. The log link
     ensures that the alphas are positive. The last linear predictor is
     log(alpha_0).

     The Bradley Terry model can be fitted with covariates, e.g., a
     home advantage variable, but unfortunately, this lies outside the
     VGLM theoretical framework and therefore cannot be handled with
     this code.

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

     An object of class '"vglmff"' (see 'vglmff-class'). The object is
     used by modelling functions such as 'vglm'.

_N_o_t_e:

     The function 'Brat' is useful for coercing a M by M matrix of
     counts into a one-row matrix suitable for 'bratt'. Diagonal
     elements are skipped, and the usual S order of 'c(a.matrix)' of
     elements is used. There should be no missing values apart from the
     diagonal elements of the square matrix. The matrix should have
     winners as the rows, and losers  as the columns. In general, the
     response should be a matrix with M(M-1) columns.

     Also, a symmetric matrix of ties should be passed into 'Brat'. The
     diagonal of this matrix should be all 'NA's.

     Only an intercept model is recommended with 'bratt'.  It doesn't
     make sense really to include covariates because of the limited
     VGLM framework.

     Notationally, note that the 'VGAM' family function 'brat' has M+1
     contestants, while 'bratt' has M contestants.

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

     T. W. Yee

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

     Torsney, B. (2004) Fitting Bradley Terry models using a
     multiplicative algorithm. In: Antoch, J. (ed.) _Proceedings in
     Computational Statistics COMPSTAT 2004_, Physica-Verlag:
     Heidelberg. Pages 513-526.

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

     'brat', 'Brat', 'binomialff'.

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

     # citation statistics: being cited is a 'win'; citing is a 'loss'
     journal = c("Biometrika", "Comm Statist", "JASA", "JRSS-B")
     m = matrix(c( NA, 33, 320, 284,
                  730, NA, 813, 276,
                  498, 68,  NA, 325,
                  221, 17, 142,  NA), 4,4)
     dimnames(m) = list(winner = journal, loser = journal)

     # Add some ties. This is fictitional data.
     ties = 5 + 0*m
     ties[2,1] = ties[1,2] = 9

     # Now fit the model
     fit = vglm(Brat(m, ties) ~ 1, bratt(refgp=1), trace=TRUE)
     fit = vglm(Brat(m, ties) ~ 1, bratt(refgp=1), trace=TRUE, cri="c")

     summary(fit)
     c(0, coef(fit)) # log-abilities (in order of "journal"); last is log(alpha0)
     c(1, Coef(fit)) # abilities (in order of "journal"); last is alpha0

     fit@misc$alpha  # alpha_1,...,alpha_M
     fit@misc$alpha0 # alpha_0

     fitted(fit)  # probabilities of winning and tying, in awkward form
     predict(fit)
     (check = InverseBrat(fitted(fit)))    # probabilities of winning 
     qprob = attr(fitted(fit), "probtie")  # probabilities of a tie 
     qprobmat = InverseBrat(c(qprob), NCo=nrow(ties))  # probabilities of a tie 
     check + t(check) + qprobmat    # Should be 1's in the off-diagonals 

