# Main function for estimating parameters of LMA models This function is a wrapper function that checks for errors in the input (i.e., `error.check'), sets up required objects and data (i.e., `set.up'), calls function to fit specified model (either `fit.independence', fit.rasch', `fit.gpcm', or `fit.nomial'), and outputs an extensive list of details and results. The required input for all models consist of a data frame where elements are consecutive integers (1, 2, ...) indicating the category chosen by each case/individual (rows) for each variable (columns), and the model type. For the LMA models that correspond to item response theory models require an Item x Trait adjacency matrix (`inItemTraitAdj') and a Trait x Trait adjacency matrix (`inTraitAdj'). Optional input include the tolerance value (`tol') which is used to for determine whether the pseudo-likelihood algorithm has converged for a gpcm or nominal model default=1e-6). Additional optional input (`starting.sv') is an item by category a matrix of starting scale values for the nominal model or fixed category scores for the gpcm and rasch models. The default category scale values/scores are eqaully spaced, centered at zero, and the sum of squared values equals 1. The final optional input is a trait x trait (`starting.phi') matrix of starting values for the association parameter matrix (default= identity matrix). ```r ple.lma( inData, model.type, inItemTraitAdj = NULL, inTraitAdj = NULL, tol = NULL, starting.sv = NULL, starting.phi = NULL ) ``` ## Arguments - `inData`: A person x item data matrix or data frame with elements equal to reponse options choosen by an individual. - `model.type`: Model to be fit (nominal, gpcm, rasch, independence) to data. - `inItemTraitAdj`: An Item x Trait adjacency matrix indicating what trait an item loads on. - `inTraitAdj`: A Trait x Trait adjacency matrix indicating relationship among traits. - `tol`: Convergence criterion, default = 1e-6 - `starting.sv`: Starting category scale values/fixed scores - `starting.phi`: Starting matrix of phi parameters (i.e., conditional covariance matrix) ## Returns model.type The model (nominal, gpcm, rash, or independence) that was fit to data TraitByTrait The Trait x Trait adjacency matrix used. ItemByTrait The Item x Trait adjacency matrix. item.by.trait One dimensional version of ItemByTrait that gives the number of trait. ItemNames Names of items in inData PhiNames Names of the association parameters (i.e., phi) formula.item Formula used to up-date item parameters via item regressions. formula.phi Formula used to up-date association parameters via stacked regression. npersons Number of persons in data set. nitems Number of items. ncat Number of categories per item. nless Number of unique marginal effects & unique scale values. Maxnphi Number of association parameters estimated. ntraits Number of traits. starting.sv Starting scale values for nominal model or fixed scores for rasch or gpcm. tol Used to determine convergence default= 1e-7 criterion Final value criterion at convergence item.log Item iteration history plus maximum of the LogLike for each item phi.log Assocation parameter iteration history estimates Item x Parameter matrix where 1st column is max LogLike for each item and remaining columns are item parameter estimate Phi.mat Estimated conditional correlation matrix item.mlogit Output from final mlogit fit to items phi.mlogit Output form final mlogit fit to stacked data mlpl.item Max Log(pseudo-likelihood) function from item models (i.e. sum of first column of estimates) mlpl.phi Max Log(pseudo-likelihood) function from stacked regression(s). AIC Akaike information criterion for pseudo-likelihood (smaller is better) BIC Bayesian information criterion for pseudo-likelihood (smaller is better) ## Examples ```r #--- some data, 3 items from depression, anxiety and stress scales # and only 250 cases out of possible 1000 data(dass) inData <- dass[1:250,c("d1", "d2", "d3", "a1","a2","a3","s1","s2","s3")] #--- log-linear model of independence ind <- ple.lma(inData, model.type="independence") #--- input for uni-dimensional inTraitAdj <- matrix(1, nrow=1, ncol=1) inItemTraitAdj <- matrix(1, nrow=9, ncol=1) #--- rasch family r1 <- ple.lma(inData, model.type="rasch", inItemTraitAdj, inTraitAdj) #--- rasch with alternative scores scores <- matrix(c(0,1,2,3),nrow=9,ncol=4,byrow=TRUE) r1b <- ple.lma(inData, model.type="rasch", inItemTraitAdj, inTraitAdj, starting.sv=scores) #--- generalized partial credit model g1 <- ple.lma(inData, model.type="gpcm", inItemTraitAdj, inTraitAdj) #--- gpcm with alternative scores scores <- matrix(c(0,1,2,3),nrow=9,ncol=4,byrow=TRUE) g1b <- ple.lma(inData, model.type="gpcm", inItemTraitAdj, inTraitAdj, starting.sv=scores) #--- nominal response model n1 <- ple.lma(inData, model.type="nominal", inItemTraitAdj,inTraitAdj) #--- re-run nominal model with input starting values and phi # and setting stronger convergnce criterion. sv <- n1$estimates[, 6:9] phi <- n1$Phi.mat n1b <- ple.lma(inData, model.type="nominal", inItemTraitAdj, inTraitAdj, starting.sv=sv, starting.phi=phi, tol=1e-8) #--- Multidimensional models #--- re-define inTraitAdj and inItemTraitAdj for 3 dimensional models inTraitAdj <- matrix(1, nrow=3, ncol=3) dpress <- matrix(c(1,0,0), nrow=3, ncol=3, byrow=TRUE) anxiety <- matrix(c(0,1,0), nrow=3, ncol=3, byrow=TRUE) stress <- matrix(c(0,0,1), nrow=3, ncol=3, byrow=TRUE) das <- list(dpress, anxiety, stress) inItemTraitAdj <- rbind(das[[1]], das[[2]], das[[3]]) #--- 3 dimensional rasch r3 <- ple.lma(inData, model.type="rasch", inItemTraitAdj, inTraitAdj) #--- 3 dimensional gpcm g3 <- ple.lma(inData, model.type="gpcm", inItemTraitAdj, inTraitAdj) #--- 3 dimensional nominal n3 <- ple.lma(inData, model.type="nominal", inItemTraitAdj, inTraitAdj) #--- 2 parameter logistic IRT model fit to responses to # 10 dichotomous Vocabulary items from from 2018 GSS # by 1309 respondents data(vocab) inItemTraitAdj <- matrix(1, nrow=10, ncol=1) inTraitAdj <- matrix(1, nrow=1, ncol=1) #--- rasch irt rasch <- ple.lma(inData=vocab, model.type="rasch", inItemTraitAdj, inTraitAdj, tol=1e-03) #--- 2 pl as a gpcm model g.2pl <- ple.lma(inData=vocab, model.type="gpcm", inItemTraitAdj, inTraitAdj, tol=1e-03) #--- 2 pl as a nominal model n.2pl <- ple.lma(inData=vocab, model.type="nominal", inItemTraitAdj, inTraitAdj, tol=1e-03) ```

ple.lma function