BradleyTerry          package:BradleyTerry          R Documentation

_B_r_a_d_l_e_y-_T_e_r_r_y _m_o_d_e_l _a_n_d _e_x_t_e_n_s_i_o_n_s

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

     Fits Bradley-Terry models for pair comparison data, including
     models with structured scores and missing covariate data.  Fits by
     either maximum likelihood or maximum penalized likelihood (with
     Jeffreys-prior penalty).

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

     BTm(formula, refcat = NULL, offset = NULL, contrasts = NULL,
     data = NULL, subset = NULL, br = FALSE, order.effect =
     NULL, ...)

     BTresiduals(model)

     BTabilities(model)

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

 formula: A model formula for the Bradley-Terry "ability" parameters. 
          Response variable should be a data frame containing contest
          results: columns include factors named "winner" (by default
          column 1) and "loser" (by default column 2), and possibly
          also "Freq", a numeric vector recording the frequency of each
          contest result (taken to be 1 if omitted). Variables on RHS
          have length equal to the number of players.  The special RHS
          formula '..' specifies the standard Bradley-Terry model with
          unstructured abilities.

  refcat: Which is the "reference" player?  Only used with '..' on the
          RHS of the formula.  Default is player 1.

  offset: An optional offset term in the model. A vector of length
          equal to the number of players.

contrasts: As for 'glm'. 

    data: A data frame, in which RHS variables can be found. 

  subset: An optional logical or numeric vector specifying a  subset of
           observations (ie, a subset of rows of the response
          dataframe)  to be used in the fitting process. 

      br: Logical.  If 'TRUE', fitting will be by penalized maximum
          likelihood as in Firth (1992, 1993), using 'brlr' from
          package brlr. Default is fitting by maximum likelihood.

order.effect: An optional vector, numeric, indicating an order effect
          to be estimated in the model (for example, a home advantage
          effect).  Values should be 1 where contest winner has the
          advantage, -1 where loser has the advantage, and 0 where
          neither player is advantaged.

     ...: other arguments for 'glm' or 'brlr' 

   model: a model object for which 'inherits(model, "BTm")' is 'TRUE'

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

     No allowance is made for tied contests.

     Aside from the possibility of an order effect, contest-specific
     predictors are not catered for by 'BTm'.  However, the
     availability of the 'model' and 'x' components in objects of class
     'BTm' allows a model fitted with only player-specific predictors
     to be manipulated subsequently to include further terms involving
     contest-specific predictors.

     The residuals returned by 'BTresiduals' are weighted means of
     working residuals, with weights equal to the binomial denominators
     in the fitted model.  These are suitable for diagnostic model
     checking, for example plotting against candidate predictors.

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

     An object of class 'c("BTm", "glm", "lm")', or of class 'c("BTm",
     "brlr", "glm", "lm")' if 'br = TRUE'.  Components are as for 'glm'
     or 'brlr', with additionally 

      x0: Model matrix for the formula as supplied (rather than the
          model matrix actually used in the subsidiary call to 'glm' or
          'brlr', which is included as component 'x' if the call
          includes 'x = TRUE').  One row for each player.

 offset0: The supplied offset vector, if any was specified.   One
          element for each player.  (The offset vector actually used in
          the subsidiary call to 'glm' or 'brlr' is included as
          component 'offset'.)

      y0: The data frame of contest winners and losers, containing 
          only those rows actually used in fitting the model.

order.effect: The values of order.effect, if specified.

abilities: A two-column matrix of estimated abilities, with the ability
          for 'refcat' set to zero if 'refcat' is specified (otherwise
          the first player has zero ability).  First column is
          estimated ability, second column is the standard error for
          that estmate.  One row for each player.


     Function 'BTresiduals' returns a vector of residuals, one for each
     "player".

     Function 'BTabilities' simply returns the 'abilities' component of
     the specified model.

_N_o_t_e:

     Methods specific to the 'BTm' class of models are

        *  'add1.BTm'

        *  'drop1.BTm'

        *  'terms.BTm'

        *  'formula.BTm'

     Others are inherited from 'glm' or 'lm'.

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

     David Firth

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

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

     Firth, D. (1992)  Bias reduction, the Jeffreys prior and GLIM. In 
     _Advances in GLIM and Statistical Modelling_, Eds. L Fahrmeir, B J
     Francis, R Gilchrist and G Tutz, pp91-100.  New York: Springer.

     Firth, D. (1993)  Bias reduction of maximum likelihood estimates.
     _Biometrika_ *80*, 27-38.

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

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

     ##
     ##  Statistics journal citation data from Stigler (1994)
     ##  -- see also Agresti (2002, p448)
     journals <- c("Biometrika", "Comm Statist", "JASA", "JRSS-B")
     citedata <- matrix(c(NA,33,320,284,
                          730,NA,813,276,
                          498,68,NA,325,
                          221,17,142,NA),
                        4,4,
                        dimnames = list(winner = journals, loser = journals))
     citedata <- as.data.frame.table(citedata)
                      
     ##  First fit the "standard" Bradley-Terry model
     print(mymodel <- BTm(citedata ~ ..))

     ##  Now the same thing with a different "reference" journal
     print(mymodel2 <- update(mymodel, . ~ ., refcat = "JASA"))

     ##  Is the "citeability" of a journal predicted by its country of origin?
     origin <- factor(c("UK", "USA", "USA", "UK"))
     print(mynewmodel <- BTm(citedata ~ origin))

     ##  Hmm... not so sure about the origin of "Comm Statist" ...
     is.na(origin[2]) <- TRUE
     mynewmodel2 <- update(mynewmodel, . ~ .)
     BTabilities(mynewmodel2)

     ##  Now an example with an order effect -- see Agresti (2002) p438
     teams <- c("Milwaukee", "Detroit", "Toronto",
                "New York", "Boston", "Cleveland", "Baltimore")
     baseball <- data.frame(
       winner = factor(rep(rep(1:7, rep(7,7)), 2), labels =  teams),
       loser = factor(rep(rep(1:7, 7), 2), labels = teams),
       Freq = c(NA,4,4,4,6,4,6,  # home wins
                3,NA,4,4,6,6,4,
                2,4,NA,2,4,4,6,
                3,5,2,NA,4,4,6,
                5,2,3,4,NA,5,6,
                2,3,3,4,4,NA,2,
                2,1,1,2,1,3,NA,
                NA,3,5,3,1,5,5,  # away wins
                3,NA,3,1,5,3,5,
                2,2,NA,5,3,4,6,
                3,3,4,NA,2,3,4,
                1,0,3,3,NA,2,6,
                2,1,2,2,2,NA,4,
                0,3,0,1,0,4,NA),
        home.adv = rep(c(1, -1), c(49,49)))

     ##  Simple Bradley-Terry model as in Agresti p437
     print(baseball.model <- BTm(baseball ~ ..))
     BTresiduals(baseball.model)

     ##  Introduce order effect as in Agresti p438
     update(baseball.model, order.effect = baseball$home.adv)   

