flirt: Uni- and Multi- dimensional Item Response Theory Analysis
In seonghobae/flirt.x32: Flexible Item Response Theory Modeling

Description Usage Arguments Details Value Author(s) See Also Examples

Maximum likelihood estimation of item response theory (IRT) models for binary and polytomous data

flirt(data, select=NULL, subset=NULL, loading=list(on=FALSE, inside=FALSE), 
    mul=list(on=FALSE, dim_info=NULL, cov_info=NULL), 
    bifac=list(on=FALSE, dim_info=NULL, cov_info=NULL), 
    second=list(on=FALSE, dim_info=NULL, cov_info=NULL), 
    guess=list(on=FALSE), 
    person_cov=list(on=FALSE, person_matrix=NULL, main=NULL), 
    item_cov=list(on=FALSE, item_matrix_beta=NULL, item_matrix_alpha=NULL), 
    dif=list(on=FALSE, dif_beta=NULL, dif_alpha=NULL), 
    mg=list(on=FALSE, group_matrix=NULL), mixture =list(on=FALSE, num=NULL), 
    weight=list(on=FALSE, weight_matrix=NULL), post=FALSE, 
    start = list(on=FALSE, npar=NULL, start_info=NULL, start_value=NULL), 
    constraint = list(on=FALSE, npar=NULL, cons_info=NULL, cons_value=NULL), 
    evaluate = list(on=FALSE, eval_value=NULL), 
    control=list(minpercent= NULL, max_it=NULL, nq=NULL, conv=NULL, 
            link=NULL, adapt=NULL, se_num=NULL, se_emp=NULL, alp_bounds_up=NULL,
            verbose=NULL, show=NULL) )

`data`	matrix or data.frame in wide form - persons in rows and items in columns. Group membership, person covariates and sampling weights may be included as additional columns
`select`	vector of item numbers or item names. If data include other than item responses or the user wants to analyze only subset of items, `select` should be specified.
`subset`	vector of names or numbers of cases (rows) of choice.
`loading`	list. on: logical. if `TRUE`, a 2PL model family, if `FALSE`, a 1PL model family (default) is used. inside: logical. When on==`TRUE`, if inside==`TRUE`, α_i(θ_p+ β_i) parameterization, if `FALSE`, α_i θ_p + β_i parameterization (default) is used.
`mul`	list. on: if `TRUE`, a multidimensional model, if `FALSE`, a unidimensional model (default) is used. dim_info: list. If on==`TRUE`, a list of item numbers or columns for each dimension should be provided. cov_info: matrix or data.frame. If there are person covariates, cov_info should be provided, which indicates which covariates are used in each dimension.
`bifac`	list. on: logical. If `TRUE`, bifactor model, if `FALSE`, unidimensional model (default). dim_info: list. If on==`TRUE`, list of item numbers or columns for each dimension should be provided. cov_info: matrix or data.frame. If there are person covariates, cov_info should be provided, which indicates which covariates are used in each dimension.
`second`	list. on: logical. If `TRUE`, second-order (testlet) model, if `FALSE`, unidimensional model (default). dim_info: list. If on==`TRUE`, list of item numbers or columns for each dimension should be provided. cov_info: matrix or data.frame. If there are person covariates, cov_info should be provided, which indicates which covariates are used in each dimension.
`guess`	list. on: logical. If `TRUE`, a 3PL model is estimated (α_i, β_i, and c_i parameters), if `FALSE`, only β_i parameters are estimated (default is 1PL models).
`person_cov`	list. on: logical. If `TRUE`, person covariates columns (or names) or the data matrix should be provided in person_matrix. person_matrix: column numbers or variable names if part of data, otherwise, matrix or data.frame for the person covariates. Number and order of rows should be the same as those in data. If `subset` is used, the number of rows should be adjusted accordingly. main: logical. If main==`TRUE`, person covariates are treated as main effects in the linear predictor instead of as predictors of a latent regression model. Default is main==`FALSE`.
`item_cov`	list. on: logical. If `TRUE`, data matrix for item covariates should be provided either for β_i or α_i. item_matrix_beta: matrix or data.frame for item covariates that are regressed on β_i. Number of rows should be the same as the number of items. If `select` is used, the number of rows should be adjusted accordingly. item_matrix_alpha: matrix or data.frame for item covariates that are regressed on α_i. Number of rows should be the same as the number of items. If this option is used, standard errors are not estimated. If `select` is used, the number of rows should be adjusted accordingly.
`dif`	list. on: logical. If `TRUE`, DIF analysis is performed. `FALSE` is default. dif_beta: vector. Item numbers or variable names for DIF for β_i. dif_alpha: vector. Item numbers or variable names for DIF for α_i.
`mg`	list. on: logical. If `TRUE`, multiple-group analysis is performed. `FALSE` is default. group_matrix: column number or variable name for person membership if part of data, otherwise data.matrix should be provided in group_matrix. Number and order of rows should be the same as those in data. If `subset` is used, the number of rows should be adjusted accordingly. Persons should be ordered by groups.
`mixture`	list. on: logical. If `TRUE`, mixture model is specified (currently, not available). num: logical. If on==`TRUE`, number of latent classes should be provided.
`weight`	list. on: logical. If `TRUE`, sampling or frequency weights are included. `FALSE` is default. weight_matrix: if on==`TRUE`, column number or variable name if part of data, otherwise data.matrix for weights should be provided. Number and order of rows should be the same as those in data. If `subset` is used, the number of rows should be adjusted accordingly.
`post`	logical. if `TRUE`, expected a posteriori (EAP) (and its variance and covariance), expected sum-scores, and IRT reliability are provided. `FALSE` is default.
`start`	on: logical. If `TRUE`, use-specified starting values are used; otherwise, random starting values are used (default). npar: integer of the total number of parameters. start_info: vector of the parameter numbers for starting values to be used. start_value: vector of the starting values for the specified parameters in `start_info`.
`constraint`	on: logical. If `TRUE`, users can specify parameter constraints. `FALSE` is default. npar: integer of the total number of parameters. cons_info: vector of the parameter numbers to be constrained. cons_value: vector of the specific values for the specified parameters to be fixed at.
`evaluate`	on: logical. If `TRUE`, log-likelihood is evaluated at given parameter values. `FALSE` is default. eval_value: vector of parameter values where the log-likelihood is evaluated at.
`control`	list of control options with components: minpercent: positive real value. Minimum percentage for a response category for polytomous items. If the relative frequency for a category is lower than minpercent, that category is collapsed into the lower adjacent category. Default is 0. To see how the category is collapsed, put the control option show=`TRUE`. max_it: positive integer. Maximum number of iterations. Default is 10,000. nq: positive integer. Numbers of quadrature points. Default is 20. For multidimensional and bifactor models, a vector of quadrature points for each dimension in order (dimension 1, dimension 2, and so on for multidimensional models; general dimension, specific dimension 1, specific dimension 2, and so on for bifactor models). If a scalar is specified, the specified number is used for all dimensions. conv: positive real value. Convergence criterion. The iteration between EM estimations stops when the maximum absolute difference in the parameter estimates becomes equal or smaller than the criterion between two subsequent iterations. Default is 0.0001. link: positive integer 1, 2, or 3. or "multinomial", "cumulative", "adjacent". Default is multinomial or 1 for binary data (that leads to logit link) and "adjacent" for polytomous data. adapt: logical. If `TRUE`, adaptive quadrature is used. if `FALSE`, Gauss-Hermite quadrature is used (default). se_num: logical. If `TRUE`, standard error estimates are computed using the Hessian matrix obtained by numerical differentiation. se_emp: logical. If `TRUE`, standard error estimates are computed using an empirical information matrix.(default) If se_num is `TRUE`, standard errors are computed using this method are contained as extra attributes. If se_emp is `FALSE`, these standard errors are used as default standard errors. alp_bounds_up: positive integer. Upper boundary value (positive) for α_i. Default is 15. Cannot be used when item covariates are regressed on α_i. alp_bounds_low: positive integer. Lower boundary value for α. Default is -1. Cannot be used when item covariates are regressed on α_i. verbose: logical. If `TRUE`, the iteration number, the maximum absolute difference in the parameter estimates (par_diff) and difference in the log-likelihood (lik_diff) between adjacent iterations are printed. show: logical. If `TRUE`, print Matlab output (error messages) on R console.

Parameterization: For a linear predictor flirt uses θ_p + β_i for 1PL models, α_i(θ_p + β_i) or α_i θ_p + β_i for 2PL models, and α_{ig} θ_{pg} +α_{is} θ_{ps} + β_i for bifactor and second-order models, where θ_p is the ability of a person p, β_i is the item easiness (or intercept), α_i is the loading (or slope), and θ_{pg} and θ_{ps} are abilities for the general g and specific dimension s with α_{ig} and α_{is}, respectively. For 3PL models, the guessing parameter c_i is incorporated in the probability, P_i = c_i + \frac{(1-c_i)}{1+ exp(-(α_i θ_p + β_i))}. For second-order models, α_{ig}/ α_{is} is the second-order loading for the sth first-order factor on the second-order factor θ_{pg}, which is constant for the items within sth first-order factor.
Polytomous item responses: Minimum category should be 0.
Multiple group analysis: Group membership should start from 0.
Standard errors: For variance-covariance parameters, standard errors are not provided and NA is returned. For parameters that are constrained, standard errors are not calculated and NA is returned.
Starting values, evaluation: Parameter values (to be fixed at) for variance-covariance parameters should be Cholesky elements of lower triangular matrix L (Cov = LL' )
Boundary values: The maximum boundary values for parameters are set to \pm 15. The upper and lower boundary values for α_i can be modified using the control options alp_bounds_up and alp_bounds_low. If a parameter estimate crosses the boundary value during iterations, the parameter estimate is automatically restricted to the boundary value and no parameter and standard error estimates are provided with a warning message.
Missing values: Missing values should be specified as NA. Missing values in item responses and item design matrices are treated as ignorable, but for missing values in person design, person group, and weight matrices, listwise deletion is used.

An object of class flirt, with the following slots that can be extracted using object@

`pars`	matrix of parameters estimates and standard errors
`parms`	original parameter estimates from BNLflirt (including cholesky estimates for multidimensional models)
`info_num`	information matrix (numerical) evaluated at the maximum likelihood estimates
`se_emp`	standard errors using empirical information matrix (if used)
`info_emp`	information matrix (empirical) evaluated at the maximum likelihood estimates (if used)
`loglik`	log-likelihood value at convergence
`AIC`	Akaike information criterion: -2loglik+2npar, where npar is number of parameters
`BIC`	Bayesian information criterion: -2loglik+nparlog(nobs), where nobs is number of cases (persons)
`npar`	number of parameters
`post`	post analysis with a list of eap: expected a posteriori (EAP) ability estimate(s) eap_var: variances of expected a posteriori (EAP) ability estimate(s) eap_cov: covariance matrix of expected a posteriori (EAP) ability estimate(s) exp_s: expected scores rel: IRT reliability using empirical priors
`data_inf`	data information with a list of nobs: number of people ngroup: number of groups nitem: number of items MS_item:maximum category of items (scalar) S_item:categories of all items (vector)
`dim_inf`	dimension information with a list of within: within-item model:1, otherwise:0 ndim: number of dimensions n_it_dim: number of items in each dimension
`inside`	inside:1, otherwise:0 (2PL parameterization)
`model`	1:unidimensional 1PL model family, 2:unidimensional 2PL model family, 3: multidimensional 1PL model family, 4: multidimensional 2PL model family, 5: bifactor model family
`dif_beta`	items that are under investigation for DIF for β_i
`dif_alpha`	items that are under investigation for DIF for α_i
`est_inf`	estimation information with a list of adapt: adaptive quadrature nqr: number of quadrature points conv: convergence criterion max_it: total number of iterations link: link function verbose: verbose alp_bounds_up: upper boundary value for α_i alp_bounds_low: lower boundary value for α_i

Minjeong Jeon <jeon.117@osu.edu>

summary, coef, logLik, anova

# set directory where the .tar is located. 
install.packages("flirt", type="source", repos=NULL) 
library(flirt)

# show built-in datasets 
data(package="flirt")

# with adjacent link function (partial credit model)
result1 <- flirt(data=charity, subset=1:100, 
        control=list(minpercent=0.05, nq=5, link="adjacent", show=TRUE))

## verbal aggression data
data(verb2)

# 2-dimensional 2PL model for binary data 
# with a(th+b) parameterization
result2 <- flirt(data=verb2, select=2:25,  
            mul=list(on=TRUE, dim_info=list(dim1=1:12, dim2=13:24))  )

# output 
result2
summary(result2)
coef(result2)
logLik(result2)


# 1PL graded response model for polytomous responses 
# with cumulative link function (graded response model)
data(charity)
result3 <- flirt(data=charity, subset=1:100, 
        control=list(minpercent=0.05, nq=5, link="cumulative", show=TRUE))