# Function to fit a loglinear Bradley-Terry model for paired comparisons

### Description

Function to fit a loglinear Bradley-Terry for paired comparisons allowing subject covariates and undecided response categories.

### Usage

1 2 | ```
llbtPC.fit(obj, nitems, formel = ~1, elim = ~1, resptype = "paircomp",
obj.names = NULL, undec = TRUE)
``` |

### Arguments

`obj` |
either a dataframe or the path/name of the datafile to be read. |

`nitems` |
the number of compared objects, not the number of comparisons |

`formel` |
the formula for subject covariates to fit different preference scales for the objects (see below). |

`elim` |
the formula for the subject covariates that specify the table
to be analysed. If omitted and |

`resptype` |
is |

`obj.names` |
character vector with names for objects. |

`undec` |
for paired comparisons with a undecided/neutral category,
a common parameter will be estimated if |

### Details

Models including categorical subject covariates can be fitted using the
`formel`

and `elim`

arguments. `formel`

specifies the
actual model to be fitted. For instance, if specified as
`formel=~SEX`

different preference scale for the objects will be
estimated for males and females. For two or more covariates,
the operators `+`

or `*`

can be used to model main or interaction
effects, respectively. The operator `:`

is not allowed. See also
`formula`

.
The specification for `elim`

follows the same rules as for
`formel`

. However, `elim`

specifies the basic contingency
table to be set up but does not specify any covariates to be fitted.
This is done using `formel`

.
If, e.g., `elim=~SEX`

but `formel=~1`

,
then the table is set up as if `SEX`

would be fitted but only one global
preference scale is computed. This feature
allows for the successive fitting of nested models to enable the use of
deviance differences for model selection (see example below).

### Value

`llbtPC.fit`

returns an object of class `llbtMod`

. This object
is basically a `gnm`

object with an additional element `envList`

.
This is a list with further details like the subject covariates
design structure `covdesmat`

, the model specification (`formel`

and `elim`

), the object names (`obj.names`

), the number of
items (`nobj`

) and comparisons (`ncomp`

), etc.

The function `llbt.worth`

can be used to
produce a matrix of estimated worth parameters.

### Input Data

The responses have to be coded as 0/1 for paired comparisons without undecided category (0 means first object in a comparison preferred) or 0/1/2 for paired comparisons with an undecided category (where 1 is the undecided category). Optional subject covariates have to be specified such that the categories are represented by consecutive integers starting with 1. Rows with missing values for subject covariates are removed from the data and a message is printed. The leftmost columns in the data must be the responses to the paired comparisons (where the mandatory order of comparisons is (12) (13) (23) (14) (24) (34) (15) (25) etc.), optionally followed by columns for categorical subject covariates.

The data specified via `obj`

are supplied using either a data frame
or a datafile in which case `obj`

is a path/filename. The input
data file if specified must be a plain text file with variable names in
the first row as readable via the command ```
read.table(datafilename,
header = TRUE)
```

.

For an example see `cemspc`

.

### Note

The function `llbtPC.fit`

is a wrapper function for `gnm`

and
was designed to facilitate fitting of LLBTs with subject covariates and
undecided categories. More specialised setups (e.g., object-specific covariates)
can be obtained using
`llbt.design`

and then calling `gnm`

(or `glm`

)
directly (see Examples for `llbt.design`

).

### Author(s)

Reinhold Hatzinger

### See Also

`llbt.design`

, `pattL.fit`

### Examples

1 2 3 4 5 6 | ```
# cems universities example
res0 <- llbtPC.fit(cemspc, nitems = 6, formel = ~1, elim = ~ENG, undec = TRUE)
res1 <- llbtPC.fit(cemspc, nitems = 6, formel = ~ENG, elim = ~ENG, undec = TRUE)
anova(res1, res0)
llbt.worth(res1)
``` |