difNLR (version 1.3.0)

ddfORD: DDF detection for ordinal data.

Description

Performs DDF detection procedure for ordinal data based either on adjacent category logit model or on cumulative logit model and likelihood ratio test of submodel.

Usage

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

Arguments

Data

matrix or data.frame: the ordinarily scored data matrix only or the ordinarily scored 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

model

character: logistic regression model for ordinal data (either "adjacent" (default) or "cumulative"). 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).

x

an object of 'ddfORD' class

...

other generic parameters for print function.

object

an object of 'ddfORD' class

SE

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

simplify

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

item

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

title

string: title of plot.

plot.type

character: which plot should be displayed for cumulative logistic regression model. Either "category" for category probabilities or "cumulative" for cumulative probabilities.

group.names

character: names of reference and focal group.

Value

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

Sval

the values of likelihood ratio test statistics.

ordPAR

the estimates of the final model.

ordSE

standard errors of the estimates of the final model.

parM0

the estimates of null model.

parM1

the estimates of alternative model.

model

model used for DDF detection.

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.

parametrization

Parameters' parametrization.

Details

DDF detection procedure for ordinal data based either on adjacent category logit model or on cumulative logit model.

The Data is a matrix or data.frame which rows represents examinee ordinarily scored 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 model corresponds to model to be used for DDF detection. Options are "adjacent" for adjacent category logit model or "cumulative" for cumulative logit model.

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", and "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 ddfORD() function is displayed by the print.ddfORD function.

The characteristic curve for item specified in item option can be plotted. For default option "all" of item, 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.

References

Agresti, A. (2010). Analysis of ordinal categorical data. Second edition. John Wiley & Sons.

See Also

p.adjust vglm

Examples

# NOT RUN {
# loading data
data(dataMedicalgraded, package = "ShinyItemAnalysis")
Data <- dataMedicalgraded[, 1:5]
group <- dataMedicalgraded[, 101]

# Testing both DDF effects with adjacent category logit model
(x <- ddfORD(Data, group, focal.name = 1, model = "adjacent"))

# graphical devices
plot(x, item = 3)
plot(x, item = "X2003")
plot(x, item = "X2003", group.names = c("Group 1", "Group 2"))

# estimated parameters
coef(x)
coef(x, SE = T) # with SE
coef(x, SE = T, simplify = T) # with SE, simplified

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

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

# Testing both DDF effects with item purification
ddfORD(Data, group, focal.name = 1, model = "adjacent", purify = T)

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

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

# Testing both DDF effects with cumulative logit model
# using IRT parametrization
(x <- ddfORD(Data, group, focal.name = 1, model = "cumulative", parametrization = "irt"))

# graphical devices
plot(x, item = 3, plot.type = "cumulative")
plot(x, item = 3, plot.type = "category")

# estimated parameters in IRT parametrization
coef(x, simplify = T)
# }
# NOT RUN {
# }