pleLMA (version 0.2.1)

ple.lma: Main function for estimating parameters of LMA models

Description

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

Usage

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)

Value

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

# NOT RUN {
#--- some data, 3 items from dpression, 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)

# }
# NOT RUN {
#--- 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)
# }
# NOT RUN {

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

# }
# NOT RUN {
#--- 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)
# }
# NOT RUN {
# }