splitModels: Create several models by splitting the qMatrix and/or...
In eatModel: Educational Assessment Tools for IRT Modeling using Conquest or TAM

Description Usage Arguments Value Author(s) See Also Examples

defineModel is programmed to define a single model. With splitModels several models can be set up. The output of splitModels can be directly passed to the splittedModels argument of defineModel

splitModels ( qMatrix = NULL , person.groups = NULL , 
    split = c ( "qMatrix" , "person.groups" ) , add = NULL , cross = NULL , 
    all.persons = TRUE , all.persons.lab = "all" , 
    person.split.depth = 0:length(person.groups[,-1,drop=FALSE]) , 
    full.model.names = TRUE , model.name.elements = c ( "dim" , "group" , "cross" ) , 
    include.var.name = FALSE , env = FALSE , nCores=NULL , mcPackage = c("future", "parallel"),
    GBcore=NULL , verbose = TRUE )

`qMatrix`	Same argument as in `defineModel`: Optional: A named data frame indicating how items should be grouped to dimensions. The first column contains the names of all items and should be named item. The other columns contain dimension definitions and should be named with the respective dimension names. A positive value (e.g., 1 or 2 or 1.4) indicates the loading weight with which an item loads on the dimension, a value of 0 indicates that the respective item does not load on this dimension. If no q matrix is specified by the user, an unidimensional structure is assumed.
`person.groups`	data.frame, first row must be person ID, further columns contain group categories, e.g. data.frame ( "id" = 1:10 , "sex" = sample ( c ( "male" , "female" ) , 10 , replace = TRUE ) )
`split`	character, possible values: NULL : qMatrix and person.groups are not split, one model with original qMatrix and all persons is set up "qMatrix" : qMatrix is split into single dimensions, number of created models equals number of dimensions "person.groups" : person.groups is split into single groups, number of created models equals number of all combinations of groups (with at least one person) c("qMatrix","person.groups") : default, both qMatrix and person.groups is split and single dimensions and single groups are crossed, number of created models equals number of dimension multiplied with number of all combinations of groups
`add`	list of elements with single values, names of elements should be arguments of `defineModel`, elements are the value that is passed when running `defineModel`; elements in `add` are used for all models; e.g. list ( "software" = "conquest" , "nodes" = 15 ), that means that all models are estimated with "conquest" and 15 nodes
`cross`	list of elements with several values, names of elements should be arguments of `defineModel`, elements are the value that is passed when running `defineModel`; elements in `cross` are crossed into models; e.g. list ( "software" = c("conquest","tam") , "nodes" = c(15,30) ), now all models are set up to run once with "conquest" and once with "tam", and with 15 and 30 nodes
`all.persons`	logical (default: TRUE), for each group variable in `person.groups` an "all" category is included
`all.persons.lab`	character, name of the "all" category
`person.split.depth`	integer, depth of group splits, 0: global all persons are included, 1: groups of all variables are included, 2: groups of all pairs of variables are included, n: groups of n variables are included. Can be a vector with more than one argument, e.g. for 3 variables, the full number of splits (which is also the default) can be obtained by c(0,1,2,3); this creates a model with all persons (0), all groups of all variables (1), groups from pairs of variables (2), and groups from combining all 3 variables (3). Using `person.split.depth` usually makes most sense if `all.persons=TRUE`; if `all.persons=FALSE` the depth equals the number of variables (if another depth is set, no splits will be performed).
`full.model.names`	logical (default: TRUE), model names are derived from `model.name.elements`; if FALSE models are numbered ascendingly
`model.name.elements`	character, elements that model names are built of, possible values: "dim" , "group" , "add" , "cross"; default: c ( "dim" , "group" , "cross" ) , that means that model names include the name of the dimension(s) , group(s) , and parameter values that are crossed in
`include.var.name`	logical (default: FALSE), include the name of the variable when building model names; e.g. (FALSE) "science__sex.female__conquest" , (TRUE) "dim.science__group.sex.female__software.conquest"
`env`	logical (default: FALSE) (FALSE) returns a list with two elements: data.frame with model information (model overview), list with model specifications (TRUE) returns a list with two elements: data.frame with model information (model overview), list of environments with model specifications set as objects for intended subsequent use with `defineModel` use `env=FALSE`
`nCores`	integer (default: NULL), number of cores to use for subsequent data preparation, model estimation and results compilation
`mcPackage`	Which package should be used for local host definition in multicore processing? If R version < 3.4, `"parallel"` is recommended. If R version >= 3.4, `"future"` is recommended.
`GBcore`	numeric (default: NULL), maximum RAM usage per core
`verbose`	logical (default: TRUE), print progess

depending on env either:

(env=FALSE) returns a list with two elements: data.frame with model information (model overview), list with model specifications (env=TRUE) retuns a list with two elements: data.frame with model information (model overview), list of environments with model specifications set as objects

for intended subsequent use with defineModel use env=FALSE

Martin Hecht

defineModel

# see also examples in 'defineModel'
# example qMatrix
qMatrix <- data.frame ( "item" = 1:4 , "science" = c(1,1,0,0) , "math" = c(0,0,1,1) , stringsAsFactors = FALSE )

# example person.groups
person.groups <- data.frame ( "person" = 1:4 , "state" = rep(c("Berlin","Bavaria"),2) , "sex" = c(rep("female",2),rep("male",2)) , stringsAsFactors = FALSE )

# Example 1: one 2-dimensional model with all persons (no split)
m01 <- splitModels ( qMatrix=qMatrix, person.groups=person.groups, split=NULL )
m01$models

# Example 2: split qMatrix to create two unidimensional models, each with all persons
m02 <- splitModels ( qMatrix=qMatrix, person.groups=person.groups, split=c("qMatrix") )
m02$models

# Example 3: split person.groups to create 2-dimensional models, each with a subgroup of persons
m03 <- splitModels ( qMatrix=qMatrix, person.groups=person.groups, split=c("person.groups") )
m03$models

# Example 4: split both qMatrix and person.groups to create unidimensional models for all subgroups
m04 <- splitModels ( qMatrix=qMatrix, person.groups=person.groups, split=c("qMatrix","person.groups") )
m04$models

# Example 5: set "software"="conquest" and "method"="montecarlo" for all models
m05 <- splitModels ( qMatrix=qMatrix, person.groups=person.groups , add = list ( "software"="conquest" , "method"="montecarlo" ) )
m05$models

# Example 6: cross "nodes"=c(1000,5000) and "seed"=c(1234,4321) into all models
m06 <- splitModels ( qMatrix=qMatrix, person.groups=person.groups , add = list ( "software"="conquest" , "method"="montecarlo" ) , cross = list ( "nodes"=c(1000,5000) , "seed"=c(1234,4321) ) )
m06$models

# Example 7: list elements in cross that contain more than one element need to be lists themselves
m07 <- splitModels ( qMatrix=qMatrix, person.groups=NULL , cross = list ( "regression"=list( c("sex") , c("sex","state") ) , "seed"=c(1234,4321) ) )
m07$models

# Example 8: create an "empty" model without qMatrix and person.groups
m08 <- splitModels ( qMatrix=NULL, person.groups=NULL )
m08$models