R: Function to fit a pattern model for paired comparisons

pattPC.fit {prefmod}

R Documentation

Function to fit a pattern model for paired comparisons

Description

Function to fit a pattern model for paired comparisons allowing for missing values using a CL approach.

Usage

pattPC.fit(obj, nitems, formel = ~1, elim = ~1, resptype = "paircomp",
    obj.names = NULL, undec = TRUE, ia = FALSE, NItest = FALSE,
    NI = FALSE, MIScommon = FALSE, MISmodel="obj", MISalpha = NULL,
    MISbeta = NULL, pr.it = FALSE)

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 ommitted 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 `pattPC.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`.
`ia`	interaction parameters between comparisons that have one object in common if `ia = TRUE`.
`NItest`	separate estimation of object parameters for complete and incomplete patterns if `NItest = TRUE`. Currently, `NItest` is set to `FALSE` if subject covariates are specified.
`NI`	if `TRUE`, fits large table (crossclassification with NA patterns), for comparison with models including `MISalpha` (and `MISbeta`).
`MIScommon`	if `TRUE`, fits a common parameter for NA indicators, i.e., alpha = alpha_i = alpha_j = ....
`MISmodel`	either `obj` (default) or `comp`. Specifies the model for missing values. If `obj`, parameters for missing objects or if `comp`, parameters for missing comparisons are estimated. In both cases `MISalpha` (and optionally `MISbeta`) specify which parameters are involved.
`MISalpha`	if not `NULL`, specification to fit parameters for NA indicators using a logical vector, where `TRUE` means that the NA indicator parameter for the corresponding object (or comparison, dependent on `MISmodel`) should be estimated (see example below). For `MISmodel="obj"` each comparison is reparameterized with alpha_i + alpha_j, for `MISmodel="comp"` each comparison is reparameterized with α_{ij}.
`MISbeta`	if not `NULL`, fits parameters for MNAR model, i.e., interactions between outcome model parameters and NA indicator parameters. The reparameterization is analogous to `MISalpha`. Usually, the specification for `MISbeta` is the same as for `MISalpha`, but any subset is reasonable. If `MISalpha = NULL` but `MISbeta` is not, then `MISalpha` is set to `MISbeta`.
`pr.it`	a dot is printed at each iteration cycle if set to `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 succesive fitting of nested models to enable the use of deviance differences for model selection (see example below).

Value

pattPC.fit returns an object of class pattMod. The function print (i.e., print.pattMod) can be used to print the results and the function patt.worth to produce a matrix of the estimated worth parameters. An object of class "pattMod" is a list containing the following components:

	main results of the fit like estimates (`coefficients`), log likelihood of the model (`ll`), log likelihood of the saturated model (`fl`), and the call
`result`	a list of results from the fitting routine (see Value of `nlm`).
`envList`	a list with further fit details like subject covariates design structure `covdesmat`, paired comparison reponse pattern matrix `Y`, etc.
`partsList`	a list of the basic data structures for each subgroup defined by crossing all covariate levels and different missing value patterns. Each element of `partsList` is again a list containing counts, missing value pattern, the CL matrix represented as a vector, and the specification of the covariates. Use `str` to inspect the elements and see example below.

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.

Warning

The size of the table to be analysed increases dramatically with the number of objects. For paired comparisons with two response categories the number of rows of the table is 2^(number of comparisons), e.g., with six objects this is 32768, for three response categories this is 14348907. A reasonable maximum number of objects to be analysed with pattern models is 6 in the case of two response categories and 5 when an additional undecided/neutral category has been observed).

Author(s)

Reinhold Hatzinger

Examples

# fit only first three objects with undecided parameter
pattPC.fit(cemspc, nitems = 3, undec = TRUE)

# check for ignorable missing
pattPC.fit(cemspc, nitems = 3, undec = TRUE, NItest = TRUE)

# check if SEX has an effect
m1 <- pattPC.fit(cemspc, nitems = 3, formel = ~1,   elim = ~SEX, undec = TRUE)
m2 <- pattPC.fit(cemspc, nitems = 3, formel = ~SEX, elim = ~SEX, undec = TRUE)

# calculate LR test for SEX
ll1 <- m1$result$minimum
ll2 <- m2$result$minimum
df1 <- length(m1$result$estimate)
df2 <- length(m2$result$estimate)
lr  <- 2*(ll1 - ll2)
df  <- df2 - df1
cat("LR test = ", lr, " on df = ", df, " (p = ",
    round(pchisq(lr, df, lower.tail = FALSE), digits = 5), ")\n", sep="")


# generates data set with three items and some missing values in
# comparison (23), column 3, then there are no NAs for object 1
data3 <- dat4[, 1:3]
idx3  <- sample(1:100, 10)
data3[idx3, 3] <- NA
checkMIS(data3, nitems = 3, verbose = TRUE)

# estimate MNAR PC pattern model for data3 without alpha1 and beta1
pattPC.fit(data3, nitems = 3,
  MISalpha = c(FALSE, TRUE, TRUE),
  MISbeta  = c(FALSE, TRUE, TRUE))

[Package prefmod version 0.8-32 Index]