llbtPC.fit: Function to fit a loglinear Bradley-Terry model for paired...

View source: R/llbtPC.fit.R

llbtPC.fitR Documentation

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

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 formel is not ~1 then elim will be set to the highest interaction between all terms contained in formel. If elim is specified, the terms must be separated by the * operator.

resptype

is "paircomp" by default and is reserved for future usage. Any other specification will not change the behaviour of llbtPC.fit

obj.names

character vector with names for objects.

undec

for paired comparisons with a undecided/neutral category, a common parameter will be estimated if undec = TRUE.

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

# 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)

prefmod documentation built on June 11, 2022, 3 p.m.