Create several models by splitting the qMatrix and/or person.groups

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

Usage

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 )

Arguments

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 and their consequences:

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 in ascending order

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 in giga bytes

verbose

logical (default: TRUE), print progress

Value

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

Author

Martin Hecht

Examples