Package 'stuart' reference manual

Title:	Subtests Using Algorithmic Rummaging Techniques
Description:	Construct subtests from a pool of items by using ant-colony-optimization, genetic algorithms, brute force, or random sampling. Schultze (2017) <doi:10.17169/refubium-622>.
Authors:	Martin Schultze [aut, cre], Johanna Schüller [ctb]
Maintainer:	Martin Schultze <[email protected]>
License:	GPL-3
Version:	0.10.2
Built:	2025-03-01 06:23:12 UTC
Source:	https://github.com/cran/stuart

STUART: Subtests Using Algorithmic Rummaging Techniques

Description

The STUART-Package automates the generation of subtests from a given set of items within the confines of confirmatory factor analysis.

Functionality

Using this package subtests can be generated in four different ways: using a pseudo-random approach rooted in Ant-Colony-Optimization via the mmas-function, using a simple genetic algorithm via the gene-function, using a brute-force approach via the aptly named bruteforce-function, or by random chance, using the randomsamples-function.

Addtionally, there are some convenience functions which are more or less useful. The combinations-function can be used to determine the number of possible subtests to inform a decision on which selection approach to use. The crossvalidate-function can be used to evaluate the quality of a selection in a different (sub-)sample. To add to this functionality, the holdout-function randomly splits the data into a calibration and a validation sample. The entire process can be applied to k samples with kfold. The heuristics-function can be used to extract the formatting of heuristic matrices which can be provided to the mmas-function.

As of version 0.10.0 this package also includes some convenience functions for handling objective functions. These are mainly fixedobjective - to generate a fixed objective function containing any number of a variety of possible quality criteria - and empiricalobjective - to generate an adaptive objective function based on the quality determined for previous solution on any such criteria. In addition objectivematrices provides functionality to extract matrices for situations in which, for example, latent correlations or regressions predicting distal outcomes are included into the selection procedure.

The package also provides three datasets to try things out with: fairplayer, sia, and sups.

Author(s)

Maintainer: Martin Schultze [email protected]

Other contributors:

Johanna Schüller [contributor]

Convert empirical to fixed objective.

Description

Convert an empirical objective to a fixed version to be used in item-selection. Sensible for extracting values from random selections and then using them in empirical but static objective functions.

Usage

as.stuartFixedObjective(x)
as.stuartFixedObjective(x)

Arguments

`x`	An object of class `stuartEmpiricalObjective`.

Value

Returns an object of class stuartFixedObjective

Author(s)

Martin Schultze

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

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

# 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

Compute the number of possible subtest combinations

Description

Used to compute the number of possible subtest constellations prior to performing item selection.

Usage

combinations(
  data,
  factor.structure,
  capacity = NULL,
  repeated.measures = NULL,
  mtmm = NULL,
  use.order = FALSE,
  ...
)
combinations(
  data,
  factor.structure,
  capacity = NULL,
  repeated.measures = NULL,
  mtmm = NULL,
  use.order = FALSE,
  ...
)

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.
`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.
`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.
`use.order`	A logical indicating whether or not to take the selection order of the items into account. Defaults to `FALSE`.
`...`	Other arguments normally provided to `mmas`, which will be ignored.

Value

Returns the number of possible subtest constellations.

Author(s)

Martin Schultze

Examples


# Determine number of combinations in a simple situation
data(fairplayer)
fs <- list(si = names(fairplayer)[83:92])
combinations(fairplayer, fs, 4)

# Number of combinations with repeated measures
data(fairplayer)
fs <- list(si1 = names(fairplayer)[83:92],
  si2 = names(fairplayer)[93:102],
  si3 = names(fairplayer)[103:112])
repe <- list(si = c('si1', 'si2', 'si3'))
combinations(fairplayer, fs, 4, repeated.measures = repe)

# Determine number of combinations in a simple situation
data(fairplayer)
fs <- list(si = names(fairplayer)[83:92])
combinations(fairplayer, fs, 4)

# Number of combinations with repeated measures
data(fairplayer)
fs <- list(si1 = names(fairplayer)[83:92],
  si2 = names(fairplayer)[93:102],
  si3 = names(fairplayer)[103:112])
repe <- list(si = c('si1', 'si2', 'si3'))
combinations(fairplayer, fs, 4, repeated.measures = repe)

Cross-Validate a Measurement Model

Description

Cross-validate a measurement model obtained from STUART.

Usage

crossvalidate(
  selection,
  old.data,
  new.data,
  max.invariance = "strict",
  filename = NULL
)
crossvalidate(
  selection,
  old.data,
  new.data,
  max.invariance = "strict",
  filename = NULL
)

Arguments

`selection`	An object of class `stuartOutput`.
`old.data`	A `data.frame` of the calibration sample.
`new.data`	A `data.frame` of the validation sample.
`max.invariance`	The maximum measurement invariance level which will be tested. Currently there are four options: 'configural', 'weak', 'strong', and 'strict' (the default). All levels below `max.invariance` are also tested.
`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.

Value

Returns a list containing the data.frame comparison and an object containing the model results of the four different invariance assumptions.

`comparison`	A `data.frame` with 4 observations, each observation representing a level of measurement invariance. The number of columns depends on the arguments of the `objective` used in the original selection. In addition to those columns, three additional columns with the (corrected) Likelihood-Ratio-Tests are reported.
`models`	A list of the four model results either of class `lavaan` or `mplus.model`, depending on the `software`-setting of the original selection.

Author(s)

Martin Schultze

Examples


# Split data into two halves
data(fairplayer)
half1 <- fairplayer[1:72,]
half2 <- fairplayer[73:143,]

# Simple example from bruteforce
fs <- list(ra = names(fairplayer)[53:57])
sel <- bruteforce(half1, fs, 3,
  cores = 1)  # number of cores set to 1

# Validation
crossvalidate(sel, half1, half2)

# Using the 'holdout' function for data split
data(fairplayer)
split <- holdout(fairplayer, seed = 55635)

# Simple example from bruteforce
fs <- list(ra = names(fairplayer)[53:57])
sel <- bruteforce(split, fs, 3,
  cores = 1)  # number of cores set to 1

# Validation
crossvalidate(sel, split)

# Split data into two halves
data(fairplayer)
half1 <- fairplayer[1:72,]
half2 <- fairplayer[73:143,]

# Simple example from bruteforce
fs <- list(ra = names(fairplayer)[53:57])
sel <- bruteforce(half1, fs, 3,
  cores = 1)  # number of cores set to 1

# Validation
crossvalidate(sel, half1, half2)

# Using the 'holdout' function for data split
data(fairplayer)
split <- holdout(fairplayer, seed = 55635)

# Simple example from bruteforce
fs <- list(ra = names(fairplayer)[53:57])
sel <- bruteforce(split, fs, 3,
  cores = 1)  # number of cores set to 1

# Validation
crossvalidate(sel, split)

Generate an empirical objective function for item selection.

Description

Generate an empirical objective function from default or empirical values for use in an item selection using STUART.

Usage

empiricalobjective(
  criteria = c("rmsea", "srmr", "crel"),
  add = c("chisq", "df", "pvalue"),
  x = NULL,
  n = 50,
  side = NULL,
  skew = FALSE,
  scale = 1,
  matrices = NULL,
  fixed = NULL,
  comparisons = NULL,
  ...
)
empiricalobjective(
  criteria = c("rmsea", "srmr", "crel"),
  add = c("chisq", "df", "pvalue"),
  x = NULL,
  n = 50,
  side = NULL,
  skew = FALSE,
  scale = 1,
  matrices = NULL,
  fixed = NULL,
  comparisons = NULL,
  ...
)

Arguments

`criteria`	A vector of names of criteria included in the objective function. Defaults to `c('rmsea', 'srmr', 'crel')`.
`add`	A vector of names of criteria not used in the objective function, but added in order to be included in the log of solutions.
`x`	Either a vector of values or an object of class `stuartOutput` from which to determine values in the objective function. If `NULL` (the default) values are generated from criteria-specific presets.
`n`	Number of values to use in function determining. Defaults to 50, meaning if `side = 'top'` the 50 largest values are used to determine discrimination and difficulty parameters for each criterion.
`side`	Which side good values are located at. `'top'` means large values are good (e.g. Reliability), `'bottom'` means small values are good (e.g. RMSEA), and `'middle'` means average values are good (e.g. factor correlations).
`skew`	Whether to account for skew in the distribution using the `psn()` function from the `sn`-Package. Defaults to `FALSE`, meaning a normal distribution is used.
`scale`	A numeric scale to use in weighting the objective component. Defaults to 1.
`matrices`	An object of class `stuartObjectiveMatrices` to include matrices (e.g. latent correlations) into the objective function.
`fixed`	An object of class `stuartFixedObjective` to include already previously defined fixed objectives.
`comparisons`	A vector of names of criteria included in the objective function which are related to model comparisons (e.g. when determining measurement invariance).
`...`	Additional arguments.

Value

Returns an object of class stuartFixedObjective

Author(s)

Martin Schultze

MTMM fairplayer Intervention Data (2009)

Description

Self- and teacher-reported empathy (8 item scale), relational aggression (5 item scale), and social intelligence (10 item scale) at three different occasions.

Format

A data frame with 143 observations on 142 variables. The variable names consist of an initial letter indicating the source (s: self-report, t: teacher-report), two letters indicating the construct (EM: empathy, RA: relational aggression, SI: social intelligence), a number indicating the item number on the scale, and a "t" followed by a number indicating the measurement occasion.

Source

Bull, H., Schultze, M., Scheithauer, H. (2009) School-based prevention of bullying and relational aggression: The fairplayer.manual. European Journal of Developmental Science, 3:313-317.

Schultze, M. (2012). Evaluating What The Crowd Says. A longitudinal structural equation model for exchangeable and structurally different methods for evaluating interventions. Unpublished Diploma Thesis.

Generate a fixed objective function for item selection.

Description

Generate an objective function from default values for use in an item selection using STUART.

Usage

fixedobjective(
  criteria = c("rmsea", "srmr", "crel"),
  add = c("chisq", "df", "pvalue"),
  side = NULL,
  scale = 1,
  matrices = NULL,
  fixed = NULL,
  comparisons = NULL,
  ...
)
fixedobjective(
  criteria = c("rmsea", "srmr", "crel"),
  add = c("chisq", "df", "pvalue"),
  side = NULL,
  scale = 1,
  matrices = NULL,
  fixed = NULL,
  comparisons = NULL,
  ...
)

Arguments

`criteria`	A vector of names of criteria included in the objective function. Defaults to `c('rmsea', 'srmr', 'crel')`.
`add`	A vector of names of criteria not used in the objective function, but added in order to be included in the log of solutions.
`side`	Which side good values are located at. `'top'` means large values are good (e.g. Reliability), `'bottom'` means small values are good (e.g. RMSEA), and `'middle'` means average values are good (e.g. factor correlations).
`scale`	A numeric scale to use in weighting the objective component. Defaults to 1.
`matrices`	An object of class `stuartObjectiveMatrices` to include matrices (e.g. latent correlations) into the objective function.
`fixed`	An object of class `stuartFixedObjective` to include already previously defined fixed objectives.
`comparisons`	A vector of names of criteria included in the objective function which are related to model comparisons (e.g. when determining measurement invariance).
`...`	Additional arguments.

Value

Returns an object of class stuartFixedObjective

Author(s)

Martin Schultze

Subtest construction using a simple genetic algorithm

Description

Construct subtests from a given pool of items using a simple genetic algorithm. Allows for multiple constructs, occasions, and groups.

Usage

gene(
  data,
  factor.structure,
  capacity = NULL,
  item.weights = 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,
  burnin = 5,
  generations = 256,
  individuals = 64,
  selection = "tournament",
  selection.pressure = NULL,
  elitism = NULL,
  reproduction = 0.5,
  mutation = 0.05,
  mating.index = 0,
  mating.size = 0.25,
  mating.criterion = "similarity",
  immigration = 0,
  convergence.criterion = "geno.between",
  tolerance = NULL,
  reinit.n = 1,
  reinit.criterion = convergence.criterion,
  reinit.tolerance = NULL,
  reinit.prop = 0.75,
  schedule = "run",
  analysis.options = NULL,
  suppress.model = FALSE,
  seed = NULL,
  filename = NULL
)
gene(
  data,
  factor.structure,
  capacity = NULL,
  item.weights = 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,
  burnin = 5,
  generations = 256,
  individuals = 64,
  selection = "tournament",
  selection.pressure = NULL,
  elitism = NULL,
  reproduction = 0.5,
  mutation = 0.05,
  mating.index = 0,
  mating.size = 0.25,
  mating.criterion = "similarity",
  immigration = 0,
  convergence.criterion = "geno.between",
  tolerance = NULL,
  reinit.n = 1,
  reinit.criterion = convergence.criterion,
  reinit.tolerance = NULL,
  reinit.prop = 0.75,
  schedule = "run",
  analysis.options = NULL,
  suppress.model = FALSE,
  seed = NULL,
  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.weights`	A placeholder. Currently all weights are assumed to be one.
`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) or 'Mplus'. 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 'details' 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`.
`burnin`	Number of generations for which to use fixed objective function before switching to empirical objective. Ignored if `objective` is not of class `stuartEmpiricalObjetive`. Defaults to 5.
`generations`	Maximum number of generations to run. Defaults to 256.
`individuals`	The number of individuals per generation. Defaults to 64.
`selection`	The method used for selecting possible parents. Can be either `'proportional'` for fitness proportional random selection or `'tournament'` (the default) for a semi-deterministic selection.
`selection.pressure`	The pressure exerted during the selection process, depending on the `selection`: if `selection = 'proportional'` the non-linearity coefficient of the pheromone when determining selection probability (the default is 1); if `selection = 'proportional'` the number of randomly selected individuals from which to choose the best (the default is 5).
`elitism`	The proportion of individuals from the last generation to carry over to the next generation. Defaults to 1/individuals, meaning that the best individual is retained into the next generation.
`reproduction`	The proportion of individuals that are allowed to sire offspring. These individuals are selected using fitness proportionate selection. Defaults to .5.
`mutation`	The mutation probability. Defaults to .05. See 'details'.
`mating.index`	The relative rank of the selected mate within the mating pool. A number bewteen 0 (the default) and 1. The meaning depends on the setting of `mating.criterion`. See 'details'.
`mating.size`	The proportion of potential mates sampled from the pool of reproducers for each selected individual. Defaults to .25. See 'details'.
`mating.criterion`	The criterion by which to select mates. Can be either 'similarity' (the default) or 'fitness'. See 'details'.
`immigration`	The proportion of individuals per generation that are randomly generated immigrants. Defaults to 0.
`convergence.criterion`	The criterion by which convergence is determined. Can be one of four criteria `'variance'`, `'median'`, `'geno.within'`, and `'geno.between'` (the default). See 'details'.
`tolerance`	The tolerance for determining convergence. The default depends on the setting used for `convergence.criterion`. See 'details'.
`reinit.n`	The maximum number of reinitilizations to be performed. Defaults to 1. See 'details'.
`reinit.criterion`	The convergence criterion used to determine whether the population should be reinitialized. Can be one of four criteria `'variance'`, `'median'`, `'geno.within'`, and `'geno.between'`. Per default, the same criterion provided to `convergence.criterion` is used. See 'details'.
`reinit.tolerance`	The tolerance for determining the necessity of reinitialization. The default depends on the setting used for `convergence.criterion`. See 'details'.
`reinit.prop`	The proportion of the population to be discarded and replaced by random individuals when reinitializing. Defaults to .75. See 'details'.
`schedule`	The counter which the scheduling of parameters pertains to. Can be either 'run' (the default), for a continuous schedule, 'generation', for a schedule that is restarted every time the population is reinitialized.
`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`.
`seed`	A random seed for the generation of random samples. See `Random` for more details.
`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', and 'alpha' 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.

The genetic algorithm implemented selects parents in a two-step procedure. First, either a tournament or a fitness proportionate selection is performed to select inviduals times reproduction viable parents. Then, the non-self-adaptive version of mating proposed by Galán, Mengshoel, and Pinter (2013) is used to perform mating. In contrast to the original article, the mating.index and mating.size are handled as proportions, not integers. Similarity-based mating is based on the Jaccard Similarity. Mutation is currently always handled as an exchange of the selection state between two items. This results in mutation selecting one item that was not selected prior to mutation and dropping one item selected prior to mutation.

Per default (convergence.criterion = 'geno.between'), convergence is checked by tracking the changes between selection probabilities over three subsequent generations. If the difference between these selections probabilities falls below tolerance (.01 by default) in three consecutive generations, the algorithm is deemed to have converged. To avoid false convergence in the early search, the lower of either 10% of the generations or 10 generations must be completed, before convergence is checked. When using reinitialization the default for reinit.tolerance is .05 to initiate a full reinitialization of the population. An alternative convergence criterion is the variance of the global-best values on the objective function, as proposed by Bhandari, Murthy, and Pal (2012). For generalizability over different functions provided to objective, variances are scaled to the first global-best found. In this case the setting for tolerance pertains to the pure variance estimate and defaults to .0005 (or .005 when regarding the reinitialization process discussed below). Alternatively, the setting 'median' checks for the relative difference between the objective function value of the generation-best and the median value of a generation (scaled by the former). Here, the default is .05 (or .10 when regarding the reinitialization process). The setting 'geno.within' checks for the variability of genotypes in a generation, by determining the relative frequency, with which each item is selected. Convergence is reached if this relative frequency is either tolerance (.8, by default - or .7 for the reinitialization process) or 1 - tolerance for all items within a generation.

A reinitialization procedure can be used to avoid premature convergence. The behavior is controlled via the arguments starting in reinit. The argument reinit.n determines the maximum number of possible reinitializations. After each reinitialization, the generation counter is reset, allowing for the maximum number of generations before the search is aborted. The reinit.criterion and reinit.tolerance relate to convergence criteria outlined above. It is recommended to use a higher tolerance on reinitialization than on final convergence to avoid long periods of stagnant search. The reinit.prop determines the proportion of the population to be replaced by random individuals when reinitializing. Note that even when reinit.prop = 1, the number of individuals kept due to elitism is not discarded.

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 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 optimization history.
`log_mat`	A `list` of matrices (e.g. lvcor) relevant to the estimation history, if any.
`solution`	A list of matrices with the choices made in the global-best solution.
`pheromones`	A list of matrices with the relative selection frequency of items in the final generation.
`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

References

Bhandari, D., Murthy, C.A., & Pal, S.K. (2012). Variance as a Stopping Criterion for Genetic Algorithms with Elitist Model. Fundamenta Informaticae, 120, 145-164. doi:10.3233/FI-2012-754

Galán, S.F., Mengshoel, O.J., & Pinter, R. (2013). A novel mating approach for genetic algorithms. Evolutionary Computation, 21(2), 197-229. doi:10.1162/EVCO_a_00067

Examples


# Genetic selection in a simple situation
# requires lavaan
# number of cores set to 1 in all examples
data(fairplayer)
fs <- list(si = names(fairplayer)[83:92])

# minimal example
sel <- gene(fairplayer, fs, 4, 
  generations = 1, individuals = 10,  # minimal runtime, remove for application
  seed = 55635, cores = 1)
summary(sel)


# longitudinal example
data(fairplayer)
fs <- list(si1 = names(fairplayer)[83:92],
  si2 = names(fairplayer)[93:102],
  si3 = names(fairplayer)[103:112])

repe <- list(si = c('si1', 'si2', 'si3'))

# run to convergence
# switching to best-last mating and 50\% mating size
sel <- gene(fairplayer, fs, 4, 
  repeated.measures = repe, long.invariance = 'strong',
  mating.criterion = 'fitness', mating.index = 0, 
  mating.size = .5,
  seed = 55635, cores = 1)

# forcing a run through all generations
# by disabling the convergence rule
sel <- gene(fairplayer, fs, 4,
  repeated.measures = repe, long.invariance = 'strong',
  tolerance = 0, seed = 55635,
  cores = 1)


# Genetic selection in a simple situation
# requires lavaan
# number of cores set to 1 in all examples
data(fairplayer)
fs <- list(si = names(fairplayer)[83:92])

# minimal example
sel <- gene(fairplayer, fs, 4, 
  generations = 1, individuals = 10,  # minimal runtime, remove for application
  seed = 55635, cores = 1)
summary(sel)


# longitudinal example
data(fairplayer)
fs <- list(si1 = names(fairplayer)[83:92],
  si2 = names(fairplayer)[93:102],
  si3 = names(fairplayer)[103:112])

repe <- list(si = c('si1', 'si2', 'si3'))

# run to convergence
# switching to best-last mating and 50\% mating size
sel <- gene(fairplayer, fs, 4, 
  repeated.measures = repe, long.invariance = 'strong',
  mating.criterion = 'fitness', mating.index = 0, 
  mating.size = .5,
  seed = 55635, cores = 1)

# forcing a run through all generations
# by disabling the convergence rule
sel <- gene(fairplayer, fs, 4,
  repeated.measures = repe, long.invariance = 'strong',
  tolerance = 0, seed = 55635,
  cores = 1)

Generating heuristics for the use in STUART subtest construction

Description

Creates uninformative heuristic matrices for the use in mmas.

Usage

heuristics(
  data,
  factor.structure,
  capacity = NULL,
  repeated.measures = NULL,
  mtmm = NULL,
  grouping = NULL,
  localization = "nodes",
  ...
)
heuristics(
  data,
  factor.structure,
  capacity = NULL,
  repeated.measures = NULL,
  mtmm = NULL,
  grouping = NULL,
  localization = "nodes",
  ...
)

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.
`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.
`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.
`grouping`	The name of the grouping variable. The grouping variable must be part of `data` provided and must be a numeric variable.
`localization`	Which parameterization to use when depositing pheromones. Can be either 'nodes' (the default) for depositing pheromones on selected nodes or 'arcs' for depositing on selection arcs.
`...`	Other arguments normally provided to `mmas`, which will be ignored.

Details

This function generates a list of matrices which can be used as heuristics for all STUART constructions. This is mainly intended to write the structure of the heuristic matrices to an object, change components in line with theoretically derived heuristics and feed them back into mmas via the heuristics argument. The generated heuristics will contain only 1s and 0s, making it no heuristic information. Selection probabilities can be altered by manipulating the contents of the object created by heuristics. Setting a value to 0 will result in prohibiting a certain choice to be made. Please note, that it will lead to unpredictable behavior if the diagonal elements of the matrices produced in the arcs parameterization are set to values other than 0.

Value

Returns a list of the same length as the factor.structure argument provided.

Author(s)

Martin Schultze

Examples


# heuristics for node localization
data(fairplayer)
fs <- list(si = names(fairplayer)[83:92])

(heu <- heuristics(fairplayer, fs, 4))

# Define anchor-item
heu$si[1] <- 10000
heu

# heuristics for arc localization
data(fairplayer)
fs <- list(si = names(fairplayer)[83:92])

(heu <- heuristics(fairplayer, fs, 4, localization = 'arcs'))

# Define equal selection of odd and even items
heu$si[1:10,] <- c(rep(c(0, 1), 5), rep(c(1, 0), 5))
heu

# heuristics for node localization
data(fairplayer)
fs <- list(si = names(fairplayer)[83:92])

(heu <- heuristics(fairplayer, fs, 4))

# Define anchor-item
heu$si[1] <- 10000
heu

# heuristics for arc localization
data(fairplayer)
fs <- list(si = names(fairplayer)[83:92])

(heu <- heuristics(fairplayer, fs, 4, localization = 'arcs'))

# Define equal selection of odd and even items
heu$si[1:10,] <- c(rep(c(0, 1), 5), rep(c(1, 0), 5))
heu

Data selection for holdout validation.

Description

Split a data.frame into two subsets for holdout validation.

Usage

holdout(data, prop = 0.5, grouping = NULL, seed = NULL, determined = NULL)
holdout(data, prop = 0.5, grouping = NULL, seed = NULL, determined = NULL)

Arguments

`data`	A `data.frame`.
`prop`	A single value or vector of proportions of data in calibration sample. Defaults to .5, for an even split.
`grouping`	Name of the grouping variable. Providing a grouping variable ensures that the provided proportion is selected within each group.
`seed`	A random seed. See `Random` for more details.
`determined`	Name of a variable indicating the pre-determined assignment to the calibration or the validation sample. This variable must be a factor containing only `NA` (no determined assingment), `"calibrate"`, or `"validate"`. If no variable is provided (the default) all cases are assigned randomly.

Value

Returns a list containing two data.frames, called calibrate and validate. The first corresponds to the calibration sample, the second to the validation sample.

Author(s)

Martin Schultze

Examples


# seeded selection, 25% validation sample
data(fairplayer)
split <- holdout(fairplayer, .75, seed = 55635)
lapply(split, nrow) # check size of samples

# seeded selection, 25% validation sample
data(fairplayer)
split <- holdout(fairplayer, .75, seed = 55635)
lapply(split, nrow) # check size of samples

k-Folds Crossvalidation

Description

k-Folds crossvalidation for item selection using any approach implemented in STUART.

Usage

kfold(
  type,
  k = 5,
  max.invariance = "strict",
  seed = NULL,
  seeded.search = TRUE,
  ...,
  remove.details = TRUE
)
kfold(
  type,
  k = 5,
  max.invariance = "strict",
  seed = NULL,
  seeded.search = TRUE,
  ...,
  remove.details = TRUE
)

Arguments

`type`	A `character` calling the item-selection procedure. Can be one of "mmas" (see `mmas`), "gene" (see `gene`), "bruteforce" (see `bruteforce`), or randomsamples (see `randomsamples`).
`k`	The number of folds.
`max.invariance`	The maximum measurement invariance level which will be tested. Currently there are four options: 'configural', 'weak', 'strong', and 'strict' (the default). All levels below `max.invariance` are also tested.
`seed`	The random seed.
`seeded.search`	A `logical` indicating whether the `seed` should also be used for the search procedure (the default) or only for the sample splitting.
`...`	Arguments passed to the item-selection procedure called with `type`.
`remove.details`	A `logical` indicating whether to remove detailed information such as models and copies of datasets. Reduces output size by approx. 90%. Defaults to `TRUE`.

Details

The function splits the provided data into k subsets using holdout and runs the item-selection procedure requested via type on the training datasets. Validation is performed using crossvalidate to check for invariance of the measurement models between the training and validation data up to the invariance level provided via max.invariance. The final item selection is based on the highest value on the objective function in the multiple-group SEM imposing max.invariance between the training and validation data.

Value

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

`call`	The called function.
`subtests`	A list containing the names of the selected items and their respective subtests.
`solution`	A list of matrices with the choices made in the global-best solution.
`final`	The results of the estimation of the solution leading to best objective value when cross-validated.
`frequencies`	A list of matrices showing the relative frequencies with which an item was selected across the k-folds.
`full`	A list of the results returned by the k runs of `type`.
`crossvalidations`	A list of data.frames showing the fit and model comparisons of all invariance levels up to `max.invariance` in each of the k folds.
`data`	A `data.frame`. The same as the original `data.frame` provided to `data` with the added variable `stuartKfold` indicating which fold an observation was assigned to.

Author(s)

Martin Schultze

Examples


# k-Folding for a simple bruteforce selection
data(fairplayer)
fs <- list(ra = names(fairplayer)[53:57])

sel <- kfold('bruteforce', k = 2,
  data = fairplayer, factor.structure = fs, 
  capacity = 3, seed = 55635,
  cores = 1)
summary(sel)


### longitudinal example with mmas ----
data(fairplayer)
fs <- list(si1 = names(fairplayer)[83:92],
  si2 = names(fairplayer)[93:102],
  si3 = names(fairplayer)[103:112])

repe <- list(si = c('si1', 'si2', 'si3'))

sel_mmas <- kfold('mmas', k = 3,
  data = fairplayer, factor.structure = fs,
  repeated.measures = repe, long.invariance = 'strong',
  capacity = 3, seed = 55635, pbest = .5,
  cores = 1)
summary(sel_mmas)



# k-Folding for a simple bruteforce selection
data(fairplayer)
fs <- list(ra = names(fairplayer)[53:57])

sel <- kfold('bruteforce', k = 2,
  data = fairplayer, factor.structure = fs, 
  capacity = 3, seed = 55635,
  cores = 1)
summary(sel)


### longitudinal example with mmas ----
data(fairplayer)
fs <- list(si1 = names(fairplayer)[83:92],
  si2 = names(fairplayer)[93:102],
  si3 = names(fairplayer)[103:112])

repe <- list(si = c('si1', 'si2', 'si3'))

sel_mmas <- kfold('mmas', k = 3,
  data = fairplayer, factor.structure = fs,
  repeated.measures = repe, long.invariance = 'strong',
  capacity = 3, seed = 55635, pbest = .5,
  cores = 1)
summary(sel_mmas)

Subtest construction using the Max-Min-Ant-System

Description

Construct subtests from a given pool of items using the classical Max-Min Ant-System (Stützle, 1998). Allows for multiple constructs, occasions, and groups.

Usage

mmas(
  data,
  factor.structure,
  capacity = NULL,
  item.weights = 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,
  burnin = 5,
  ants = 16,
  colonies = 256,
  evaporation = 0.95,
  alpha = 1,
  beta = 1,
  pheromones = NULL,
  heuristics = NULL,
  deposit = "ib",
  localization = "nodes",
  pbest = 0.005,
  tolerance = 0.5,
  schedule = "run",
  analysis.options = NULL,
  suppress.model = FALSE,
  seed = NULL,
  filename = NULL
)
mmas(
  data,
  factor.structure,
  capacity = NULL,
  item.weights = 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,
  burnin = 5,
  ants = 16,
  colonies = 256,
  evaporation = 0.95,
  alpha = 1,
  beta = 1,
  pheromones = NULL,
  heuristics = NULL,
  deposit = "ib",
  localization = "nodes",
  pbest = 0.005,
  tolerance = 0.5,
  schedule = "run",
  analysis.options = NULL,
  suppress.model = FALSE,
  seed = NULL,
  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.weights`	A placeholder. Currently all weights are assumed to be one.
`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) or 'Mplus'. 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 'details' 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`.
`burnin`	Number of colonies for which to use fixed objective function before switching to empirical objective. Ignored if `objective` is not of class `stuartEmpiricalObjetive`. Defaults to 5.
`ants`	The number of ants per colony to be estimated. Can either be a single value or an array with two columns for parameter scheduling. See 'details'.
`colonies`	The maximum number of colonies estimated since finding the latest global-best solution before aborting the process. Can either be a single value or an array with two columns for parameter scheduling. See 'details'.
`evaporation`	The evaporation coefficient. Can either be a single value or an array with two columns for parameter scheduling. See 'details'.
`alpha`	The nonlinearity coefficient of the pheromone-trail's contribution to determining selection probabilities. Defaults to 1 (linear). Can either be a single value or an array with two columns for parameter scheduling. See 'details'.
`beta`	The nonlinearity coefficient of the heuristics' contribution to determining selection probabilities. Defaults to 1 (linear). Can either be a single value or an array with two columns for parameter scheduling. See 'details'.
`pheromones`	A list of pheromones as created by `mmas`. This can be used to continue previous runs of this function.
`heuristics`	An object of the class `stuartHeuristic` as provided by `heuristics` which contains heuristic information to be used in determining selection probabilities. If `NULL` (the default) selection probabilities are determined solely by the pheromones.
`deposit`	Which deposit rule to use. Can be either 'ib' (the default) for an iteration-best deposit rule, or 'gb' for a global-best deposit rule.
`localization`	Which localization to use when depositing pheromones. Can be either 'nodes' (the default) for depositing pheromones on selected nodes or 'arcs' for depositing on selection arcs.
`pbest`	The desired overall probability of constructing the global-best solution when the algorithm convergels. Can either be a single value or an array with two columns for parameter scheduling. See 'details'.
`tolerance`	The tolerance of imprecision when comparing the pheromones to the upper and lower limits. Can either be a single value or an array with two columns for parameter scheduling. See 'details'.
`schedule`	The counter which the scheduling of parameters pertains to. Can be either 'run' (the default), for a continuous schedule, 'colony', for a schedule that is restarted every time a new global best is found, or 'mixed' for a schedule that restarts its current phase every time a new global best is found. See 'details'.
`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`.
`seed`	A random seed for the generation of random samples. See `Random` for more details.
`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 scheduling of parameters is possible for the arguments ants, colonies, evaporation, pbest, alpha, beta, tolerance, and deposit. For all of these parameter scheduling is done when an array with two columns is provided. The first column of the array contains the timer, i.e. when to switch between parameter settings, the second column contains the values. The argument schedule can be used to select an absolute schedule (schedule='run'), a relative schedule which resets completely after a new global best is found (schedule='colony'), or a mixed version which resets the current phase of the schedule after a new global best is found (schedule='mixed'). When providing a parameter schedule for iterations 0, 3, and 10 using 'run' will result in a change after the third and the tenth iteration - irrespective of whether global best solutions were found. In contrast, using 'colony' will result in the first setting being used again once a new global best is found. This setting will then be used until iteration 3 (if no new best solution is found) before a switch occurs. If a new global best is found the setting will begin the sequence from the beginning. Using 'mixed' will result in the first setting being used until three consecutive iterations cannot produce a new global best. After this the second setting is used. If a new global best is found, the second setting is kept, but for the purpose of the schedule it is now iteration 3 again, meaning that the third setting will be used later than in a 'run' schedule.

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 optimization history.
`log_mat`	A `list` of matrices (e.g. lvcor) relevant to the estimation history, if any.
`solution`	A list of matrices with the choices made in the global-best solution.
`pheromones`	A list of matrices with the pheromones of each choice.
`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

References

Stützle, T. (1998). Local search algorithms for combinatorial problems: Analysis, improvements, and new applications. Unpublished doctoral dissertation. Darmstadt: Fachbereich Informatik, Universität Darmstadt.

Examples

# MMAS in a simple situation
# requires lavaan
# number of cores set to 1 in all examples
data(fairplayer)
fs <- list(si = names(fairplayer)[83:92])

# minimal example
sel <- mmas(fairplayer, fs, 4, 
  colonies = 0, ants = 10,  # minimal runtime, remove for application
  seed = 55635, cores = 1)
summary(sel)


# longitudinal example
data(fairplayer)
fs <- list(si1 = names(fairplayer)[83:92],
  si2 = names(fairplayer)[93:102],
  si3 = names(fairplayer)[103:112])

repe <- list(si = c('si1', 'si2', 'si3'))

# change evaporation rate after 10 and 20 colonies
sel <- mmas(fairplayer, fs, 4, 
  repeated.measures = repe, long.invariance = 'strong',
  evaporation = cbind(c(0, 10, 20), c(.95, .8, .5)),
  seed = 55635, cores = 1)


# MMAS in a simple situation
# requires lavaan
# number of cores set to 1 in all examples
data(fairplayer)
fs <- list(si = names(fairplayer)[83:92])

# minimal example
sel <- mmas(fairplayer, fs, 4, 
  colonies = 0, ants = 10,  # minimal runtime, remove for application
  seed = 55635, cores = 1)
summary(sel)


# longitudinal example
data(fairplayer)
fs <- list(si1 = names(fairplayer)[83:92],
  si2 = names(fairplayer)[93:102],
  si3 = names(fairplayer)[103:112])

repe <- list(si = c('si1', 'si2', 'si3'))

# change evaporation rate after 10 and 20 colonies
sel <- mmas(fairplayer, fs, 4, 
  repeated.measures = repe, long.invariance = 'strong',
  evaporation = cbind(c(0, 10, 20), c(.95, .8, .5)),
  seed = 55635, cores = 1)

Generate matrix-components for objective functions.

Description

Generate objects of the correct structure for use in custom objective functions.

Usage

objectivematrices(
  data,
  factor.structure,
  capacity = NULL,
  matrices = c("lvcor"),
  n.random = 0,
  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,
  ...
)
objectivematrices(
  data,
  factor.structure,
  capacity = NULL,
  matrices = c("lvcor"),
  n.random = 0,
  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,
  ...
)

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.
`matrices`	Which matrix to extract. Can be one of `'lvcor'` (the default) for latent correlations, 'lambda', 'theta', 'psi', or 'alpha' for the model-implied matrices.
`n.random`	The number of random draws to base values on. If 0 (the default) values are in the matrices are set to 0 and can be overwritten later. If any value larger than 0, the mean from `n.random` random solutions is used.
`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) or 'Mplus'. 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 'details' 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`.
`...`	Additional arguments passed either to `randomsamples` or to `lavaan`.

Value

Returns an object of class stuartFixedObjective

Author(s)

Martin Schultze

Examples


# Extract latent correlation matric
# requires lavaan
# number of cores set to 1 in all examples
data(sups)
fs <- list(pro = names(sups)[2:13],
 fee = names(sups)[14:20])

mats <- objectivematrices(sups, fs, 3,
  cores = 1)
mats

mats$lvcor$use[,] <- FALSE
mats$lvcor$use[2, 1] <- TRUE

mats$lvcor$use

# Extract latent correlation matric
# requires lavaan
# number of cores set to 1 in all examples
data(sups)
fs <- list(pro = names(sups)[2:13],
 fee = names(sups)[14:20])

mats <- objectivematrices(sups, fs, 3,
  cores = 1)
mats

mats$lvcor$use[,] <- FALSE
mats$lvcor$use[2, 1] <- TRUE

mats$lvcor$use

Generating random samples of Subtests

Description

Construct a defined number of random subtests from a given pool of items.

Usage

randomsamples(
  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,
  seed = NULL,
  request.override = 10000,
  filename = NULL,
  n = 1000,
  percentile = 100
)
randomsamples(
  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,
  seed = NULL,
  request.override = 10000,
  filename = NULL,
  n = 1000,
  percentile = 100
)

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`.
`seed`	A random seed for the generation of random samples. See `Random` for more details.
`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.
`n`	The number of random samples to be drawn.
`percentile`	The percentile of the final solution reported among the viable solutions. Defaults to 100 (the best solution found).

Details

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

Examples


# Random samples in a simple situation
# requires lavaan
# number of cores set to 1 in all examples
data(fairplayer)
fs <- list(si = names(fairplayer)[83:92])

# 10 random solutions, report median solution
sel <- randomsamples(fairplayer, fs, 4, 
  n = 10, percentile = 50,
  seed = 55635, cores = 1)
summary(sel)


# Random samples in a simple situation
# requires lavaan
# number of cores set to 1 in all examples
data(fairplayer)
fs <- list(si = names(fairplayer)[83:92])

# 10 random solutions, report median solution
sel <- randomsamples(fairplayer, fs, 4, 
  n = 10, percentile = 50,
  seed = 55635, cores = 1)
summary(sel)

Data from a German Meaning of Work Scale.

Description

Self-reports from a scale construction study for a German Meaning of Work Scale (Feser et al., 2019) with three facets: Self-realization (17 items), belonging (9 items), justification (8 Items). The data additionally include assessments on the Work and Meaning Inventory (Steger et al., 2012), alienation from work (Fischer and Kohr, 2014).

Usage

sia
sia

Format

A data frame with 257 observations on 62 variables.

Details

lfdn. Participant ID.
self1 - self17. 17 items of the self-realization facet.
belong1 - belong9. 9 items of the belonging facet.
just1 - just8. 8 items of the justification facet.
wami1 - wami10. 10 items of the Work and Meaning Inventory.
alien1 - alien10. 10 item of the alienation from work sacle.
age. Age in years.
sex. Gender with 1 = female, 2 = other, 3 = male.
work. Type of employment 1 = employed, 2 = self-employed, 3 = temp-work, 4 = civil servant.
wokrhours. Weekly work hours.
tenure1. Years at the current place of employment.
tenure2. Years of experience in current job.
kldb2010. German Classification of Occupations (first code number).

Source

Feser, M., Lorenz, T., & Mainz, E. (2019). Meaning of work: A culture based approach towards the construction of a German questionnaire. Poster presented at the 19th Congress of The European Association for Work & Organizational Psychology. Turin, Italy.

Fischer, A., & Kohr, H. (2014). Entfremdung von der Arbeit. Zusammentstellung Sozialwissenschaftlicher Items Und Skalen, ZIS. https://doi.org/https://doi.org/10.6102/zis8

Steger, M. F., Dik, B. J., & Duffy, R. D. (2012). Measuring Meaningful Work. Journal of Career Assessment, 20(3), 322–337. https://doi.org/10.1177/1069072711436160

Data from a scale for Supervisor Support

Description

A scale for supervisor support with 19 items. The scale consists of two subscales: carreer promotion (items 1 through 12) and feedback and goal setting (items 13 through 19).

Format

A data frame with 411 observations on 20 variables. The first variable indicates the person ID, the following 19 all stem from the scale for Supervisor Support

Source

Janssen, A.B., Schultze, M., & Grötsch, A. (2015). Following the ants: Development of short scales for proactive personality and supervisor support by Ant Colony Optimization. European Journal of Psychological Assessment.

Package 'stuart'

Help Index

STUART: Subtests Using Algorithmic Rummaging Techniques

Description

Functionality

Author(s)

Convert empirical to fixed objective.

Description

Usage

Arguments

Value

Author(s)

See Also

Subtest construction using a brute-force approach

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Compute the number of possible subtest combinations

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Cross-Validate a Measurement Model

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Generate an empirical objective function for item selection.

Description

Usage

Arguments

Value

Author(s)

See Also

MTMM fairplayer Intervention Data (2009)

Description

Format

Source

Generate a fixed objective function for item selection.

Description

Usage

Arguments

Value

Author(s)

See Also

Subtest construction using a simple genetic algorithm

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Generating heuristics for the use in STUART subtest construction

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Data selection for holdout validation.

Description

Usage

Arguments

Value