ddfMLR: DDF detection for nominal data.

Description

Performs DDF detection procedure for nominal data based on multinomial log-linear regression model and likelihood ratio test of submodel.

Usage

ddfMLR(Data, group, focal.name, key, type = "both", match = "zscore", anchor = NULL,
purify = FALSE, nrIter = 10, p.adjust.method = "none", parametrization = "irt",
alpha = 0.05)
# S3 method for ddfMLR
print(x, ...)
# S3 method for ddfMLR
plot(x, item = "all", title, group.names, ...)
# S3 method for ddfMLR
coef(object, SE = FALSE, simplify = FALSE, ...)
# S3 method for ddfMLR
logLik(object, item = "all", ...)
# S3 method for ddfMLR
AIC(object, item = "all", ...)
# S3 method for ddfMLR
BIC(object, item = "all", ...)

Arguments

Data

character: either the unscored data matrix only, or the unscored data matrix plus the vector of group. See Details.

group

numeric or character: either the binary vector of group membership or the column indicator of group membership. See Details.

focal.name

numeric or character: indicates the level of group which corresponds to focal group

key

character: the answer key. See Details.

type

character: type of DDF to be tested (either "both" (default), "udif", or "nudif"). See Details.

match

specifies matching criterion. Can be either "zscore" (default, standardized total score), "score" (total test score), or vector of the same length as number of observations in Data. See Details.

anchor

Either NULL (default) or a vector of item names or item identifiers specifying which items are currently considered as anchor (DDF free) items. Argument is ignored if match is not "zscore" or "score".

purify

logical: should the item purification be applied? (default is FALSE). See Details.

nrIter

numeric: the maximal number of iterations in the item purification (default is 10).

p.adjust.method

character: method for multiple comparison correction. See Details.

parametrization

character: parametrization of regression coefficients. Possible options are "irt" (default) and "classic". See Details.

alpha

numeric: significance level (default is 0.05).

an object of 'ddfMLR' class

...

other generic parameters for print or plot functions.

item

numeric or character: either the vector of column indicator (number or column name) or 'all' (default) for all items. See Details.

title

string: title of plot.

group.names

character: names of reference and focal group.

object

an object of 'ddfMLR' class

logical: should be standard errors also returned? (default is FALSE).

simplify

logical: should the result be simplified to a matrix? (default is FALSE).

Value

A list of class 'ddfMLR' with the following arguments:

Sval: the values of likelihood ratio test statistics.
mlrPAR: the estimates of final model.
mlrSE: standard errors of the estimates of final model.
parM0: the estimates of null model.
parM1: the estimates of alternative model.
alpha: numeric: significance level.
DDFitems: either the column indicators of the items which were detected as DDF, or "No DDF item detected".
type: character: type of DDF that was tested.
purification: purify value.
nrPur: number of iterations in item purification process. Returned only if purify is TRUE.
ddfPur: a binary matrix with one row per iteration of item purification and one column per item. "1" in i-th row and j-th column means that j-th item was identified as DDF in i-1-th iteration. Returned only if purify is TRUE.
conv.puri: logical indicating whether item purification process converged before the maximal number nrIter of iterations. Returned only if purify is TRUE.
p.adjust.method: character: method for multiple comparison correction which was applied.
pval: the p-values by likelihood ratio test.
adj.pval: the adjusted p-values by likelihood ratio test using p.adjust.method.
df: the degress of freedom of likelihood ratio test.
group: the vector of group membership.
Data: the data matrix.
match: matching criterion.
group.names: levels of grouping variable.
llM0: log-likelihood of null model.
llM1: log-likelihood of alternative model.
AICM0: AIC of null model.
AICM1: AIC of alternative model.
BICM0: BIC of null model.
BICM1: BIC of alternative model.

Details

Performs DDF detection procedure for nominal data based on multinomial log-linear regression model and likelihood ratio test of submodel.

The Data is a matrix which rows represents examinee unscored answers and columns correspond to the items. The group must be either a vector of the same length as nrow(Data) or column indicator of Data. The key must be a vector of correct answers corresponding to columns of Data.

The type corresponds to type of DDF to be tested. Possible values are "both" to detect any DDF (uniform and/or non-uniform), "udif" to detect only uniform DDF or "nudif" to detect only non-uniform DDF.

Argument match represents the matching criterion. It can be either the standardized test score (default, "zscore"), total test score ("score"), or any other continuous or discrete variable of the same length as number of observations in Data.

A set of anchor items (DDF free) can be specified through the anchor argument. It need to be a vector of either item names (as specified in column names of Data) or item identifiers (integers specifying the column number). In case anchor items are provided, only these items are used to compute matching criterion match. If the match argument is not either "zscore" or "score", anchor argument is ignored. When anchor items are provided, purification is not applied.

The p.adjust.method is a character for p.adjust function from the stats package. Possible values are "holm", "hochberg", "hommel", "bonferroni", "BH", "BY", "fdr", "none". See also p.adjust for more information.

Argument parametrization is a character which specifies parametrization of regression parameters. Default option is "irt" which returns IRT parametrization (difficulty-discrimination). Option "classic" returns intercept-slope parametrization with effect of group membership and interaction with matching criterion.

The output of the ddfMLR function is displayed by the print.ddfMLR function.

The characteristic curve for item specified in item option can be plotted. item can be column indicator (numeric or character - column name) or "all" (default). For option "all", characteristic curves of all converged items are plotted. The drawn curves represent best model.

Missing values are allowed but discarded for item estimation. They must be coded as NA for both, Data and group parameters.

Examples

Run this code

# NOT RUN {
# loading data based on GMAT
data(GMATtest, GMATkey)

Data  <- GMATtest[, 1:20]
group <- GMATtest[, "group"]
key <- GMATkey

# Testing both DDF effects
(x <- ddfMLR(Data, group, focal.name = 1, key))

# Testing both DDF effects with Benjamini-Hochberg adjustment method
ddfMLR(Data, group, focal.name = 1, key, p.adjust.method = "BH")

# Testing both DDF effects with item purification
ddfMLR(Data, group, focal.name = 1, key, purify = T)

# Testing uniform DDF effects
ddfMLR(Data, group, focal.name = 1, key, type = "udif")
# Testing non-uniform DDF effects
ddfMLR(Data, group, focal.name = 1, key, type = "nudif")

# Testing both DDF effects with total score as matching criterion
ddfMLR(Data, group, focal.name = 1, key, match = "score")

# Testing both DDF effects using classic parametrization
ddfMLR(Data, group, focal.name = 1, key, parametrization = "classic")

# Graphical devices
plot(x, item = 1)
plot(x, item = 1, group.names = c("Group 1", "Group 2"))
plot(x, item = x$DDFitems)
plot(x, item = "all")

# AIC, BIC, log-likelihood
AIC(x); BIC(x); logLik(x)
# AIC, BIC, log-likelihood for the first item
AIC(x, item = 1); BIC(x, item = 1); logLik(x, item = 1)

# estimates
coef(x)
coef(x, SE = TRUE)
coef(x, SE = TRUE, simplify = TRUE)
# }
# NOT RUN {
# }