brat                  package:VGAM                  R Documentation

_B_r_a_d_l_e_y _T_e_r_r_y _M_o_d_e_l

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

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

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

     brat(refgp = "last", refvalue = 1, init.alpha = 1)

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

   refgp: Integer whose value must be from the set  {1,...,M+1}, where
          there are M+1 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. 

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

     The Bradley Terry model involves M+1 competitors who either win or
     lose against each other (no draws/ties allowed in this
     implementation-see 'bratt' if there are ties). The probability
     that Competitor i beats Competitor j is alpha_i / (alpha_i +
     alpha_j), where all the alphas are positive.  Loosely, the alphas
     can be thought of as the competitors' `abilities'. 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+1 by M+1 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 M linear predictors. The log link ensures that
     the alphas are positive.

     The Bradley Terry model can be fitted by logistic regression, but
     this approach is not taken here.  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'.

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

     Presently, the residuals are wrong, and the prior weights are not
     handled correctly. Ideally, the total number of counts should be
     the prior weights, after the response has been converted to
     proportions. This would make it similar to family functions such
     as 'multinomial' and 'binomialff'.

_N_o_t_e:

     The function 'Brat' is useful for coercing a M+1 by M+1 matrix of
     counts into a one-row matrix suitable for 'brat'. 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 1-row matrix with M(M+1) columns.

     Only an intercept model is recommended with 'brat'.  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:

     Agresti, A. (2002) _Categorical Data Analysis_, 2nd ed. New York:
     Wiley.

     Stigler, S. (1994) Citation patterns in the journals of statistics
     and probability. _Statistical Science_, *9*, 94-108.

     The 'BradleyTerry' package has more comprehensive capabilities
     than this function.

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

     'bratt', 'Brat', 'multinomial', '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)
     fit = vglm(Brat(m) ~ 1, brat(refgp=1), trace=TRUE)
     fit = vglm(Brat(m) ~ 1, brat(refgp=1), trace=TRUE, cri="c")
     summary(fit)
     c(0, coef(fit)) # log-abilities (in order of "journal")
     c(1, Coef(fit)) # abilities (in order of "journal")
     fitted(fit)  # probabilities of winning in awkward form
     (check = InverseBrat(fitted(fit)))  # probabilities of winning 
     check + t(check)   # Should be 1's in the off-diagonals 

