bruteforce {stuart}

Subtest construction using a brute-force approach

Description

Construct subtests from a given pool of items using a brute-force approach (i.e. by estimating all possible combinations).

Usage

bruteforce(
  data,
  factor.structure,
  capacity = NULL,
  item.invariance = "congeneric",
  repeated.measures = NULL,
  long.invariance = "strict",
  mtmm = NULL,
  mtmm.invariance = "configural",
  grouping = NULL,
  group.invariance = "strict",
  comparisons = NULL,
  auxiliary = NULL,
  use.order = FALSE,
  software = "lavaan",
  cores = NULL,
  objective = NULL,
  ignore.errors = FALSE,
  analysis.options = NULL,
  suppress.model = FALSE,
  request.override = 10000,
  filename = NULL
)

Arguments

data

A data.frame containing all relevant data.

factor.structure

A list linking factors to items. The names of the list elements correspond to the factor names. Each list element must contain a character-vector of item names that are indicators of this factor.

capacity

A list containing the number of items per subtest. This must be in the same order as the factor.structure provided. If a single number, it is applied to all subtests. If NULL all items are evenly distributed among the subtests.

item.invariance

A character vector of length 1 or the same length as factor.structure containing the desired invariance levels between items pertaining to the same subtest. Currently there are five options: 'congeneric', 'ess.equivalent', 'ess.parallel', 'equivalent', and 'parallel', the first being the default.

repeated.measures

A list linking factors that are repeated measures of each other. Repeated factors must be in one element of the list - other sets of factors in other elements of the list. When this is NULL (the default) a cross-sectional model is estimated.

long.invariance

A character vector of length 1 or the same length as repeated.measures containing the longitudinal invariance level of repeated items. Currently there are four options: 'configural', 'weak', 'strong', and 'strict'. Defaults to 'strict'. When repeated.measures=NULL this argument is ignored.

mtmm

A list linking factors that are measurements of the same construct with different methods. Measurements of the same construct must be in one element of the list - other sets of methods in other elements of the list. When this is NULL (the default) a single method model is estimated.

mtmm.invariance

A character vector of length 1 or the same length as mtmm containing the invariance level of MTMM items. Currently there are five options: 'none', 'configural', 'weak', 'strong', and 'strict'. Defaults to 'configural'. With 'none' differing items are allowed for different methods. When mtmm=NULL this argument is ignored.

grouping

The name of the grouping variable. The grouping variable must be part of data provided and must be a numeric variable.

group.invariance

A single value describing the assumed invariance of items across groups. Currently there are four options: 'configural', 'weak', 'strong', and 'strict'. Defaults to 'strict'. When grouping=NULL this argument is ignored.

comparisons

A character vector containing any combination of 'item', 'long', 'mtmm', and 'group' indicating which invariance should be assessed via model comparisons. The order of the vector dictates the sequence in which model comparisons are performed. Defaults to NULL meaning that no model comparisons are performed.

auxiliary

The names of auxiliary variables in data. These can be used in additional modeling steps that may be provided in analysis.options$model.

use.order

A logical indicating whether or not to take the selection order of the items into account. Defaults to FALSE.

software

The name of the estimation software. Can currently be 'lavaan' (the default), 'Mplus', or 'Mplus Demo'. Each option requires the software to be installed.

cores

The number of cores to be used in parallel processing. If NULL (the default) the result of detectCores will be used. On Unix-y machines parallel processing is implemented via mclapply, on Windows machines it is realized via parLapply.

objective

A function that converts the results of model estimation into a pheromone. See mmas for details.

ignore.errors

A logical indicating whether or not to ignore estimation problems (such as non positive-definite latent covariance matrices). Defaults to FALSE.

analysis.options

A list additional arguments to be passed to the estimation software. The names of list elements must correspond to the arguments changed in the respective estimation software. E.g. analysis.options$model can contain additional modeling commands - such as regressions on auxiliary variables.

suppress.model

A logical indicating whether to suppress the default model generation. If TRUE a model must be provided in analysis.options$model.

request.override

The maximum number of combinations for which the estimation is performed immediately, without an additional override request.

filename

The stem of the filenames used to save inputs, outputs, and data files when software='Mplus'. This may include the file path. When NULL (the default) files will be saved to the temporary directory, which is deleted when the R session is ended.

Details

The pheromone function provided via objective is used to assess the quality of the solutions. These functions can contain any combination of the fit indices provided by the estimation software. When using Mplus these fit indices are 'rmsea', 'srmr', 'cfi', 'tli', 'chisq' (with 'df' and 'pvalue'), 'aic', 'bic', and 'abic'. With lavaan any fit index provided by inspect can be used. Additionally 'crel' provides an aggregate of composite reliabilites, 'rel' provides a vector or a list of reliability coefficients for the latent variables, 'con' provides an aggregate consistency estimate for MTMM analyses, and 'lvcor' provides a list of the latent variable correlation matrices. For more detailed objective functions 'lambda', 'theta', 'psi', 'alpha', and 'nu' provide the model-implied matrices. Per default a pheromone function using 'crel', 'rmsea', and 'srmr' is used. Please be aware that the objective must be a function with the required fit indices as (correctly named) arguments.

Using model comparisons via the comparisons argument compares the target model to a model with one less degree of assumed invariance (e.g. if your target model contains strong invariance, the comparison model contain weak invariance). Adding comparisons will change the preset for the objective function to include model differences. With comparisons, a custom objective function (the recommended approach) can also include all model fit indices with a preceding delta. to indicate the difference in this index between the two models. If more than one type of comparison is used, the argument of the objective function should end in the type of comparison requested (e.g. delta.cfi.group to use the difference in CFI between the model comparison of invariance across groups).

Value

Returns an object of the class stuartOutput for which specific summary and plot methods are available. The results are a list.

call

The called function.

software

The software used to fit the CFA models.

parameters

A list of the ACO parameters used.

analysis.options

A list of the additional arguments passed to the estimation software.

timer

An object of the class proc_time which contains the time used for the analysis.

log

A data.frame containing the estimation history.

log_mat

A list of matrices (e.g. lvcor) relevant to the estimation history, if any.

solution

NULL

pheromones

NULL

subtests

A list containing the names of the selected items and their respective subtests.

final

The results of the estimation of the global-best solution.

Author(s)

Martin Schultze

See Also

mmas, gene, randomsamples, combinations

Examples

# Bruteforce selection in a minimal example
# selecting 3 of 5 items
# requires lavaan
data(fairplayer)
fs <- list(ra = names(fairplayer)[53:57])
sel <- bruteforce(fairplayer, fs, 3,
  cores = 1)  # number of cores set to 1
summary(sel)  # Fit is perfect because of just-identified model