Clean data and calculate the md5 hash

Description

Internal utility function, primarily for prepareMplusData.

Internal utility function, primarily for prepareMplusData.

Usage

.cleanHashData(df, keepCols = NULL, dropCols = NULL, imputed = FALSE)

.hashifyFile(filename, hash, useexisting = FALSE)

Arguments

Value

A list of the data and the md5 hash.

A list of the filename (plus hash) and a logical value whether a filename with the hash already existed or not.

Examples

## Not run: 

## basic example
MplusAutomation:::.cleanHashData(mtcars)

## has changes when data changes
MplusAutomation:::.cleanHashData(mtcars[-15,])

## example on a list (e.g., for multiply imputed data)

MplusAutomation:::.cleanHashData(
 list(
   data.frame(a = 1:4),
   data.frame(a = c(2, 2, 3, 4))),
  imputed = TRUE)


## End(Not run)
MplusAutomation:::.hashifyFile("testit.dat", "abc")

Convert a matrix or data frame to numeric or integer for Mplus

Description

Primarily an internal utility function, for prepareMplusData.

Usage

.convertData(df, dummyCode = NULL)

Arguments

Value

An error if it cannot be converted or a matrix or data frame with all variables converted to numeric or integer classes

Examples

## Not run: 
df1 <- df2 <- df3 <- df4 <- mtcars

df2$cyl <- factor(df2$cyl)
df2$am <- as.logical(df2$am)

df3$mpg <- as.character(df3$mpg)

df4$vs <- as.Date(df4$vs, origin = "1989-01-01")

df5 <- as.matrix(cars)

df6 <- matrix(c(TRUE, TRUE, FALSE, FALSE), ncol = 2)

df7 <- as.list(mtcars)


MplusAutomation:::.convertData(df1)

MplusAutomation:::.convertData(df2)

MplusAutomation:::.convertData(df3)

MplusAutomation:::.convertData(df4)

MplusAutomation:::.convertData(df5)

MplusAutomation:::.convertData(df6)

MplusAutomation:::.convertData(df7)

rm(df1, df2, df3, df4, df5, df6, df7)

## End(Not run)

Internal Function for Multinomial Regression in Mplus

Description

Internal Function for Multinomial Regression in Mplus

Usage

.mplusMultinomial(
  dv,
  iv,
  data,
  idvar = "",
  integration = 1000,
  processors = 2,
  OR = TRUE,
  pairwise = TRUE,
  ...
)

Arguments

Value

A list of results and Mplus model object.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

Examples

## Not run: 

set.seed(1234)
tmpd <- data.frame(
  x1 = rnorm(200),
  x2 = rnorm(200),
  x3 = cut(rnorm(200),
           breaks = c(-Inf, -.7, .7, Inf),
           labels = c("a", "b", "c")))
tmpd$y <- cut(rnorm(200, sd = 2) + tmpd$x1 + tmpd$x2 + I(tmpd$x3 == "b"),
              breaks = c(-Inf, -.5, 1, Inf),
              labels = c("L", "M", "H"))

tmpres <- MplusAutomation:::.mplusMultinomial(
  dv = "y",
  iv = c("x1", "x2"),
  data = tmpd,
  pairwise = TRUE)
tmpres2 <- MplusAutomation:::.mplusMultinomial(
  dv = "y",
  iv = c("x1", "x2"),
  data = tmpd,
  pairwise = FALSE)
tmpres3 <- MplusAutomation:::.mplusMultinomial(
  dv = "y",
  iv = c("x1@0", "x2@0"),
  data = tmpd,
  pairwise = FALSE)


## End(Not run)

Create an HTML file containing a summary table of Mplus model statistics

Description

Creates an HTML file containing a summary table of model fit statistics extracted using the extractModelSummaries function. By default, the following summary statistics are included: Title, LL, Parameters, AIC, AICC, BIC, RMSEA_Estimate, but these are customizable using the keepCols and dropCols parameters.

Usage

HTMLSummaryTable(
  modelList,
  filename = file.path(getwd(), "Model Comparison.html"),
  keepCols,
  dropCols,
  sortBy = NULL,
  display = FALSE
)

Arguments

Value

No value is returned by this function. It is solely used to create an HTML file containing summary statistics.

Note

You must choose between keepCols and dropCols because it is not sensible to use these together to include and exclude columns. The function will error if you include both parameters.

Author(s)

Michael Hallquist

See Also

extractModelSummaries, showSummaryTable, LatexSummaryTable

Examples

# make me!!!

Display summary table of Mplus model statistics in separate window

Description

Creates a LaTex-formatted summary table of model fit statistics extracted using the extractModelSummaries function. The table syntax is returned by the function, which is useful for embedding LaTex tables using Sweave. By default, the following summary statistics are included: Title, LL, Parameters, AIC, AICC, BIC, RMSEA_Estimate, but these are customizable using the keepCols and dropCols parameters.

Usage

LatexSummaryTable(
  modelList,
  keepCols,
  dropCols,
  sortBy = NULL,
  label = NULL,
  caption = NULL
)

Arguments

Value

A LaTex-formatted table summarizing the modelList is returned (created by xtable).

Note

You must choose between keepCols and dropCols because it is not sensible to use these together to include and exclude columns. The function will error if you include both parameters.

Author(s)

Michael Hallquist

See Also

extractModelSummaries, HTMLSummaryTable, showSummaryTable, Sweave

Examples

# make me!!!

Automating Mplus Model Estimation and Interpretation

Description

The MplusAutomation package leverages the flexibility of the R language to automate latent variable model estimation and interpretation using 'Mplus', a powerful latent variable modeling program developed by Muthen and Muthen (http://www.statmodel.com). Specifically, MplusAutomation provides routines for creating related groups of models, running batches of models, and extracting and tabulating model parameters and fit statistics.

Details

The MplusAutomation package has four primary purposes:

1. To automatically run groups/batches of models.

2. To provide routines to extract model fit statistics, parameter estimates, and raw data from 'Mplus' output files.

3. To facilitate comparisons among models

4. To provide a template language that allows for the creation of related input files.

The core routine for running batches of models is runModels, with an easy-to-use GUI wrapper, runModels_Interactive.

The core routine for extracting information from 'Mplus' outputs is readModels, which returns a list containing all output sections that the package can extract.

To extract summaries, parameters, modification indices, SAVEDATA output, and all other sections that the package can understand, use the readModels function. This is the recommended way to extract 'Mplus' output with this package. If the target argument to readModels is a single .out file, an mplus.model (that is also a list) will be returned containing all output sections that the package can extract. If target is a directory, a list of mplus.model objects will be returned, named according to the output filenames.

Note: extractModelSummaries is deprecated and readModels should be preferred. To extract model summary statistics from one or more output files, see extractModelSummaries, which returns a data.frame of fit statistics for models located within a directory. Model fit results can be summarized in tabular form (for comparing among models) using showSummaryTable (displays table in separate window), HTMLSummaryTable (creates HTML file containing summary table), or LatexSummaryTable (returns a LaTex-formatted table of summary statistics).

Deprecated: To extract raw data created by the SAVEDATA command (e.g., class membership probabilities or factor scores), see getSavedata_Data.

Deprecated: To extract unstandardized or standardized parameter estimates from a single output file, see extractModelParameters.

Detailed model fit and parameter comparisons between two models can be obtained using compareModels.

To create a group of related models from a single template, see createModels. Please read the MplusAutomation vignette provided along with the package (and on the CRAN website) in order to understand the template language: vignette("Vignette", package="MplusAutomation").

In addition to the major functions above, a function for converting an R data.frame for use with 'Mplus' is provided: prepareMplusData. This converts the data.frame to a tab-delimited file and provides an 'Mplus' syntax stub for variable names.

Author(s)

Michael Hallquist michael.hallquist@gmail.com, Joshua F. Wiley jwiley.psych@gmail.com

Maintainer: Michael Hallquist michael.hallquist@gmail.com

References

Mplus software. Muthen and Muthen. http://www.statmodel.com

See Also

See runModels for an example running a model.

Functions to identify the operating system

Description

Functions to identify the operating system

Usage

is.windows()

is.macos()

is.linux()

os()

Value

A logical value for the is.* functions and a character string for os()

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

Examples

MplusAutomation:::is.windows()

MplusAutomation:::is.macos()

MplusAutomation:::is.linux()

MplusAutomation:::os()

Create a summary table of Mplus model statistics

Description

Creates output (optionally sent to a file) containing a summary table of model fit statistics extracted using the extractModelSummaries function. By default, the following summary statistics are included: Title, LL, Parameters, AIC, AICC, BIC, RMSEA_Estimate, but these are customizable using the keepCols and dropCols parameters.

Usage

SummaryTable(
  modelList,
  type = c("none", "screen", "popup", "html", "latex", "markdown"),
  filename = "",
  keepCols,
  dropCols,
  sortBy = NULL,
  caption = "",
  display = FALSE,
  ...,
  include.rownames = FALSE
)

Arguments

Value

Invisibly returns the summary table, which can be used if the printing options avaiable are not sufficient.

Note

You must choose between keepCols and dropCols because it is not sensible to use these together to include and exclude columns. The function will error if you include both parameters.

Author(s)

Joshua F. Wiley based on code by Michael Hallquist

See Also

extractModelSummaries

Examples

## Not run: 
 m1 <- mplusObject(TITLE = "Reduced",
  MODEL = "mpg ON wt;", rdata = mtcars)
 m1.fit <- mplusModeler(m1, "mtcars.dat", run = 1L)
 m2 <- mplusObject(TITLE = "Full",
  MODEL = "mpg ON wt hp qsec;", rdata = mtcars)
 m2.fit <- mplusModeler(m2, "mtcars.dat", run = 1L)

 SummaryTable(list(m1.fit, m2.fit))
 SummaryTable(list(m1.fit, m2.fit), type = "popup")
 SummaryTable(list(m1.fit, m2.fit), type = "markdown",
   keepCols = c("Title", "Parameters", "LL", "AIC", "CFI", "SRMR"),
   caption = "Table of Model Fit Statistics",
   split.tables = 200)

 # remove files
 unlink("mtcars.dat")
 unlink("mtcars.inp")
 unlink("mtcars.out")
 unlink("Mplus Run Models.log")
 closeAllConnections()

## End(Not run)

Add a node to a GRAPHVIZ model

Description

To do: add details

Usage

addNode(dotModel, name, role, type)

Arguments

Value

the dotModel with added node

Change directory

Description

The function takes a path and changes the current working directory to the path. If the directory specified in the path does not currently exist, it will be created.

Usage

cd(base, pre, num)

Arguments

Details

The function has been designed to be platform independent, although it has had limited testing. Path creation is done using file.path, the existence of the directory is checked using file.exists and the directory created with dir.create. Only the first argument, is required. The other optional arguments are handy when one wants to create many similar directories with a common base.

Value

NULL, changes the current working directory

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

Examples

## Not run: 
# an example just using the base
cd("~/testdir")

# an example using the optional arguments
base <- "~/testdir"
pre <- "test_"

cd(base, pre, 1)
cd(base, pre, 2)

## End(Not run)

Classifies Tags

Description

Accepts a vector of tags to be classified as well as the iterators. Tags are classified as ‘iterator’, ‘array’, ‘conditional’, or ‘simple’. This is an internal function.

Usage

classifyTags(tagVector, iteratorsVector)

Arguments

Value

A character vector the same length as the vectors to be tagged

Clip String

Description

To do: add any details.

Usage

clipString(string, start, end)

Arguments

Value

A string from start to end

Return coefficients for an mplus.model object

Description

This is a method for returning the coefficients of an mplus.model object. It works directly on an object stored from readModels such as: object <- readModels("/path/to/model/model.out").

Method that calls coef.mplus.model. See further documentation there.

Usage

## S3 method for class 'mplus.model'
coef(
  object,
  type = c("un", "std", "stdy", "stdyx"),
  params = c("regression", "loading", "undirected", "expectation", "variability", "new"),
  ...,
  raw = FALSE
)

## S3 method for class 'mplusObject'
coef(object, ...)

Arguments

Value

Either a data frame of class ‘mplus.model.coefs’, or in the case of multiple group models, a list of class ‘mplus.model.coefs’, where each element of the list is a data frame of class ‘mplus.model.coefs’, or a named vector of coefficients, if raw=TRUE.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

See Also

readModels

Other Mplus-Formatting: confint.mplus.model(), extract(), print.MplusRstructure(), summary.mplusObject()

Examples

## Not run: 
# simple example of a model using builtin data
# demonstrates use
test <- mplusObject(
  TITLE = "test the MplusAutomation Package;",
  MODEL = "
    mpg ON wt hp;
    wt WITH hp;",
  OUTPUT = "STANDARDIZED;",
  usevariables = c("mpg", "wt", "hp"),
  rdata = mtcars)

res <- mplusModeler(test, "mtcars.dat", modelout = "model1.inp", run = 1L)

# example of the coef method on an mplud.model object
# note that res$results holds the results of readModels()
coef(res$results)
coef(res$results, type = "std")
coef(res$results, type = "stdy")
coef(res$results, type = "stdyx")

# there is also a method for mplusObject class
coef(res)

# remove files
unlink("mtcars.dat")
unlink("model1.inp")
unlink("model1.out")
unlink("Mplus Run Models.log")

## End(Not run)

Compare the output of two Mplus models

Description

The compareModels function compares the output of two Mplus files and prints similarities and differences in the model summary statistics and parameter estimates. Options are provided for filtering out fixed parameters and nonsignificant parameters. When requested, compareModels will compute the chi-square difference test for nested models (does not apply to MLMV, WLSM, and WLSMV estimators, where DIFFTEST in Mplus is needed). Model outputs to be compared can be full summaries and parameters (generated by readModels), summary statistics only (extractModelSummaries), or parameters only (extractModelParameters).

Usage

compareModels(
  m1,
  m2,
  show = "all",
  equalityMargin = c(param = 1e-04, pvalue = 1e-04),
  compare = "unstandardized",
  sort = "none",
  showFixed = FALSE,
  showNS = TRUE,
  diffTest = FALSE
)

Arguments

Details

The show parameter can be one or more of the following, which can be passed as a vector, such as c("equal", "pdiff").

show

"all"

Display all available model comparison. Equivalent to c("summaries", "equal", "diff", "pdiff", "unique").

"summaries"

Print a comparison of model summary statistics. Compares the following summary statistics (where available): c("Title", "Observations", "Estimator", "Parameters", "LL", "AIC", "BIC", "ChiSqM_Value", "ChiSqM_DF", "CFI", "TLI", "RMSEA", "SRMR", "WRMR")

"allsummaries"

Prints a comparison of all summary statistics available in each model. May generate a lot of output.

"equal"

Print parameter estimates that are equal between models (i.e., <= equalityMargin["param"])

.

"diff"

Print parameter estimates that are different between models (i.e., > equalityMargin["param"])

.

"pdiff"

Print parameter estimates where the p-values differ between models (i.e., > equalityMargin["pvalue"])

.

"unique"

Print parameter estimates that are unique to each model.

The sort parameter determines the order in which parameter estimates are displayed. The following options are available:

sort

"none"

No sorting is performed, so parameters are output in the order presented in Mplus. (Default)

"type"

Sort parameters by their role in the model. This groups output by regression coefficient (ON), factor loadings (BY), covariances (WITH), and so on. Within each type, output is alphabetical.

"alphabetical"

Sort parameters in alphabetical order.

"maxDiff"

Sort parameter output by the largest differences between models (high to low).

Value

No value is returned by this function. It is used to print model differences to the R console.

Author(s)

Michael Hallquist

Examples

# make me!!!

Return confidence intervals for an mplus.model object

Description

This is a method for returning the confidence of an mplus.model object. It works directly on an object stored from readModels such as: object <- readModels("/path/to/model/model.out").

Method that calls confint.mplus.model. See further documentation there.

Usage

## S3 method for class 'mplus.model'
confint(
  object,
  parm,
  level = 0.95,
  type = c("un", "std", "stdy", "stdyx"),
  params = c("regression", "loading", "undirected", "expectation", "variability", "new"),
  ...
)

## S3 method for class 'mplusObject'
confint(object, ...)

Arguments

Value

A data frame of class ‘mplus.model.cis’, or in the case of multiple group models, a list of class ‘mplus.model.cis’, where each element of the list is a data frame of class ‘mplus.model.cis’.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

See Also

readModels

Other Mplus-Formatting: coef.mplus.model(), extract(), print.MplusRstructure(), summary.mplusObject()

Examples

## Not run: 
# simple example of a model using builtin data
# demonstrates use
test <- mplusObject(
  TITLE = "test the MplusAutomation Package;",
  MODEL = "
    mpg ON wt hp;
    wt WITH hp;",
  OUTPUT = "STANDARDIZED; CINTERVAL;",
  usevariables = c("mpg", "wt", "hp"),
  rdata = mtcars)

res <- mplusModeler(test, "mtcars.dat", modelout = "model1.inp", run = 1L)

# example of the confint method on an mplus.model object
# note that res$results holds the results of readModels()
confint(res$results)
confint(res$results, type = "std")
confint(res$results, type = "stdy")
confint(res$results, type = "stdyx", level = .99)

# there is also a method for mplusObject class
confint(res)
screenreg(res, cis = TRUE, single.row = TRUE)

# remove files
unlink("mtcars.dat")
unlink("model1.inp")
unlink("model1.out")
unlink("Mplus Run Models.log")

## End(Not run)

Connect two nodes

Description

To do: add details

Usage

connectNodes(dotModel, node1, node2, connectionType)

Arguments

Create syntax for a batch of mixture models

Description

Dynamically creates syntax for a batch of mixture models, with intelligent defaults. This function is a wrapper around mplusObject and mplusModeler, and the respective arguments of those functions can be passed on using .... For instance, passing the argument run = 1L means that the models will be evaluated and returned.

Usage

createMixtures(
  classes = 1L,
  filename_stem = NULL,
  model_overall = NULL,
  model_class_specific = NULL,
  rdata = NULL,
  usevariables = NULL,
  OUTPUT = "TECH11 TECH14;",
  SAVEDATA = "FILE IS {filename_stem}_{C}.dat;  SAVE = cprobabilities;",
  quiet = TRUE,
  ...
)

Arguments

Details

In the arguments model_class_specific and SAVEDATA, the character string “{C}” is substituted with the correct class number. The character string “{filename_stem}” is substituted with the filename stem, for example, to name savedata in line with the input files.

In all arguments to mplusObject, a double space (“ ”) is replaced with a newline character. This can be used to obtain nicely formatted Mplus syntax.

Value

None, unless the argument run = 1L is specified. In that case, a list with elements of class mplusObject is returned. Otherwise, this function is used for its side effects (generating syntax).

Author(s)

Caspar J. van Lissa

See Also

mplusObject, mplusModeler

Examples

## Not run: 
createMixtures(classes = 1:3, filename_stem = "iris", rdata = iris)

## End(Not run)
## Not run: 
mydat <- read.csv(
system.file("extdata", "ex8.13.csv", package = "MplusAutomation"))
createMixtures(
classes = 2,
filename_stem = "dating",
model_overall = "c2 ON c1;",
model_class_specific = c(
"[u11$1] (a{C});  [u12$1] (b{C});  [u13$1] (c{C});  [u14$1] (d{C});  [u15$1] (e{C});",
"[u21$1] (a{C});  [u22$1] (b{C});  [u23$1] (c{C});  [u24$1] (d{C});  [u25$1] (e{C});"
),
rdata = mydat,
ANALYSIS = "PROCESSORS IS 2;  LRTSTARTS (0 0 40 20);  PARAMETERIZATION = PROBABILITY;",
VARIABLE = "CATEGORICAL = u11-u15 u21-u25;"
)

## End(Not run)

Create Mplus Input Files from Template

Description

The createModels function processes a single Mplus template file and creates a group of related model input files. Definitions and examples for the template language are provided in the MplusAutomation vignette and are not duplicated here at the moment. See this documentation: vignette("Vignette", package="MplusAutomation")

Usage

createModels(templatefile)

Arguments

Value

No value is returned by this function. It is solely used to process an Mplus template file.

Author(s)

Michael Hallquist

Examples

## Not run: 
  createModels("L2 Multimodel Template No iter.txt")

## End(Not run)

Create the Mplus input text for an mplusObject

Description

This function takes an object of class mplusObject and creates the Mplus input text corresponding to it, including data link and variable names.

Usage

createSyntax(object, filename, check = TRUE, add = FALSE, imputed = FALSE)

Arguments

Value

A character string containing all the text for the Mplus input file.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

See Also

prepareMplusData, mplusModeler

Examples

# example mplusObject
example1 <- mplusObject(MODEL = "mpg ON wt;",
  usevariables = c("mpg", "hp"), rdata = mtcars)

# create the Mplus input text
cat(createSyntax(example1, "example1.dat"), file=stdout(), fill=TRUE)

# update the object, then create input text
cat(createSyntax(update(example1,
  TITLE = ~ "This is my title;",
  MODEL = ~ . + "\nmpg ON hp;",
  usevariables = c("mpg", "hp", "wt")), "example1.dat"),
  file=stdout(),
  fill=TRUE)
rm(example1)

Create Mplus syntax for variable names

Description

This is a simple function designed to take a dataset in R and translate it into a set of variable names for Mplus.

Usage

createVarSyntax(data)

Arguments

Value

A character vector of the variable names for Mplus

See Also

prepareMplusData

Examples

MplusAutomation:::createVarSyntax(mtcars)

Detect Column Names

Description

Helper function to detect model results columns.

Usage

detectColumnNames(filename, modelSection, sectionType = "model_results")

Arguments

Value

A list with elements for the directory, filename, and absolute path.

Examples

# make me!!!

Detect the location/name of the Mplus command

Description

This is an utility function to help detect the correct name/path to Mplus. It tries hard across operating systems to find Mplus and if it cannot find the full version of Mplus to find a demo version of Mplus.

Usage

detectMplus()

Details

It does not require any arguments.

Value

A character string that is the Mplus command possibly the path to the mplus command or an error if it cannot be found.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

Examples

## if you have Mplus installed, uncomment and run
## this will give an error if it cannot find Mplus.
## detectMplus()

Automatically detect variables from an Mplus model object

Description

This is a function to automatically detect the variables used in an Mplus model object.

Usage

detectVariables(object, quiet = TRUE)

Arguments

Value

A vector of variables from the R dataset to use.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

See Also

mplusModeler, mplusObject

Examples

example1 <- mplusObject(MODEL = "mpg ON wt;",
  rdata = mtcars, autov = FALSE)
example1$usevariables
MplusAutomation:::detectVariables(example1)

example2 <- mplusObject(MODEL = "mpg ON wt;",
  rdata = mtcars, autov = TRUE)
example2$usevariables
example3 <- update(example2,
  MODEL = ~ . + "mpg ON qsec; wt WITH qsec;",
  autov = TRUE)
example3$usevariables
rm(example1, example2, example3)

Divide text into fields

Description

Helper function to divide an input section into key-value pair list taken from mplus2lavaan

Usage

divideIntoFields(section.text, required)

Arguments

Value

Divided sections

Examples

# make me!!!

Evaluate Conditional

Description

Note that at thie point the comparator must be a number (not another variable).

Usage

evaluateConditional(tag, initCollection)

Arguments

Value

A boolean value indicating whether the conditional is true

Extract function to make Mplus output work with the texreg package

Description

This is a method for extracting output in a format suitable for the texreg package. Uses coef for most the work.

Usage

extract.mplus.model(
  model,
  summaries = "none",
  cis = FALSE,
  escape.latex = FALSE,
  ...
)

extract.mplusObject(model, summaries = "none", cis = FALSE, ...)

## S4 method for signature 'mplus.model'
extract(model, summaries = "none", cis = FALSE, escape.latex = FALSE, ...)

## S4 method for signature 'mplusObject'
extract(model, summaries = "none", cis = FALSE, ...)

Arguments

Value

A texreg object, or for multiple group models, a list of texreg objects.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

See Also

readModels

Other Mplus-Formatting: coef.mplus.model(), confint.mplus.model(), print.MplusRstructure(), summary.mplusObject()

Examples

## Not run: 
# simple example of a model using builtin data
# demonstrates use
test <- mplusObject(
  TITLE = "test the MplusAutomation Package;",
  MODEL = "
    mpg ON wt hp;
    wt WITH hp;",
  OUTPUT = "STANDARDIZED;",
  usevariables = c("mpg", "wt", "hp"),
  rdata = mtcars)

res <- mplusModeler(test, "mtcars.dat", modelout = "model1.inp", run = 1L)

extract(res$results)
# there is also a method for mplusObject class
extract(res)

# load the texreg package
# to use pretty printing via screenreg
# uncomment to run these examples
# library(texreg)
# screenreg(res)
# screenreg(res, type = 'stdyx')

# screenreg(res, type = 'un', params = 'regression',
#   single.row=TRUE)
# screenreg(res, type = 'un', params = 'regression', summaries = 'CFI',
#   single.row=TRUE)

# remove files
unlink("mtcars.dat")
unlink("model1.inp")
unlink("model1.out")
unlink("Mplus Run Models.log")

## End(Not run)

Extract Auxiliary condition means and comparisons.

Description

To do: add details.

Usage

extractAux(outfiletext, filename)

Arguments

Value

A data frame

Extract Latent Class Counts

Description

Function for extracting counts of latent classes

Usage

extractClassCounts(outfiletext, filename, summaries)

Arguments

Value

a list

Examples

# make me!!!

Function to extract the SUMMARY OF DATA section from Mplus outputs

Description

Function to extract the SUMMARY OF DATA section from Mplus outputs

Usage

extractDataSummary(outfiletext, filename)

Arguments

Extract the model parameters from an EFA Mplus model output

Description

Extract the model parameters from an EFA Mplus model output

Usage

extractEFAparameters(outfiletext, filename)

Arguments

Value

list of parsed EFA parameters

Extract Factor Score Statistics

Description

Function for extracting matrices for factor scores

Usage

extractFacScoreStats(outfiletext, filename)

Arguments

Value

A list

See Also

matrixExtract

Examples

# make me!!!

Extract free file output

Description

Function for reading "free" output where a sequence of values populates a matrix

Usage

extractFreeFile(filename, outfile, make_symmetric = TRUE)

Arguments

Value

a matrix

Examples

# make me!!!

Extract Indirect Effects output

Description

This function parses both unstandardized and standardized indirect effects It returns a list composed of $unstandardized and $standardized. The base structure of each is a list containing $overall and $specific effects (as data.frames)

Usage

extractIndirect(outfiletext, curfile)

Arguments

Value

An mplus.indirect object (inherits list) containing $overall and $specific

Extract Indirect Effects output

Description

This function parses a given indirect section It returns a list composed of $overall and $specific effects

Usage

extractIndirect_section(indirectSection, curfile, sectionType)

Arguments

Value

An mplus.indirect object (inherits list) containing $overall and $specific

Extract and parse Mplus input file

Description

Function to extract and parse mplus input syntax from the output file

Usage

extractInput_1file(outfiletext, filename)

Arguments

Value

The parsed input file

Examples

# make me!!!

Extract model modification indices.

Description

Extracts the model modification indices from the MODEL MODIFICATION INDICES section of one or more Mplus output files. If the target is a directory, all .out files therein will be parsed and a single list will be returned, where the list elements are named by the output file name. Returned parameters typically include the pairwise relationships between variables to be freed, the change in model chi-square (M.I.), and the expected parameter change (E.P.C.).

Usage

extractModIndices(target = getwd(), recursive = FALSE, filefilter)

Arguments

Value

If target is a single file, a data.frame containing modification results for the target output file will be returned. If target is a directory, a list will be returned, where each element contains a data.frame of the modification indices for a single file, and the top-level elements are named after the corresponding output file name. The basic data.frame containing the MODEL MODIFICATION INDICES section of outfile. Variables include

Author(s)

Michael Hallquist

See Also

readModels, extractModelSummaries, extractModelParameters

Examples

## Not run: 
ex3.14 <- extractModIndices(
	"C:/Program Files/Mplus/Mplus Examples/User's Guide Examples/ex3.14.out")

## End(Not run)

Extract Modification Indices for One Chunk (Section)

Description

To do: add details.

Usage

extractModIndices_1chunk(chunk, columnNames, filename)

Arguments

Value

A data frame

Extract Modification Indices for One File

Description

To do: add details.

Usage

extractModIndices_1file(outfiletext, filename)

Arguments

Value

A data frame

Extract model parameters from MODEL RESULTS section.

Description

Extracts the model parameters from the MODEL RESULTS section of one or more Mplus output files. If a particular output file has more than one results section (unstandardized, stdyx, stdy, and/or std), a list will be returned. If the target is a directory, all .out files therein will be parsed and a single list will be returned, where the list elements are named by the output file name. Returned parameters often include the parameter estimate, std. err, param/s.e., and two-tailed p-value.

Usage

extractModelParameters(
  target = getwd(),
  recursive = FALSE,
  filefilter,
  dropDimensions = FALSE,
  resultType
)

Arguments

Value

If target is a single file, a list containing unstandardized and standardized results will be returned. If all standardized solutions are available, the list element will be named: unstandardized, stdyx.standardized, stdy.standardized, and std.standardized. If confidence intervals are output using OUTPUT:CINTERVAL, then a list element named ci.unstandardized will be included. Each of these list elements is a data.frame containing relevant model parameters.

If target is a directory, a list will be returned, where each element contains the results for a single file, and the top-level elements are named after the corresponding output file name. Each element within this list is itself a list, with elements as in the single file case above.

The core data.frame for each MODEL RESULTS section typically has the following structure:

In the case of output from Bayesian estimation (ESTIMATOR=BAYES), the data.frame will contain a different set of variables, including some of the above, as well as

Also note that the pval column for Bayesian output represents a one-tailed estimate.

In the case of output from a Monte Carlo study (MONTECARLO: and MODEL POPULATION:), the data.frame will contain a different set of variables, including some of the above, as well as

In the case of confidence interval output (OUTPUT:CINTERVAL), the list element ci.unstandardized will contain a different set of variables, including some of the above, as well as

If the model contains multiple latent classes, an additional variable, LatentClass, will be included, specifying the latent class number. Also, the Categorical Latent Variables section will be included as LatentClass "Categorical.Latent.Variables."

If the model contains multiple groups, Group will be included.

If the model contains two-level output (between/within), BetweenWithin will be included.

Author(s)

Michael Hallquist

See Also

extractModelSummaries

Examples

## Not run: 
ex3.14 <- extractModelParameters(
	"C:/Program Files/Mplus/Mplus Examples/User's Guide Examples/ex3.14.out")

## End(Not run)

Extract summary statistics from a single output file or from a group of Mplus models within a directory

Description

Parses a group of Mplus model output files (.out extension) for model fit statistics. At this time, the details extracted are fixed and include: Filename, InputInstructions, Title, Estimator, LL, BIC, aBIC, AIC, AICC, Parameters, Observations, CFI, TLI, RMSEA_Estimate, RMSEA_90CI_LB, RMSEA_90CI_UB, RMSEA_pLT05, ChiSqM_Value, ChiSqM_DF, ChiSq_PValue, BLRT_KM1LL, BLRT_PValue, BLRT_Numdraws). The infrastructure is in place to allow for user-specified selection of summary statistics in future versions.

Usage

extractModelSummaries(target = getwd(), recursive = FALSE, filefilter)

Arguments

Value

Returns a data.frame containing model fit statistics for all output files within directory. The data.frame contains some of the following variables (depends on model type):

Author(s)

Michael Hallquist

See Also

regex, runModels, readModels

Examples

## Not run: 
  allExamples <- extractModelSummaries(
    "C:/Program Files/Mplus/Mplus Examples/User's Guide Examples")

## End(Not run)

Extract Parameters for One Chunk

Description

Helper function for extractModelParameters. Used to parse each subsection of output within a given file and given results section (e.g., stdyx section) There will be many chunks if latent classes, multiple groups, multilevel features are used.

Usage

extractParameters_1chunk(filename, thisChunk, columnNames, sectionName)

Arguments

Value

A data frame (or matrix?)

Extract Parameters for One File

Description

To do: add details

Usage

extractParameters_1file(outfiletext, filename, resultType, efa = FALSE)

Arguments

Value

A list of parameters

Extract Parameters for One Section

Description

To do: add details

Usage

extractParameters_1section(filename, modelSection, sectionName)

Arguments

Value

A list of parameters

Examples

## Not run: 
  #a few examples of files to parse
  #mg + lc. Results in latent class pattern, not really different from
  #         regular latent class matching. See Example 7.21
  #mg + twolevel. Group is top, bw/wi is 2nd. See Example 9.11
  #lc + twolevel. Bw/wi is top, lc is 2nd. See Example 10.1.
  #               But categorical latent variables is even higher
  #test cases for more complex output: 7.21, 9.7, 9.11, 10.1

## End(Not run)

Extract residual matrices

Description

Function that extracts the residual matrices including standardized ones

Usage

extractResiduals(outfiletext, filename)

Arguments

Value

A list of the residual matrices

See Also

matrixExtract

Examples

# make me!!!

Helper subfunction to extract one section of OUTPUT: RESIDUALS Can be called multiple times, as in the case of invariance testing

Description

Helper subfunction to extract one section of OUTPUT: RESIDUALS Can be called multiple times, as in the case of invariance testing

Usage

extractResiduals_1section(residSection, filename)

Arguments

Helper function to extract the sample statistics from Mplus output Depends on OUTPUT: SAMPSTAT

Description

Helper function to extract the sample statistics from Mplus output Depends on OUTPUT: SAMPSTAT

Usage

extractSampstat(outfiletext, filename)

Arguments

Extract the summaries from one file

Description

Description: This function parses an output file for specific model details. It returns a list of model details for a single output file.

Usage

extractSummaries_1file(outfiletext, filename, input)

Arguments

Value

A list of the summaries

Examples

# make me!!!

Worker function used in extractSummaries_1section

Description

Worker function used in extractSummaries_1section

Usage

extractSummaries_1plan(
  arglist,
  sectionHeaders,
  sectionFields,
  textToParse,
  filename
)

Arguments

Value

A list

Examples

# make me!!!

Extract summary information for one section from Mplus output

Description

Function to extract model fit statistics from a section, wrapped to allow for multiple fit sections, as in EFA files. Calls extractSummaries_1plan

Usage

extractSummaries_1section(modelFitSection, arglist, filename, input = list())

Arguments

Value

The argument list

Examples

# make me!!!

Extract Technical 1 matrix from Mplus

Description

Function that extracts the Tech1 matrix

Usage

extractTech1(outfiletext, filename)

Arguments

Value

A list of class “mplus.tech1”

See Also

matrixExtract

Examples

# make me!!!

Extract Technical 10 matrix from Mplus

Description

Function that extracts the Tech10 matrix

Usage

extractTech10(outfiletext, filename)

Arguments

Value

An empty list

See Also

matrixExtract

Examples

# make me!!!

Extract Technical 12 from Mplus

Description

The TECH12 option is used in conjunction with TYPE=MIXTURE to request residuals for observed versus model estimated means, variances, covariances, univariate skewness, and univariate kurtosis. The observed values come from the total sample. The estimated values are computed as a mixture across the latent classes.

Usage

extractTech12(outfiletext, filename)

Arguments

Value

A list of class “mplus.tech12”

See Also

matrixExtract

Examples

# make me!!!

Extract Technical 15 from Mplus

Description

The TECH15 option is used in conjunction with TYPE=MIXTURE to request conditional probabilities for the latent class variables.

Usage

extractTech15(outfiletext, filename)

Arguments

Value

A list of class “mplus.tech15”

See Also

matrixExtract

Examples

# make me!!!

Extract Technical 3 matrix from Mplus

Description

Function that extracts the Tech3 matrix

Usage

extractTech3(outfiletext, savedata_info, filename)

Arguments

Value

A list of class “mplus.tech3”

See Also

matrixExtract

Examples

# make me!!!

Extract Technical 4 matrix from Mplus

Description

Function that extracts the Tech4 matrix

Usage

extractTech4(outfiletext, filename)

Arguments

Value

A list of class “mplus.tech4”

See Also

matrixExtract

Examples

# make me!!!

Extract Technical 7 from Mplus

Description

The TECH7 option is used in conjunction with TYPE=MIXTURE to request sample statistics for each class using raw data weighted by the estimated posterior probabilities for each class.

Usage

extractTech7(outfiletext, filename)

Arguments

Value

A list of class “mplus.tech7”

See Also

matrixExtract

Examples

# make me!!!

Extract Technical 8 from Mplus

Description

The TECH8 option is used to print the optimization history of a model. It also prints the potential scale reduction in Bayesian models.

Usage

extractTech8(outfiletext, filename)

Arguments

Value

A list of class “mplus.tech8”

See Also

matrixExtract

Examples

# make me!!!

Extract Technical 9 matrix from Mplus

Description

Function that extracts the Tech9 matrix

Usage

extractTech9(outfiletext, filename)

Arguments

Value

A list of class “mplus.tech9”

See Also

matrixExtract

Examples

# make me!!!

Extract values from Mplus output An internal function used by extractSummaries_1file to extract parameters from the output file using regular expressions.

Description

Extract values from Mplus output An internal function used by extractSummaries_1file to extract parameters from the output file using regular expressions.

Usage

extractValue(pattern, textToScan, filename, type = "int")

Arguments

Value

A string or numeric vector

Examples

#make me!!!

Extract warnings and errors from 1 mplus file

Description

Helper function

Usage

extractWarningsErrors_1file(outfiletext, filename, input)

Arguments

Value

A list with two elements

Examples

# make me!!!

Finalize Init Collection

Description

this function should handle initTags that still contain tags once the initCollection is finalized, then process the deferred body tags the notion is that the substitutions will be handled in an inefficient manner – using lots of regular expression parsing, not using the matched tags data.frame

Usage

finalizeInitCollection(initCollection)

Arguments

Details

we only need to handle simple and array tags iterators should always be integers foreach and conditional are not relevant

iterate over init tags until no tags are left here, the init collection should already have had most of its tags substituted by replaceInitTags above.

Value

Finalized initCollection

Friendly Regular Expression

Description

Creates data frame documenting the start and end of all tags.

Usage

friendlyGregexpr(pattern, charvector, perl = TRUE)

Arguments

Value

A data.frame

Author(s)

Michael Hallquist

Examples

## make me

Get Initial Tags

Description

An internal function

Usage

getInitTags(initCollection)

Arguments

Value

The initMatches

Extract a multiline section from Mplus output

Description

New approach to multiline section: retain spaces and look for next line that has identical indentation.

Usage

getMultilineSection(
  header,
  outfiletext,
  filename,
  allowMultiple = FALSE,
  allowSpace = TRUE,
  ignore.case = FALSE
)

Arguments

Value

A list of sections

Examples

# make me!!!

Get Output File List

Description

This is a helper function used by extractModelSummaries and extractModelParameters. It determines whether the target is a single file or a directory. If it is a directory, all .out files are returned (perhaps recursively) It also permits the files to be filtered using a certain regular expression.

Usage

getOutFileList(target, recursive = FALSE, filefilter)

Arguments

Value

A character vector of the output files

Examples

# make me!!!

Load the draws from the Bayesian model posterior distribution (SAVEDATA BPARAMETERS) command into an R data.frame

Description

This function reads a the BPARAMETERS output file from the Mplus SAVEDATA BPARAMETERS command and returns an R data.frame object.

Usage

getSavedata_Bparams(outfile, discardBurnin = TRUE)

Arguments

Value

A list containing the draws from the MCMC chains for a Bayesian model that uses the SAVEDATA BPARAMETERS command. Each list element corresponds to a single MCMC chain, as specified by the ANALYSIS: CHAINS syntax in Mplus. If discardBurnin is FALSE, then a superordinate list is provided that divides output in terms of burn-in versus valid draw halves of the MCMC chains. For documentation of how Mplus implements chain convergence checks and MCMC draws, see here: http://www.statmodel.com/download/Bayes3.pdf.

Note

Note that the outfile parameter should refer to the Mplus output file (.out extension), not the actual dataset generated by SAVEDATA. This function reads information about the dataset from the .out file and loads the dataset accordingly.

Author(s)

Michael Hallquist, Florian Boeing-Messing

References

http://www.statmodel.com/download/Bayes3.pdf

See Also

getSavedata_Fileinfo, getSavedata_Data

Examples

## Not run: 
  fileInfo <- getSavedata_Data("C:/Program Files/Mplus/Test Output.out")

## End(Not run)

Load an analysis dataset from the SAVEDATA command into an R data.frame

Description

This function reads an analysis dataset generated by the Mplus SAVEDATA command and returns an R data.frame object.

Usage

getSavedata_Data(outfile)

Arguments

Value

A data.frame containing the analysis dataset generated by the SAVEDATA command.

Note

Note that the outfile parameter should refer to the Mplus output file (.out extension), not the actual dataset generated by SAVEDATA. This function reads information about the dataset from the .out file and loads the dataset accordingly.

Author(s)

Michael Hallquist

See Also

getSavedata_Fileinfo

Examples

## Not run: 
  savedat <- getSavedata_Data("C:/Program Files/Mplus/Test Output.out")

## End(Not run)

Read Variable Names, Formats, and Widths from data generated by the SAVEDATA Command

Description

This function reads the SAVEDATA INFORMATION section from an Mplus output file that used the SAVEDATA command, and it returns a list with the filename, variable names, variable formats, and variable widths of the SAVEDATA file. If present, the function also parses information about the Bayesian Parameters (BPARAMETERS) file.

Usage

getSavedata_Fileinfo(outfile)

Arguments

Value

Returns a list of SAVEDATA file information that includes:

Author(s)

Michael Hallquist

See Also

getSavedata_Data

Examples

## Not run: 
  fileInfo <- getSavedata_Fileinfo("C:/Program Files/Mplus/Test Output.out")

## End(Not run)

Get an Output Section

Description

Get an Output Section

Usage

getSection(sectionHeader, outfiletext, headers = "standard")

Arguments

Value

Section

Examples

# make me!!!

Small helper function to obtain number of factors for an EFA output section

Description

Small helper function to obtain number of factors for an EFA output section

Usage

get_efa_nfactors(headers)

Arguments

Value

A vector of the number of factors in each heading, or a matrix if multilevel output

Extract Mplus results

Description

This function allows users to extract elements of Mplus output by name from different types of objects returned by MplusAutomation.

Usage

get_results(x, element, simplify = FALSE, ...)

get_input(x, simplify = FALSE, ...)

get_warn_err(x, simplify = FALSE, ...)

get_data_summary(x, simplify = FALSE, ...)

get_sampstat(x, simplify = FALSE, ...)

get_covariance_coverage(x, simplify = FALSE, ...)

get_summaries(x, simplify = FALSE, ...)

get_invariance_testing(x, simplify = FALSE, ...)

get_parameters(x, simplify = FALSE, ...)

get_class_counts(x, simplify = FALSE, ...)

get_indirect(x, simplify = FALSE, ...)

get_mod_indices(x, simplify = FALSE, ...)

get_residuals(x, simplify = FALSE, ...)

get_savedata(x, simplify = FALSE, ...)

get_bparameters(x, simplify = FALSE, ...)

get_tech1(x, simplify = FALSE, ...)

get_tech3(x, simplify = FALSE, ...)

get_tech4(x, simplify = FALSE, ...)

get_tech7(x, simplify = FALSE, ...)

get_tech8(x, simplify = FALSE, ...)

get_tech9(x, simplify = FALSE, ...)

get_tech10(x, simplify = FALSE, ...)

get_tech12(x, simplify = FALSE, ...)

get_tech15(x, simplify = FALSE, ...)

get_fac_score_stats(x, simplify = FALSE, ...)

get_lcCondMeans(x, simplify = FALSE, ...)

get_gh5(x, simplify = FALSE, ...)

Arguments

Value

An atomic vector or matrix or list of the same length as X (of length n for replicate). If simplification occurs, the output type is determined from the highest type of the return values in the hierarchy NULL < raw < logical < integer < double < complex < character < list < expression, after coercion of pairlists to lists.

Examples

## Not run: 
 test <- mplusObject(MODEL = "mpg ON wt hp;
 wt WITH hp;", rdata = mtcars)
 res <- mplusModeler(test, modelout = "model1.inp", run = 1L)
 get_results(res, "summaries")
 unlink(res$results$input$data$file)
 unlink("model1.inp")
 unlink("model1.out")

## End(Not run)
out <- get_input(res)
out <- get_warn_err(res)
out <- get_data_summary(res)
out <- get_sampstat(res)
out <- get_covariance_coverage(res)
out <- get_summaries(res)
out <- get_invariance_testing(res)
out <- get_parameters(res)
out <- get_class_counts(res)
out <- get_indirect(res)
out <- get_mod_indices(res)
out <- get_residuals(res)
out <- get_savedata(res)
out <- get_bparameters(res)
out <- get_tech1(res)
out <- get_tech3(res)
out <- get_tech4(res)
out <- get_tech7(res)
out <- get_tech8(res)
out <- get_tech9(res)
out <- get_tech10(res)
out <- get_tech12(res)
out <- get_tech15(res)
out <- get_fac_score_stats(res)
out <- get_lcCondMeans(res)
out <- get_gh5(res)

Create a graphic model from Mplus

Description

To do: add details

Usage

graphModel(model)

Arguments

Value

a dot model

Read in Mplus Output File from HTML on the Mplus Website

Description

This is an internal utility function to help with testing MplusAutomation. On the Mplus website, many output files are included, which are good tests. However, they are stored in HTML files. This function reads them in, strips the HTML parts leaving just the output file, and then writes it to disk and returns the file name, which can be used with readModels() for testing.

Usage

htmlout(url)

Arguments

Value

A character string that is the filename where the output file was written. Always a temp file in a temp directory.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

Examples

MplusAutomation:::htmlout("https://statmodel.com/usersguide/chap3/ex3.1.html")

Check whether a useable function argument was provided

Description

This is a simple utility to check whether a function argument is missing, NULL, or has only NAs.

Usage

isEmpty(arg)

Arguments

Value

Logical vector of length 1.

Examples

## Not run: 
f1 <- function(x) {
  if (!isEmpty(x)) return(mean(x, na.rm = TRUE))
  return(NULL)
}

f1()                 #> NULL
f1(x = NA)           #> NULL
f1(x = NULL)         #> NULL
f1(x = c(NA, 1:2))   #> 1.5

## End(Not run)

Internal function to load the draws from the Bayesian model posterior distribution

Description

To do: add details.

Usage

l_getSavedata_Bparams(outfile, outfiletext, fileInfo, discardBurnin = TRUE)

Arguments

Value

A list of class mcmc and mplus.bparameters

local function that does the work of getSaveData_Fileinfo

Description

This function is split out so that getSaveData_Fileinfo is exposed to the user, but the parsing function can be used by readModels

Usage

l_getSavedata_Fileinfo(outfile, outfiletext, summaries)

Arguments

Value

A list that includes:

See Also

getSavedata_Data

Examples

# make me!

Internal function to load the draws from the Bayesian model posterior distribution

Description

This function is used by other extractor functions that read particular types of saved data such as factor scores or iterations from an MCMC chain.

Usage

l_getSavedata_readRawFile(
  outfile,
  outfiletext,
  format = "fixed",
  fileName,
  varNames,
  varWidths,
  input
)

Arguments

Value

A data frame of the extracted data.

Latent Class Analysis Demonstration

Description

A list containing the Mplus Data, Output Files, and GH5 Files for a demonstration of using MplusAutomation for latent class analysis. Generated by the vignette on latent class analysis.

Usage

lcademo

Format

A list containing 11 elements.

Data

2 Class LCA data simulated using Mplus

CFA

Mplus output file for CFA

LCA2

Mplus output file for 2 class LCA

LCA3

Mplus output file for 3 class LCA

LCA4

Mplus output file for 4 class LCA

LCA5

Mplus output file for 5 class LCA

CFAGH5

GH5 file for CFA

LCA2GH5

GH5 file for 2 class LCA

LCA3GH5

GH5 file for 3 class LCA

LCA4GH5

GH5 file for 4 class LCA

LCA5GH5

GH5 file for 5 class LCA

Long data to wide latent growth mixture model

Description

This function streamlines the process of converting long data into a format that Mplus can use for latent growth mixture models in wide form. It makes use of continuous time scores, and these time scores must be supplied as variables in the R dataset. For the conversion to wide form, it is assumed that although assessments may have happened in continuous time, a discrete number of assessments (likely ismilar for all participants) were collected.

Usage

long2LGMM(
  data,
  idvar,
  assessmentvar,
  dv,
  timevars,
  misstrick = TRUE,
  k = 1L,
  title = "Trajectory Model",
  base = "trajmodel_",
  run = FALSE,
  processors = 1L,
  starts = "500 100",
  newdata,
  cov = c("un", "independent", "intercept", "zero"),
  model
)

Arguments

Details

One valuable feature of this function is that it makes it possible to feed any continuous time scores to Mplus for mixture modelling. For example, continuous linear time is straightforward, but so to are quadratic time models or piecewise models. Using facilities in R, spline models are also comparatively easy to specify.

Examples

## Not run: 
## Simulate Some Data from 3 classes
library(MASS)
set.seed(1234)
allcoef <- rbind(
  cbind(1, mvrnorm(n = 200,
                   mu = c(0, 2, 0),
                   Sigma = diag(c(.2, .1, .01)),
                   empirical = TRUE)),
  cbind(2, mvrnorm(n = 200,
                   mu = c(-3.35, 2, 2),
                   Sigma = diag(c(.2, .1, .1)),
                   empirical = TRUE)),
  cbind(3, mvrnorm(n = 200,
                   mu = c(3.35, 2, -2),
                   Sigma = diag(c(.2, .1, .1)),
                   empirical = TRUE)))
allcoef <- as.data.frame(allcoef)
names(allcoef) <- c("Class", "I", "L", "Q")
allcoef$ID <- 1:nrow(allcoef)
d <- do.call(rbind, lapply(1:nrow(allcoef), function(i) {
  out <- data.frame(
    ID = allcoef$ID[i],
    Class = allcoef$Class[i],
    Assess = 1:11,
    x = sort(runif(n = 11, min = -2, max = 2)))
  out$y <- rnorm(11,
    mean = allcoef$I[i] + allcoef$L[i] * out$x + allcoef$Q[i] * out$x^2,
    sd = .1)
  return(out)
}))

## create splines
library(splines)
time_splines <- ns(d$x, df = 3, Boundary.knots = quantile(d$x, probs = c(.02, .98)))
d$t1 <- time_splines[, 1]
d$t2 <- time_splines[, 2]
d$t3 <- time_splines[, 3]
d$xq <- d$x^2

## create new data to be used for predictions
nd <- data.frame(ID = 1,
                 x = seq(from = -2, to = 2, by = .1))
nd.splines <- with(attributes(time_splines),
                   ns(nd$x, df = degree, knots = knots,
                      Boundary.knots = Boundary.knots))
nd$t1 <- nd.splines[, 1]
nd$t2 <- nd.splines[, 2]
nd$t3 <- nd.splines[, 3]
nd$xq <- nd$x^2

## create a tuning grid of models to try
## all possible combinations are created of different time trends
## different covariance structures of the random effects
## and different number of classes
tuneGrid <- expand.grid(
  dv = "y",
  timevars = list(c("t1", "t2", "t3"), "x", c("x", "xq")),
  starts = "2 1",
  cov = c("independent", "zero"),
  k = c(1L, 3L),
  processors = 1L, run = TRUE,
  misstrick = TRUE, stringsAsFactors = FALSE)
tuneGrid$title <- paste0(
  c("linear", "quad", "spline")[sapply(tuneGrid$timevars, length)],
  "_",
  sapply(tuneGrid$cov, function(x) if(nchar(x)==4) substr(x, 1, 4) else substr(x, 1, 3)),
  "_",
  tuneGrid$k)
tuneGrid$base <- paste0(
  c("linear", "quad", "spline")[sapply(tuneGrid$timevars, length)],
  "_",
  sapply(tuneGrid$cov, function(x) if(nchar(x)==4) substr(x, 1, 4) else substr(x, 1, 3)))

## example using long2LGMM to fit one model at a time
mres <- long2LGMM(
        data = d,
        idvar = "ID",
        assessmentvar = "Assess",
        dv = tuneGrid$dv[1],
        timevars = tuneGrid$timevars[[1]],
        misstrick = tuneGrid$misstrick[1],
        k = tuneGrid$k[1],
        title = paste0(tuneGrid$title[1], tuneGrid$k[1]),
        base = tuneGrid$base[1],
        run = tuneGrid$run[1],
        processors = tuneGrid$processors[1],
        starts = tuneGrid$starts[1],
        newdata = nd,
        cov = tuneGrid$cov[1])

rm(mres)

## End(Not run)

Simple tag lookup

Description

The purpose of this function is to set the currentValue column for the bodyTags and initTags data.frames for simple tags only. Most values will be replaced at the bottom level of recursion, but simple tags do not change over iterations, so can be set one time.

Usage

lookupSimpleTags(templateTags, initCollection)

Arguments

Value

A tag.

Lookup the matrix element for a give parameter number

Description

The lookupTech1Parameter function identifies the position in the Mplus model matrices corresponding to a given parameter defined in the TECHNICAL 1 PARAMETER SPECIFICATION OUTPUT. The goal of this function is to aid in identifying problematic parameters often printed in the warnings and errors section of Mplus output.

Usage

lookupTech1Parameter(tech1Output, paramNumber)

Arguments

Value

A data.frame containing the row(s) and column(s) of TECH1 parameter specification matching the requested paramNumber.

Author(s)

Michael Hallquist

See Also

readModels

Examples

## Not run: 
  models <- readModels("test1.out")
  param <- lookupTech1Parameter(models$tech1, 16)

## End(Not run)

Lookup values

Description

To do: fill in some details

Usage

lookupValue(tag, tagType, initCollection)

Arguments

Value

Current value

Reconstruct matrix from multi-line text output

Description

main worker function for extracting Mplus matrix output where matrices are spread across blocks to keep within width constraints example: tech1 matrix output.

Usage

matrixExtract(
  outfiletext,
  headerLine,
  filename,
  ignore.case = FALSE,
  expect_sig = FALSE
)

Arguments

Value

a matrix

Examples

# make me!!!

Create a summary table of Mplus mixture models

Description

Creates a summary table of model fit statistics and relevant diagnostic information for a list of mixture models. Default statistics reported are in line with published guidelines (see Jung & Wickrama, 2008; Nylund et al., 2007): c("Title", "Classes", "Warnings", "AIC", "BIC", "aBIC", "Entropy", "T11_VLMR_PValue", "T11_LMR_PValue", "BLRT_PValue", "min_N", "max_N", "min_prob", "max_prob"). The table is customizable using the keepCols parameter, which is passed through to SummaryTable.

Usage

mixtureSummaryTable(
  modelList,
  keepCols = c("Title", "Classes", "Warnings", "AIC", "BIC", "aBIC", "Entropy",
    "T11_VLMR_PValue", "T11_LMR_PValue", "BLRT_PValue", "min_N", "max_N", "min_prob",
    "max_prob"),
  sortBy = NULL,
  ...
)

Arguments

Value

An object of class data.frame.

Note

This function is partially a wrapper around SummaryTable, with enhancements for summarizing mixture models.

Author(s)

Caspar J. van Lissa

See Also

SummaryTable

Examples

## Not run: 
res <- createMixtures(classes = 1:2, filename_stem = "iris", rdata = iris,
               OUTPUT = "tech11 tech14;",
               run = 1L)
mixtureSummaryTable(res)

## End(Not run)

Plot the samples for each MCMC chain as a function of iterations

Description

Displays a traceplot of the MCMC draws from the poster distribution of each parameter estimate for a Bayesian Mplus model. This function requires that 1) PLOT: TYPE=PLOT2; be included in the Mplus input file, 2) a gh5 file be present corresponding to the Mplus output file (and containing a bayesian_data section), and 3) that the rhdf5 package be installed to allow the gh5 file to be imported.

Usage

mplus.traceplot(mplus.model, rows = 4, cols = 4, parameters_only = TRUE)

Arguments

Details

A multi-panel plot is drawn to the screen and the user is prompted to display the next plot if more than rows x columns estimates are in the model.

Value

No value is returned by this function. Called for the side effect of displaying an MCMC chains traceplot.

Note

Trace and density plots can also be obtained using the coda package and the bparameters element of the mplus.model object. This requires that the posterior draws be saved using SAVEDATA: BPARAMETERS syntax. See example below.

Author(s)

Joseph Glass, Michael Hallquist

See Also

plot.mcmc

Examples

## Not run: 
  myModel <- readModels("BayesModel_WithGH5MCMC.out")
  mplus.traceplot(myModel, rows=2, cols=3)

  #alternative using the coda package
  library(coda)
  plot(myModel$bparameters$valid_draw)

## End(Not run)

Check whether Mplus can be found

Description

This is a simple utility to check whether Mplus can be found. Returns 0 if Mplus command can be found by the system. If silent = FALSE, prints a message to the user to help suggest what to do.

Usage

mplusAvailable(silent = TRUE)

Arguments

Value

The status of finding Mplus. Per unix conventions, status 0 indicates Mplus was found (0 problems) and status 1 indicates that Mplus was not found.

Author(s)

Joshua Wiley

Examples

mplusAvailable(silent = TRUE)
mplusAvailable(silent = FALSE)

Function to fit GLMs in Mplus

Description

The purpose of this function is to make it (relatively) easy to fit (most) generalized linear models in Mplus. Fitting GLMs in Mplus offers advantages such as using full information maximum likelihood for missing data, robust estimators (default used is MLR), and standard errors adjusted for clustering (planned; not currently available via mplusGLM(). The overarching aim of this function is to make most GLMs as easy to fit in Mplus as they are in R.

Usage

mplusGLM(formula, data, idvar = "", ...)

Arguments

Details

Note that although there are benefits to fitting GLMs in Mplus. Caution also is warranted. Using full information maximum likelihood for missing data requires a number of assumptions. These may be (badly) violated. mplusGLM() requires the analyst to check these as appropriate.

Currently, mplusGLM() only supports multinomial outcomes. More outcomes are planned in the future including binary, continuous/normal, and count outcomes.

Value

A list of results and Mplus model object.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

Examples

## Not run: 
set.seed(1234)
tmpd <- data.frame(
  x1 = rnorm(200),
  x2 = rnorm(200),
  x3 = cut(rnorm(200),
           breaks = c(-Inf, -.7, .7, Inf),
           labels = c("a", "b", "c")))
tmpd$y <- cut(rnorm(200, sd = 2) + tmpd$x1 + tmpd$x2 + I(tmpd$x3 == "b"),
              breaks = c(-Inf, -.5, 1, Inf),
              labels = c("L", "M", "H"))
test <- mplusGLM(y ~ x1 + x2 + x3, data = tmpd)

## End(Not run)

Create, run, and read Mplus models.

Description

This is a convenience wrapper to automate many of the usual steps required to run an Mplus model. It relies in part on functions from the MplusAutomation package.

Usage

mplusModeler(
  object,
  dataout,
  modelout,
  run = 0L,
  check = FALSE,
  varwarnings = TRUE,
  Mplus_command = detectMplus(),
  writeData = c("ifmissing", "always", "never"),
  hashfilename = TRUE,
  killOnFail = TRUE,
  quiet = TRUE,
  ...
)

Arguments

Details

Combined with functions from the MplusAutomation package, this function is designed to make it easy to fit Mplus models from R and to ease many of the usual frustrations with Mplus. For example, Mplus has very specific formats it accepts data in, but also very little data management facilities. Using R data management is easy. This function is designed to make using data from R in Mplus models easy. It is also common to want to fit many different models that are slight variants. This can be tedius in Mplus, but using R you can create one basic set of input, store it in a vector, and then just modify that (e.g., using regular expressions) and pass it to Mplus. You can even use loops or the *apply constructs to fit the same sort of model with little variants.

The writeData argument is new and can be used to reduce overhead from repeatedly writing the same data from R to the disk. When using the ‘always’ option, mplusModeler behaves as before, always writing data from R to the disk. This remains the default for the prepareMplusData function to avoid confusion or breaking old code. However, for mplusModeler, the default has been set to ‘ifmissing’. In this case, R generates an md5 hash of the data prior to writing it out to the disk. The md5 hash is based on: (1) the dimensions of the dataset, (2) the variable names, (3) the class of every variable, and (4) the raw data from the first and last rows. This combination ensures that under most all circumstances, if the data changes, the hash will change. The hash is appended to the specified data file name (which is controlled by the logical hashfilename argument). Next R checks in the directory where the data would normally be written. If a data file exists in that directory that matches the hash generated from the data, R will use that existing data file instead of writing out the data again. A final option is ‘never’. If this option is used, R will not write the data out even if no file matching the hash is found.

Value

An Mplus model object, with results. If run = 1, returns an invisible list of results from the run of the Mplus model (see readModels from the MplusAutomation package). If run = 0, the function returns a list with two elements, ‘model’ and ‘boot’ that are both NULL. if run >= 1,returns a list with two elements, ‘model’ and ‘boot’ containing the regular Mplus model output and the boot object, respectively. In all cases, the Mplus data file and input files are created.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

See Also

runModels and readModels

Examples

## Not run: 
# minimal example of a model using builtin data, allowing R
# to automatically guess the correct variables to use
test <- mplusObject(MODEL = "mpg ON wt hp;
  wt WITH hp;", rdata = mtcars)

 # estimate the model in Mplus and read results back into R
 res <- mplusModeler(test, modelout = "model1.inp", run = 1L)

 # when forcing writeData = "always" data gets overwritten (with a warning)
 resb <- mplusModeler(test, modelout = "model1.inp", run = 1L,
                      writeData = "always")

 # using writeData = "ifmissing", the default, no data re-written
 resc <- mplusModeler(test, modelout = "model1.inp", run = 1L)

 # using writeData = "ifmissing", the default, data ARE written
 # if data changes
 test <- mplusObject(MODEL = "mpg ON wt hp;
   wt WITH hp;", rdata = mtcars[-10, ])
 resd <- mplusModeler(test, modelout = "model1.inp", run = 1L)

 # show summary
 summary(resd)

 # show coefficients
 coef(resd)

 # what if you wanted confidence intervals
 # and standardized values?
 # first update to tell Mplus you want them, re-run and print
 test <- update(test, OUTPUT = ~ "CINTERVAL; STDYX;")
 resd <- mplusModeler(test, modelout = "model1.inp", run = 1L)

coef(resd)
confint(resd)

# now standardized
coef(resd, type = "stdyx")
confint(resd, type = "stdyx")

# put together in one data frame if desired
merge(
  coef(resd, type = "stdyx"),
  confint(resd, type = "stdyx"),
  by = "Label")

 # remove files
 unlink(resc$results$input$data$file)
 unlink(resd$results$input$data$file)
 unlink("model1.inp")
 unlink("model1.out")

# simple example of a model using builtin data
# demonstrates use with a few more sections
test2 <- mplusObject(
  TITLE = "test the MplusAutomation Package and mplusModeler wrapper;",
  MODEL = "
    mpg ON wt hp;
    wt WITH hp;",
  usevariables = c("mpg", "wt", "hp"),
  rdata = mtcars)

 res2 <- mplusModeler(test2, modelout = "model2.inp", run = 1L)

 # remove files
 unlink(res2$results$input$data$file)
 unlink("model2.inp")
 unlink("model2.out")

 # similar example using a robust estimator for standard errors
 # and showing how an existing model can be easily updated and reused
 test3 <- update(test2, ANALYSIS = ~ "ESTIMATOR = MLR;")

 res3 <- mplusModeler(test3, modelout = "model3.inp", run = 1L)
 unlink(res3$results$input$data$file)
 unlink("model3.inp")
 unlink("model3.out")

 # now use the built in bootstrapping methods
 # note that these work, even when Mplus will not bootstrap
 # also note how categorical variables and weights are declared
 # in particular, the usevariables for Mplus must be specified
 # because mroe variables are included in the data than are in the
 # model. Note the R usevariables includes all variables for both
 # model and weights. The same is true for clustering.
 test4 <- mplusObject(
   TITLE = "test bootstrapping;",
   VARIABLE = "
     CATEGORICAL = cyl;
     WEIGHT = wt;
     USEVARIABLES = cyl mpg;",
   ANALYSIS = "ESTIMATOR = MLR;",
   MODEL = "
     cyl ON mpg;",
   usevariables = c("mpg", "wt", "cyl"),
   rdata = mtcars)

 res4 <- mplusModeler(test4, "mtcars.dat", modelout = "model4.inp", run = 10L,
   hashfilename = FALSE)
 # see the results
 res4$results$boot

 # remove files
 unlink("mtcars.dat")
 unlink("model4.inp")
 unlink("model4.out")

# Monte Carlo Simulation Example
montecarlo <- mplusObject(
 TITLE = "Monte Carlo Example;",
 MONTECARLO = "
  NAMES ARE i1-i5;
  NOBSERVATIONS = 100;
  NREPS = 100;
  SEED = 1234;",
 MODELPOPULATION = "
  f BY i1-i5*1;
  f@1;
  i1-i5*1;",
 ANALYSIS = "
  ESTIMATOR = BAYES;
  PROC = 2;
  fbiter = 100;",
 MODEL = "
  f BY i1-i5*.8 (l1-l5);
  f@1;
  i1-i5*1;",
 MODELPRIORS = "
   l1-l5 ~ N(.5 .1);",
 OUTPUT = "TECH9;")

fitMonteCarlo <- mplusModeler(montecarlo,
  modelout = "montecarlo.inp",
  run = 1L,
  writeData = "always",
  hashfilename = FALSE)

unlink("montecarlo.inp")
unlink("montecarlo.out")


# Example including ID variable and extracting factor scores
dat <- mtcars
dat$UID <- 1:nrow(mtcars)

testIDs <- mplusObject(
  TITLE = "test the mplusModeler wrapper with IDs;",
  VARIABLE = "IDVARIABLE = UID;",
  MODEL = "
    F BY mpg wt hp;",
  SAVEDATA = "
    FILE IS testid_fscores.dat;
    SAVE IS fscores;
    FORMAT IS free;",
  usevariables = c("UID", "mpg", "wt", "hp"),
  rdata = dat)

 resIDs <- mplusModeler(testIDs, modelout = "testid.inp", run = 1L)

# view the saved data from Mplus, including factor scores
# the indicator variables, and the ID variable we specified
head(resIDs$results$savedata)

# merge the factor scores with the rest of the original data
# merge together by the ID column
dat <- merge(dat, resIDs$results$savedata[, c("F", "UID")],
  by = "UID")

# correlate merged factor scores against some other new variable
with(dat, cor(F, qsec))




# can write multiply imputed data too
# here are three "imputed" datasets
idat <- list(
  data.frame(mpg = mtcars$mpg, hp = c(100, mtcars$hp[-1])),
  data.frame(mpg = mtcars$mpg, hp = c(110, mtcars$hp[-1])),
  data.frame(mpg = mtcars$mpg, hp = c(120, mtcars$hp[-1])))

# if we turn on hashing in the filename the first time,
# we can avoid overwriting notes the second time
testobjimp <- mplusObject(MODEL = "[mpg];", rdata = idat, imputed = TRUE)

testimp <- mplusModeler(
  testobjimp,
  modelout = "testimp.inp",
  writeData = "ifmissing", hashfilename=FALSE)

testimp <- mplusModeler(
  testobjimp,
  modelout = "testimp.inp",
  writeData = "ifmissing", hashfilename=TRUE)

testimp <- mplusModeler(
  testobjimp,
  modelout = "testimp.inp",
  writeData = "ifmissing", hashfilename=TRUE,
  run = TRUE)

testobjimp2 <- mplusObject(MODEL = "[hp];", rdata = idat, imputed = TRUE)
testimp2 <- mplusModeler(
  testobjimp2,
  modelout = "testimp2.inp",
  writeData = "ifmissing", hashfilename=TRUE,
  run = TRUE)

 # remove files
 unlink(resIDs$results$input$data$file)
 unlink("testid.inp")
 unlink("testid.out")
 unlink("testid_fscores.dat")
 unlink("Mplus Run Models.log")

## End(Not run)

Create an Mplus model object

Description

This is a function to create an Mplus model object in R. The object holds all the sections of an Mplus input file, plus some extra R ones. Once created, the model can be run using other functions such as mplusModeler or updated using methods defined for the update function.

Usage

mplusObject(
  TITLE = NULL,
  DATA = NULL,
  VARIABLE = NULL,
  DEFINE = NULL,
  MONTECARLO = NULL,
  MODELPOPULATION = NULL,
  MODELMISSING = NULL,
  ANALYSIS = NULL,
  MODEL = NULL,
  MODELINDIRECT = NULL,
  MODELCONSTRAINT = NULL,
  MODELTEST = NULL,
  MODELPRIORS = NULL,
  OUTPUT = NULL,
  SAVEDATA = NULL,
  PLOT = NULL,
  usevariables = NULL,
  rdata = NULL,
  autov = TRUE,
  imputed = FALSE,
  quiet = TRUE,
  ...
)

Arguments

Details

Mplus model objects allow a base model to be defined, and then flexibly update the data, change the precise model, etc. If a section does not vary between models, you can leave it the same. For example, suppose you are fitting a number of models, but in all cases, wish to use maximum likelihood estimator, “ANALYSIS: ESTIMATOR = ML;” and would like standardized output, “OUTPUT: STDYX;”. Rather than retype those in every model, they can be defined in one Mplus model object, and then that can simply be updated with different models, leaving the analysis and output sections untouched. This also means that if a reviewer comes back and asks for all analyses to be re-run say using the robust maximum likelihood estimator, all you have to do is change it in the model object once, and re run all your code.

Value

A list of class mplusObject with elements

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

See Also

mplusModeler

Examples

example1 <- mplusObject(MODEL = "mpg ON wt;",
  usevariables = c("mpg", "hp"), rdata = mtcars)
str(example1)
rm(example1)

# R figures out the variables automagically, with a message
example2 <- mplusObject(MODEL = "mpg ON wt;",
  rdata = mtcars, autov = TRUE)
str(example2)
rm(example2)

# R can also try to figure out a list of variables when
# variable names are hyphenated first-last variable, all variables
# between the first and last one will be included
example3 <- mplusObject(MODEL = "mpg ON wt-vs;",
  rdata = mtcars, autov = TRUE)
str(example3)
rm(example3)

# R warns if the first 8 characters of a (used) variable name are not unique
# as they will be indistinguishable in the Mplus output
example4 <- mplusObject(MODEL = "basename_01 ON basename_02;",
  rdata = data.frame(basename_01 = 1:5, basename_02 = 5:1),
  autov = TRUE)
rm(example4)

Create Mplus code for various residual covariance structures.

Description

This function makes it easy to write the Mplus syntax for various residual covariance structure.

Usage

mplusRcov(
  x,
  type = c("homogenous", "heterogenous", "cs", "toeplitz", "ar", "un"),
  r = "rho",
  e = "e",
  collapse = FALSE
)

Arguments

Details

The homogenous residual covariance structure estimates one parameter: the residual variance, \sigma^{2}_{e}. The residual variance is assumed to be identical for all variables and all covariances are assumed to be zero. The structure is represented in this table.

The heterogenous residual covariance structure estimates n parameters, where n is the number of variables. A unique residual variance is estimated for every variable. All covariances are assumed to be zero. The structure is represented in this table.

The compound symmetric residual covariance structure estimates two parameters: one for the residual variance , \sigma^{2}_{e}, and one for the covariance. The residual variance is assumed to be identical for all variables and all covariances are assumed to be identical. The structure is represented in this table.

The toeplitz residual covariance structure estimates n parameters, one for every band of the matrix. The residual variance , \sigma^{2}_{e}, is assumed to be identical for all variables. The covariances one step removed are all assumed identical. Likewise for all further bands. The structure is represented in this table.

The autoregressive residual covariance structure has two parameters: the residual variance, \sigma^{2}_{e} and the correlation between adjacent time points, \rho. The variances are constrained to be equal for all time points. A single correlation parameter is estimated. The \rho is the correlation between adjacent time points such as 1 and 2 or 2 and 3. More distant relationships are assumed to have smaller correlations, decreasing exponentially. Thus between 1 and 3, the estimate is \rho^2. The structure is represented in this table.

Because structural equation models generally model covariance structures, the autoregressive residual structure must be parameterized in terms of covariances. This is done in two parts. First, the function returns syntax to estimate all the pairwise covariances, labelling the parameters \rho, \rho^2, etc. so that they are constrained to be equal. Next, it returns the syntax for the necessary model constraints to constrain the different covariances, to decrease exponentially in their correlations. This is done via:

\rho^2 = (\frac{\rho}{\sigma^2_{e}})^{2}\sigma^2_{e}

and likewise for all later time points.

The unstructured residual covariance structure estimates \frac{n(n + 1)}{2} parameters. It is unstructured in that every variance and covariance is freely estimated with no constraints. However, in most cases, this results in an overparameterized model and is unestimable. The structure is represented in this table.

Value

A named character vector of class ‘MplusRstructure’ with four elements:

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

Examples

# all five structures collapsing
mplusRcov(letters[1:4], "homogenous", "rho", "e", TRUE)
mplusRcov(letters[1:4], "heterogenous", "rho", "e", TRUE)
mplusRcov(letters[1:4], "cs", "rho", "e", TRUE)
mplusRcov(letters[1:4], "toeplitz", "rho", "e", TRUE)
mplusRcov(letters[1:4], "ar", "rho", "e", TRUE)
mplusRcov(letters[1:4], "un", "rho", "e", TRUE)

# all five structures without collapsing
# useful for long names or many variables
# where a line may cross 80 characters
mplusRcov(letters[1:4], "homogenous", "rho", "e", FALSE)
mplusRcov(letters[1:4], "heterogenous", "rho", "e", FALSE)
mplusRcov(letters[1:4], "cs", "rho", "e", FALSE)
mplusRcov(letters[1:4], "toeplitz", "rho", "e", FALSE)
mplusRcov(letters[1:4], "ar", "rho", "e", FALSE)
mplusRcov(letters[1:4], "un", "rho", "e", FALSE)

Convert Mplus Number to Numeric

Description

Helper function to convert strings formatted in Mplus Fortran-style scientific notation using D to indicate double.

Usage

mplus_as.numeric(vec, expect_sig = FALSE)

Arguments

Value

A numeric vector

Examples

MplusAutomation:::mplus_as.numeric("3.1D2")

Extract parameters from a data frame of Mplus estimates

Description

This is a simple convenience function designed to facilitate looking at specific parameter types by easily return a subset of a data frame with those types only. It is designed to follow up the results returned from the readModels function.

Usage

paramExtract(
  x,
  params = c("regression", "loading", "undirected", "expectation", "variability", "new")
)

Arguments

Value

A subset data frame with the parameters of interest.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

See Also

readModels

Examples

## Not run: 
  test <- mplusObject(
    TITLE = "test the MplusAutomation Package and my Wrapper;",
    MODEL = "
      mpg ON wt hp;
      wt WITH hp;",
    usevariables = c("mpg", "wt", "hp"),
    rdata = mtcars)

  res <- mplusModeler(test, "mtcars.dat", modelout = "model1.inp", run = 1L)

  # store just the unstandardized parameters in 'd'
  d <- res$results$parameters$unstandardized
  # extract just regression parameters
  paramExtract(d, "regression")
  # extract other types of parameters using shorthand
  paramExtract(d, "u")
  paramExtract(d, "e")
  paramExtract(d, "v")

## End(Not run)

Parse Categorical Output

Description

Helper function for parsing output with variables and categories.

Usage

parseCatOutput(text)

Arguments

Value

The parsed output

Author(s)

Michael Hallquist

Examples

"
Example:
UNIVARIATE PROPORTIONS AND COUNTS FOR CATEGORICAL VARIABLES

SOP2A
  Category 1    0.254      631.000
  Category 2    0.425     1056.000
  Category 3    0.174      432.000
  Category 4    0.147      365.000

Or Item Categories in IRT Parameterization

Item Categories
 U1
   Category 1         0.000      0.000      0.000      1.000
   Category 2        -0.247      0.045     -5.534      0.000
   Category 3         0.699      0.052     13.325      0.000
   Category 4        -0.743      0.057    -12.938      0.000
   Category 5         0.291      0.052      5.551      0.000
"

Check Mplus code for missing semicolons or too long lines.

Description

The function parses a character string containing Mplus code and checks that every non blank line ends in either a colon or a semicolon. In addition, it checks that every line is less than 90 characters, because Mplus ignores everything after 90 characters on a line which can be a source of enigmatic errors.

Usage

parseMplus(x, add = FALSE)

Arguments

Details

The function is fairly basic at the moment. It works by simply removing blank space (spaces, tabs, etc.) and then if a line does not terminate in a colon or semicolon, it returns a note and the line number. Optionally, it can add semicolons to any lines missing them and return the input with added semicolons. To check for lines that are too long, all trailing (but not before) white space is removed, and then the number of characters is checked.

Value

a character vector containing the input text and optionally added semicolons.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

See Also

mplusModeler

Examples

# sample input
test <- "
MODEL:
  mpg ON wt hp;
  wt WITH hp
"
# check and return
cat(parseMplus(test), file=stdout(), fill=TRUE)
# add missing semicolons and return
cat(parseMplus(test, TRUE), file=stdout(), fill=TRUE)
# line that is too long for Mplus
test <- "
MODEL:
  mpg cyl disp hp drat wt qsec vs am gear PWITH cyl disp hp drat wt qsec vs am gear carb;
"
cat(parseMplus(test), file=stdout())

Parses tags in the body section

Description

Parses tags in the body section (character vector) and init collection (list of vars defined in the init section). This is an internal function.

Usage

parseTags(bodySection, initCollection)

Arguments

Value

A list with three elements, where each list represents the location, start character, end character, tag type, etc. of each tag.

initTags

initMatches

bodyTags

bodyMatches

bodyText

bodySection

Plot coefficients for an mplusObject

Description

This is a method for plotting the coefficients of an mplusObject.

Usage

## S3 method for class 'mplusObject'
plot(x, y, type = c("stdyx", "un", "std", "stdy"), ...)

Arguments

Value

Nothing. Called for its side effect of plotting the coefficients.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

Examples

## Not run: 
# simple example of a model using builtin data
# demonstrates use
test <- mplusObject(
  TITLE = "test the MplusAutomation Package;",
  MODEL = "
    mpg ON wt hp;
    wt WITH hp;",
  OUTPUT = "STANDARDIZED;",
  usevariables = c("mpg", "wt", "hp"),
  rdata = mtcars)

res <- mplusModeler(test, "mtcars.dat", modelout = "model1.inp", run = 1L)

# example of the coef method
plot(res)

# remove files
unlink("mtcars.dat")
unlink("model1.inp")
unlink("model1.out")
unlink("Mplus Run Models.log")

## End(Not run)

Plot growth mixture models

Description

Plots latent and observed trajectories for a list of growth mixture models, specified using Mplus' '|' notation (e.g., i s | ).

Usage

plotGrowthMixtures(
  modelList,
  bw = FALSE,
  rawdata = FALSE,
  estimated = TRUE,
  poly = FALSE,
  alpha_range = c(0, 0.1),
  growth_variables = NULL,
  time_scale = NULL,
  jitter_lines = NULL,
  coefficients = "unstandardized"
)

Arguments

Value

An object of class 'ggplot'.

Author(s)

Caspar J. van Lissa

Examples

## Not run: 
mydat <- read.csv(
system.file("extdata", "ex8.2.csv", package = "MplusAutomation"))
res <- createMixtures(classes = 1:3, filename_stem = "ex8.2",
                      model_overall = 
                                    "i s | V1@0 V2@1 V3@2 V4@3;  i s on V5;",
                      rdata = mydat,
                      OUTPUT = "tech11 tech14;", 
                      usevariables = c("V1", "V2", "V3", "V4", "V5"),
                      run = 1L)
plotGrowthMixtures(res, estimated = TRUE, rawdata = TRUE, 
                   time_scale = c(0, 1, 2, 3))
plotGrowthMixtures(res, estimated = FALSE, rawdata = TRUE, poly = TRUE)

res <- createMixtures(classes = 1:3, filename_stem = "ex8.2_free",
                      model_overall = "i s | V1@0 V2* V3* V4@3;  i s on V5;",
                      rdata = mydat,
                      OUTPUT = "tech11 tech14;",
                      usevariables = c("V1", "V2", "V3", "V4", "V5"),
                      run = 1L)
plotMixtureDensities(res, variables = c("V1", "V2", "V3", "V4"))
plotGrowthMixtures(res, estimated = TRUE, rawdata = TRUE,
                   bw = TRUE, time_scale = c(0, 1, 2, 3),
                   alpha_range = c(0, .05))

plotGrowthMixtures(res, estimated = FALSE, rawdata = TRUE,
                   poly = TRUE, bw = TRUE, time_scale = c(0, 1, 2, 3))

## End(Not run)

Plot latent transition model

Description

Plots latent transition probabilities and classification probabilities for a single latent transition model (a model with multiple categorical latent variables, regressed on one another). Stroke thickness of nodes represents the proportion of cases most likely assigned to that class, with wider strokes representing greater probability. Edge thickness and transparency represent the probability of making a particular transition (left to right), with thicker/darker edges representing greater probability.

Usage

plotLTA(
  mplusModel,
  node_stroke = 2,
  max_edge_width = 2,
  node_labels = "variable.class",
  x_labels = "variable"
)

Arguments

Value

An object of class 'ggplot'.

Author(s)

Caspar J. van Lissa

Examples

## Not run: 
mydat <- read.csv(
system.file("extdata", "ex8.13.csv", package = "MplusAutomation"))
createMixtures(
classes = 2,
filename_stem = "dating",
model_overall = "c2 ON c1;",
model_class_specific = c(
"[u11$1] (a{C});  [u12$1] (b{C});  [u13$1] (c{C});  [u14$1] (d{C});  [u15$1] (e{C});",
"[u21$1] (a{C});  [u22$1] (b{C});  [u23$1] (c{C});  [u24$1] (d{C});  [u25$1] (e{C});"
),
rdata = mydat,
ANALYSIS = "PROCESSORS IS 2;  LRTSTARTS (0 0 40 20);  PARAMETERIZATION = PROBABILITY;",
VARIABLE = "CATEGORICAL = u11-u15 u21-u25;"
)
runModels(filefilter = "dating")
results <- readModels(filefilter = "dating")
plotLTA(results)

## End(Not run)

Create density plots for mixture models

Description

Creates a density plot for a single object of class 'mplus.model', or a faceted plot of density plots for an object of class 'mplus.model.list'. For each variable, a Total density plot will be shown, along with separate density plots for each latent class, where cases are weighted by the posterior probability of being assigned to that class.

Usage

plotMixtureDensities(
  modelList,
  variables = NULL,
  bw = FALSE,
  conditional = FALSE,
  alpha = 0.2,
  facet_labels = NULL
)

Arguments

Value

An object of class 'ggplot'.

Note

This function returns warnings, indicating that sum(weights) != 1. These can be ignored. The sum of the "Total" density per variable per model is equal to 1, and the sum of all of the posterior probabilities is equal to 1. This results in a normal density plot for the "Total", which is subdivided by the latent classes, in proportion to the posterior probabilities of participants being assigned to those clases.

Author(s)

Caspar J. van Lissa

Examples

## Not run: 
results <- createMixtures(classes = 1:3, filename_stem = "iris",
                          rdata = iris, run = 1L)
plotMixtureDensities(results)

## End(Not run)
## Not run: 
plotMixtureDensities(results, variables = "PETAL_LE")

## End(Not run)
## Not run: 
plotMixtureDensities(results, bw = TRUE)

## End(Not run)
## Not run: 
plotMixtureDensities(results, bw = FALSE, conditional = TRUE)

## End(Not run)
## Not run: 
plotMixtureDensities(results[[2]], variables = "PETAL_LE")

## End(Not run)

Create latent profile plots

Description

Creates a profile plot for a single object of class 'mplus.model', or a faceted plot of profile plots for an object of class 'mplus.model.list'.

Usage

plotMixtures(
  modelList,
  variables = NULL,
  coefficients = c("unstandardized", "stdyx.standardized", "stdy.standardized",
    "stdy.standardized"),
  parameter = c("Means", "Intercepts"),
  ci = 0.95,
  bw = FALSE,
  rawdata = FALSE,
  alpha_range = c(0, 0.1)
)

Arguments

Value

An object of class 'ggplot'.

Author(s)

Caspar J. van Lissa

Examples

## Not run: 
res <- createMixtures(classes = 1:2, filename_stem = "cars",
                      model_overall = "wt ON drat;",
                      model_class_specific = "wt;  qsec;",
                      rdata = mtcars,
                      usevariables = c("wt", "qsec", "drat"),
                      OUTPUT = "standardized",
                      run = 1L)
plotMixtures(res, rawdata = TRUE)

## End(Not run)
## Not run: 
plotMixtures(res, variables = "wt")

## End(Not run)
## Not run: 
plotMixtures(res, coefficients = "stdyx.standardized")

## End(Not run)

Create tab-delimited file and Mplus input syntax from R data.frame

Description

The prepareMplusData function converts an R data.frame (or a list of data frames), into a tab-delimited file (without header) to be used in an Mplus input file. The corresponding Mplus syntax, including the data file definition and variable names, is printed to the console or optionally to an input file.

Usage

prepareMplusData(
  df,
  filename = NULL,
  inpfile = FALSE,
  keepCols = NULL,
  dropCols = NULL,
  dummyCode = NULL,
  interactive = TRUE,
  overwrite = TRUE,
  imputed = FALSE,
  writeData = c("always", "ifmissing", "never"),
  hashfilename = FALSE,
  quiet = TRUE
)

Arguments

Details

The writeData argument is new and can be used to reduce overhead from repeatedly writing the same data from R to the disk. When using the ‘always’ option, prepareMplusData behaves as before, always writing data from R to the disk. When ‘ifmissing’, R generates an md5 hash of the data prior to writing it out to the disk. The md5 hash is based on: (1) the dimensions of the dataset, (2) the variable names, (3) the class of every variable, and (4) the raw data from the first and last rows. This combination ensures that under most all circumstances, if the data changes, the hash will change. The hash is appended to the specified data file name (which is controlled by the logical hashfilename argument). Next R checks in the directory where the data would normally be written. If a data file exists in that directory that matches the hash generated from the data, R will use that existing data file instead of writing out the data again. A final option is ‘never’. If this option is used, R will not write the data out even if no file matching the hash is found.

Value

Invisibly returns a character vector of the Mplus input syntax. Primarily called for its side effect of creating Mplus data files and optionally input files.

Author(s)

Michael Hallquist

Examples

## Not run: 
library(foreign)

study5 <- read.spss("reanalysis-study-5-mt-fall-08.sav", to.data.frame=TRUE)
ASData5 <- subset(study5, select=c("ppnum", paste("as", 1:33, sep="")))

prepareMplusData(ASData5, "study5.dat")


# basic example
test01 <- prepareMplusData(mtcars, "test01.dat")



# see that syntax was stored
test01

# example when there is a factor and logical
tmpd <- mtcars
tmpd$cyl <- factor(tmpd$cyl)
tmpd$am <- as.logical(tmpd$am)
prepareMplusData(tmpd, "test_type.dat")
rm(tmpd)

# by default, if re-run, data is re-written, with a note
test01b <- prepareMplusData(mtcars, "test01.dat")

# if we turn on hashing in the filename the first time,
# we can avoid overwriting notes the second time
test01c <- prepareMplusData(mtcars, "test01c.dat", hashfilename=TRUE)

# now that the filename was hashed in test01c, future calls do not re-write data
# as long as the hash matches
test01d <- prepareMplusData(mtcars, "test01c.dat",
  writeData = "ifmissing", hashfilename=TRUE)

# now that the filename was hashed in test01c, future calls do not re-write data
# as long as the hash matches
test01db <- prepareMplusData(mtcars, "test01d.dat",
  writeData = "ifmissing", hashfilename=TRUE)

# however, if the data change, then the file is re-written
test01e <- prepareMplusData(iris, "test01c.dat",
  writeData = "ifmissing", hashfilename=TRUE)

# tests for keeping and dropping variables
prepareMplusData(mtcars, "test02.dat", keepCols = c("mpg", "hp"))
prepareMplusData(mtcars, "test03.dat", keepCols = c(1, 2))
prepareMplusData(mtcars, "test04.dat",
  keepCols = c(TRUE, FALSE, FALSE, TRUE, FALSE,
  FALSE, FALSE, FALSE, FALSE, FALSE, FALSE))

prepareMplusData(mtcars, "test05.dat", dropCols = c("mpg", "hp"))
prepareMplusData(mtcars, "test06.dat", dropCols = c(1, 2))
prepareMplusData(mtcars, "test07.dat",
  dropCols = c(TRUE, FALSE, FALSE, TRUE, FALSE,
  FALSE, FALSE, FALSE, FALSE, FALSE, FALSE))


# interactive (test08.dat)
prepareMplusData(mtcars, interactive=TRUE)

# write syntax to input file, not stdout
prepareMplusData(mtcars, "test09.dat", inpfile=TRUE)

# write syntax to alternate input file, not stdout
prepareMplusData(mtcars, "test10.dat", inpfile="test10alt.inp")

# should be error, no file
prepareMplusData(mtcars, interactive=FALSE)

# new warnings if it is going to overwrite files
# (the default to be consistent with prior behavior)
prepareMplusData(mtcars, "test10.dat")

# new warnings if it is going to overwrite files
# (the default to be consistent with prior behavior)
prepareMplusData(mtcars, "test11.dat", inpfile="test10alt.inp")

# new errors if files exist and overwrite=FALSE
prepareMplusData(mtcars, "test10.dat",
  inpfile="test10alt.inp", overwrite=FALSE)


# can write multiply imputed data too
# here are three "imputed" datasets
idat <- list(
  data.frame(mpg = mtcars$mpg, hp = c(100, mtcars$hp[-1])),
  data.frame(mpg = mtcars$mpg, hp = c(110, mtcars$hp[-1])),
  data.frame(mpg = mtcars$mpg, hp = c(120, mtcars$hp[-1])))

# if we turn on hashing in the filename the first time,
# we can avoid overwriting notes the second time
testimp1 <- prepareMplusData(idat, "testi1.dat",
  writeData = "ifmissing", hashfilename=TRUE,
  imputed = TRUE)

# now that the filename was hashed, future calls do not re-write data
# as long as all the hashes match
testimp2 <- prepareMplusData(idat, "testi2.dat",
  writeData = "ifmissing", hashfilename=TRUE,
  imputed = TRUE)

# in fact, the number of imputations can decrease
# and they still will not be re-written
testimp3 <- prepareMplusData(idat[-3], "testi3.dat",
  writeData = "ifmissing", hashfilename=TRUE,
  imputed = TRUE)

# however, if the data changes, then all are re-written
# note that it warns for the two files that already exist
# as these two are overwritten

idat2 <- list(
  data.frame(mpg = mtcars$mpg, hp = c(100, mtcars$hp[-1])),
  data.frame(mpg = mtcars$mpg, hp = c(109, mtcars$hp[-1])),
  data.frame(mpg = mtcars$mpg, hp = c(120, mtcars$hp[-1])))
testimp4 <- prepareMplusData(idat2, "testi4.dat",
  writeData = "ifmissing", hashfilename=TRUE,
  imputed = TRUE)



## End(Not run)

Prepare Mplus Data Matrix

Description

support writing of covariance or means + covariance matrix (future)

Usage

prepareMplusData_Mat(covMatrix, meansMatrix, nobs)

Arguments

Value

A dataset

Print an Mplus Residual Structure object

Description

This is a method for printing an Mplus Residual Structure object.

Usage

## S3 method for class 'MplusRstructure'
print(x, ...)

Arguments

Value

NULL Called for its side effect of printing the object to the console

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

See Also

Other Mplus-Formatting: coef.mplus.model(), confint.mplus.model(), extract(), summary.mplusObject()

Examples

# default 'show' uses printing
mplusRcov(c("a", "b", "c"), type = "ar")

# also if calling print explicitly
print(mplusRcov(c("a", "b", "c"), type = "ar"))

# to see all aspects of the raw/original object
str(mplusRcov(c("a", "b", "c"), type = "ar"))

Process Conditional Tags

Description

To do: add details.

Usage

processConditionalTags(templateTags, initCollection)

Arguments

Value

Processed templateTags

Process the Init Section

Description

To do: add details.

Usage

processInit(initsection)

Arguments

Value

arglist

Read Parameters, Summary Statistics, and Savedata from Mplus Output

Description

Extracts information from one or more Mplus output files, including fit statistics and parameters. Its is to parse all (supported) aspects of Mplus output and to combine these into a list object, with one element per output file identified.

Usage

readModels(
  target = getwd(),
  recursive = FALSE,
  filefilter,
  what = "all",
  quiet = TRUE
)

Arguments

Details

The what parameter defaults to "all", which extracts all supported output. If you would like to extract a reduced set of output sections (especially to speed up the function when reading many files), specify the sections as a character vector from the following options:

c("input", "warn_err", "data_summary", "sampstat", "covariance_coverage", "summaries", "parameters", "class_counts", "indirect", "mod_indices", "residuals", "savedata", "bparameters", "tech1", "tech3", "tech4", "tech7", "tech8", "tech9", "tech10", "tech12", "fac_score_stats", "lcCondMeans", "gh5", "output")

Value

A list with one mplus.model per file. Each mplus.model object is composed of elements containing major output sections, as detailed below. If target is a single file, then the top-level elements will be a single mplus.model object, not a list of files. Specific elements are:

'

Author(s)

Michael Hallquist

Examples

## Not run: 
  allOutput <- readModels(
    "C:/Program Files/Mplus/Mplus Examples/User's Guide Examples", recursive=TRUE)

## End(Not run)

Recursive replace

Description

To do: fill in some details

Usage

recurseReplace(templateTags, initCollection, curiterator = 1L)

Arguments

Value

Does not look like it returns anything

Replace Body Tags

Description

To do: fill in some details

Usage

replaceBodyTags(bodySection, bodyTags, initCollection)

Arguments

Value

Returns updated bodySection

Replace Init Tags

Description

To do: fill in some details

Usage

replaceInitTags(initTags, initCollection)

Arguments

Value

Returns updated initCollection

Remove variable name length warnings from Mplus output file

Description

This function is designed to remove warnings in Mplus output files about variable names being greater than 8 characters. It replaces them with a note that the warnings were removed and a count of how many warnings were removed.

Usage

rmVarWarnings(file)

Arguments

Details

This is an internal function and not meant to be directly called by the user under most circumstances. It is called by mplusModeler when the varwarnings = FALSE argument is used.

Value

Usually NULL. Called for the side effect of removing warnings in Mplus output files. If file.access testing for write permissions returns FALSE, a character string note that rmVarWarnings could not run.

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

See Also

mplusModeler

Examples

# to do

Run Mplus Models

Description

This function runs a group of Mplus models (.inp files) located within a single directory or nested within subdirectories.

Usage

runModels(
  target = getwd(),
  recursive = FALSE,
  filefilter = NULL,
  showOutput = FALSE,
  replaceOutfile = "always",
  logFile = "Mplus Run Models.log",
  Mplus_command = detectMplus(),
  killOnFail = TRUE,
  local_tmpdir = FALSE,
  quiet = TRUE
)

Arguments

Value

None. Function is used for its side effects (running models).

Author(s)

Michael Hallquist

See Also

runModels_Interactive

Examples

## Not run: 
  runModels("C:/Users/Michael/Mplus Runs", recursive=TRUE, showOutput=TRUE,
    replaceOutfile="modifiedDate", logFile="MH_RunLog.txt",
    Mplus_command="C:\\Users\\Michael\\Mplus Install\\Mplus51.exe")

## End(Not run)
## Not run: 
  runModels(getwd(), filefilter = "ex8.*", logFile=NULL)

## End(Not run)

Run Mplus Models Using Graphical Interface

Description

This function is provides a graphical user interface to the runModels function. It uses Tcl/Tk to display a window in which the user can specify parameters for runModels, including the directory for runs, recursing through subdirectories, displaying output on the console, and replacing existing outfiles.

Usage

runModels_Interactive(
  directory = getwd(),
  recursive = "0",
  showOutput = "1",
  replaceOutfile = "1",
  checkDate = "0",
  logFile = "1"
)

Arguments

Details

This function exists as a GUI wrapper for runModels and does not provide any distinct functionality.

Value

None. Function is used to display user interface for running models.

Author(s)

Michael Hallquist

See Also

runModels

Examples

# interactive, none

Separate Hyphenated Variable Strings

Description

This code is a simplified form of expandCmd from the lavaan package. It separates hyphenated variable strings into a list of vectors, while ignoring hyphens that may be used in numbers.

Usage

separateHyphens(cmd)

Arguments

Details

Note that this is an internal function only.

Value

The character string if no hyphens, or a list of vectors if there are hyphens.

Author(s)

Michael Hallquist revised by Joshua Wiley

Examples

MplusAutomation:::separateHyphens("x1x4")
MplusAutomation:::separateHyphens("x1-x4")
MplusAutomation:::separateHyphens("x1-x4; x1*-1; v1-v3;")

Display summary table of Mplus model statistics in separate window

Description

Displays a summary table of model fit statistics extracted using the extractModelSummaries function. This function relies on the showData function from the relimp package, which displays data in a Tk-based window. By default, the following summary statistics are included: Title, LL, Parameters, AIC, AICC, BIC, RMSEA_Estimate, but these are customizable using the keepCols and dropCols parameters.

Usage

showSummaryTable(
  modelList,
  keepCols,
  dropCols,
  sortBy = NULL,
  font = "Courier 9"
)

Arguments

Value

No value is returned by this function. It is solely used to display the summary table in a separate window.

Note

You must choose between keepCols and dropCols because it is not sensible to use these together to include and exclude columns. The function will error if you include both parameters.

Author(s)

Michael Hallquist

See Also

extractModelSummaries HTMLSummaryTable LatexSummaryTable

Examples

# make me!!!

Split a data frame into a list by rows

Description

Takes a data frame and returns a list with an element for each row of the data frame. This is an internal function.

Usage

splitDFByRow(df)

Arguments

Value

A list where each element is a one row data frame

Examples

# small example using built in data
MplusAutomation:::splitDFByRow(mtcars)

Split File and Path into Separate Parts

Description

This is a helper function to split path into path and filename. Code adapted from R.utils filePath command.

Usage

splitFilePath(abspath, normalize = FALSE)

Arguments

Value

A list with elements for the directory, filename, and absolute path.

Examples

# make me!!!

Subset a list of Mplus model results

Description

a helper function to be used by wrappers that generate HTML, LaTex, and on-screen displays of summary statistics

Usage

subsetModelList(modelList, keepCols, dropCols, sortBy = NULL)

Arguments

Value

Extracted and sorted data

Examples

# make me!!!

Summarize an mplusObject

Description

This is a method for summarizing an mplusObject.

Usage

## S3 method for class 'mplusObject'
summary(object, verbose = FALSE, ...)

Arguments

Value

NULL Called for its side effect of printing a model summary to the console

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

See Also

Other Mplus-Formatting: coef.mplus.model(), confint.mplus.model(), extract(), print.MplusRstructure()

Examples

## Not run: 
# simple example of a model using builtin data
# demonstrates use
test <- mplusObject(
  TITLE = "test the MplusAutomation Package;",
  MODEL = "
    mpg ON wt hp;
    wt WITH hp;",
  usevariables = c("mpg", "wt", "hp"),
  rdata = mtcars)

 res <- mplusModeler(test, "mtcars.dat", modelout = "model1.inp", run = 1L)

# example of the summary method
summary(res)

# example of verbose output
summary(res, verbose=TRUE)

# remove files
unlink("mtcars.dat")
unlink("model1.inp")
unlink("model1.out")
unlink("Mplus Run Models.log")

## End(Not run)

Test inequality-constrained hypothesis for two or more parameters based on iterations of MCMC chains

Description

Tests an inequality-constrained hypothesis (van de Schoot, Hoijtink, Hallquist, & Boelen, in press) based on draws from the posterior distribution of the model parameters, which provides information about the proportion of the distribution that is in agreement with a given hypothesis. This function is used for more complex hypotheses about three or more parameters, whereas testBParamConstraint tests a simple two-parameter hypothesis.

Usage

testBParamCompoundConstraint(bparams, test)

Arguments

Details

This function accepts a bparameters object containing iterations of the MCMC chains (rows) for each model parameter (columns) and prints out the number and proportion of draws that are consistent with the requested hypothesis test.

The test argument is evaluated directly as R code, with the bparams object attached so that variable names are available directly in the environment. Because the goal is to evaluate the test for each draw from the posterior distribution, remember to use vector-based logic operators, not boolean operators. That is, stick to & or | for joining tests of parameters, rather than && or || since the latter will return a single TRUE/FALSE, which is irrelevant.

An example test in R logic would be "(STAITOT.ON.CG > STAITOT.ON.UCG) & (BDIM.ON.CG > BDIM.ON.UCG)".

Value

No value is returned by this function. Instead, two summary tables are printed to the screen containing the number and proportion of draws consistent with the hypothesis.

Author(s)

Michael Hallquist

See Also

testBParamConstraint

Examples

## Not run: 
  #using bparameters directly
  btest <- getSavedata_Bparams("model vb1_simpel_b.out")
  testBParametersCompoundConstraint(btest,
  "(STDYX_STAITOT.ON.CG > STDYX_STAITOT.ON.UCG) & (STDYX_BDIM.ON.CG > STDYX_BDIM.ON.UCG)")

  #or using readModels
  btest <- readModels("model vb1_simpel_b.out")
  testBParametersCompoundConstraint(btest,
  "(STDYX_STAITOT.ON.CG > STDYX_STAITOT.ON.UCG) & (STDYX_BDIM.ON.CG > STDYX_BDIM.ON.UCG)")

## End(Not run)

Test inequality-constrained hypothesis for two parameters based on iterations of MCMC chains

Description

Tests a simple inequality-constrained hypothesis (van de Schoot, Hoijtink, Hallquist, & Boelen, in press) based on draws from the posterior distribution of the model parameters, which provides information about the proportion of the distribution that is in agreement with a given hypothesis. This function is used for simple hypothesis for two parameters, whereas testBParamCompoundConstraint gives full access to multiple parameters and R's logic syntax. This function accepts a bparameters object containing iterations of the MCMC chains (rows) for each model parameter (columns) and prints out the number and proportion of draws that are consistent with the requested hypothesis test. The coef1, operator, and coef2 arguments are appended in sequence, so that the hypothesis test is constructed from left-to-right. e.g., testBParamConstraint(bparamsDF, "MGM.TRT1", ">", "MGM.EX2").

Usage

testBParamConstraint(bparams, coef1, operator, coef2)

Arguments

Value

No value is returned by this function. Instead, two summary tables are printed to the screen containing the number and proportion of draws consistent with the hypothesis.

Author(s)

Michael Hallquist

See Also

testBParamCompoundConstraint

Examples

## Not run: 
  #using bparameters directly
  btest <- getSavedata_Bparams("model vb1_simpel_b.out"))
  testBParametersConstraint(btest, "STDYX_STAITOT.ON.CG", ">", "STDYX_STAITOT.ON.UCG")

  #or using readModels
  btest <- readModels("model vb1_simpel_b.out"))
  testBParametersConstraint(btest, "STDYX_STAITOT.ON.CG", ">", "STDYX_STAITOT.ON.UCG")

## End(Not run)

Train a variety of latent growth mixture model

Description

This function iterates through a grid of values to train LGMMs, optionally using a local or remote cluster.

Usage

trainLGMM(
  data,
  idvar,
  assessmentvar,
  newdata = FALSE,
  tuneGrid,
  cl,
  ncores = 1L
)

Arguments

Examples

## Not run: 
## This example is not run by default because even with very limitted number of
## random starts and iterations, it takes quite a few minutes
setwd(tempdir())

## Simulate Some Data from 3 classes
library(MASS)
set.seed(1234)
allcoef <- rbind(
  cbind(1, mvrnorm(n = 200,
                   mu = c(0, 2, 0),
                   Sigma = diag(c(.2, .1, .01)),
                   empirical = TRUE)),
  cbind(2, mvrnorm(n = 200,
                   mu = c(-3.35, 2, 2),
                   Sigma = diag(c(.2, .1, .1)),
                   empirical = TRUE)),
  cbind(3, mvrnorm(n = 200,
                   mu = c(3.35, 2, -2),
                   Sigma = diag(c(.2, .1, .1)),
                   empirical = TRUE)))
allcoef <- as.data.frame(allcoef)
names(allcoef) <- c("Class", "I", "L", "Q")
allcoef$ID <- 1:nrow(allcoef)
d <- do.call(rbind, lapply(1:nrow(allcoef), function(i) {
  out <- data.frame(
    ID = allcoef$ID[i],
    Class = allcoef$Class[i],
    Assess = 1:11,
    x = sort(runif(n = 11, min = -2, max = 2)))
  out$y <- rnorm(11,
    mean = allcoef$I[i] + allcoef$L[i] * out$x + allcoef$Q[i] * out$x^2,
    sd = .1)
  return(out)
}))

## create splines
library(splines)
time_splines <- ns(d$x, df = 3, Boundary.knots = quantile(d$x, probs = c(.02, .98)))
d$t1 <- time_splines[, 1]
d$t2 <- time_splines[, 2]
d$t3 <- time_splines[, 3]
d$xq <- d$x^2

## create new data to be used for predictions
nd <- data.frame(ID = 1,
                 x = seq(from = -2, to = 2, by = .1))
nd.splines <- with(attributes(time_splines),
                   ns(nd$x, df = degree, knots = knots,
                      Boundary.knots = Boundary.knots))
nd$t1 <- nd.splines[, 1]
nd$t2 <- nd.splines[, 2]
nd$t3 <- nd.splines[, 3]
nd$xq <- nd$x^2

## create a tuning grid of models to try
## all possible combinations are created of different time trends
## different covariance structures of the random effects
## and different number of classes
tuneGrid <- expand.grid(
  dv = "y",
  timevars = list(c("t1", "t2", "t3"), "x", c("x", "xq")),
  starts = "2 1",
  cov = c("independent", "zero"),
  k = c(1L, 3L),
  processors = 1L, run = TRUE,
  misstrick = TRUE, stringsAsFactors = FALSE)
tuneGrid$title <- paste0(
  c("linear", "quad", "spline")[sapply(tuneGrid$timevars, length)],
  "_",
  sapply(tuneGrid$cov, function(x) if(nchar(x)==4) substr(x, 1, 4) else substr(x, 1, 3)),
  "_",
  tuneGrid$k)
tuneGrid$base <- paste0(
  c("linear", "quad", "spline")[sapply(tuneGrid$timevars, length)],
  "_",
  sapply(tuneGrid$cov, function(x) if(nchar(x)==4) substr(x, 1, 4) else substr(x, 1, 3)))

## example using long2LGMM to fit one model at a time
mres <- long2LGMM(
        data = d,
        idvar = "ID",
        assessmentvar = "Assess",
        dv = tuneGrid$dv[1],
        timevars = tuneGrid$timevars[[1]],
        misstrick = tuneGrid$misstrick[1],
        k = tuneGrid$k[1],
        title = paste0(tuneGrid$title[1], tuneGrid$k[1]),
        base = tuneGrid$base[1],
        run = tuneGrid$run[1],
        processors = tuneGrid$processors[1],
        starts = tuneGrid$starts[1],
        newdata = nd,
        cov = tuneGrid$cov[1])

## Example using trainLGMM to fit a whole set of models
## can be distributed across a local or remote cluster
## Defaults to creating a local cluster, but can also pass an
## existing cluster
AllRes <- trainLGMM(
  data = d,
  idvar = "ID",
  assessmentvar = "Assess",
  newdata = nd,
  tuneGrid = tuneGrid,
  ncores = 2L)


tuneGridRes <- as.data.frame(
  cbind(tuneGrid,
        do.call(rbind, lapply(AllRes, function(x) {
          if (is.null(x$Model$results$summaries)) {
            NA
          } else {
            out <- x$Model$results$summaries
            ## deal with missing summary information for k = 1
            if (is.null(out$Entropy)) {
              out$Entropy <- 1
            }
            if (is.null(out$NCategoricalLatentVars)) {
              out$NCategoricalLatentVars <- 0
            }
            out[, sort(names(out)), drop = FALSE]
          }
        }))))

tuneGridRes$Type <- gsub("([a-z]+)_.*$", "\\1", tuneGridRes$title)

tuneGridRes$MinClass <- sapply(AllRes, function(x) {
  n <- x$Model$results$class_counts$mostLikely$count
  if(is.null(n)) {
    length(unique(d$ID))
  } else {
    min(n, na.rm = TRUE)
  }
})

## when trying many models, some may not converge
## subset to omit any missing AICC and look only at those with some
## minimum number of participants per class,
## for demonstration only arbitrarily set at 30
subset(tuneGridRes, !is.na(AICC) & MinClass >= 30,
       select = c(title, aBIC, AICC, Entropy, MinClass, LL))

## reshape data into long form which can make a very nice plot using ggplot2
tuneGridResL <- reshape(
  subset(tuneGridRes, select = c(Type, cov, k, Parameters, aBIC, AICC, AIC, BIC, Entropy)),
  varying = c("Parameters", "aBIC", "AICC", "AIC", "BIC", "Entropy"),
  v.names = "value",
  times = c("Parameters", "aBIC", "AICC", "AIC", "BIC", "Entropy"),
  timevar = "variable",
  idvar = c("Type", "cov", "k"),
  direction = "long")
tuneGridResL$cov <- factor(tuneGridResL$cov, levels = c("zero", "independent"))

## uncomment to run
## library(ggplot2)
## ggplot(tuneGridResL, aes(k, value, colour = Type, shape = Type)) +
##   geom_point() +
##   facet_grid(variable~cov, scales = "free")


## nice plot of the average trajectories in each class
## these are possible as trainLGMM exports predicted values for the
## new data fed in
## uncomment to run
## ggplot(AllRes[[which(tuneGridRes$title=="quad_ind_3")]]$predictions, aes(x)) +
##   geom_line(aes(y = y_1), colour = "black", size = 2) +
##   geom_line(aes(y = y_2), colour = "red", size = 2) +
##   geom_line(aes(y = y_3), colour = "blue", size = 2)

## End(Not run)

Trim White Space

Description

Helper function to remove white space from a character vector

Usage

trimSpace(string)

Arguments

Value

A character vector with the white space removed.

Examples

MplusAutomation:::trimSpace(c("    test", "another    "))

Reconstruct matrix from unlabeled multi-line text output

Description

worker function for extracting Mplus matrix output from an unlabeled section where matrices are spread across blocks to keep within width constraints example: class counts output from latent class models.

Usage

unlabeledMatrixExtract(outfiletext, filename)

Arguments

Value

a matrix

Examples

# make me!!!

Update an Mplus model object

Description

This is a method for updating an Mplus model object. It takes an Mplus model object as the first argument, and then optionally any sections to update. There are two ways to update a section using a formula interface. ~ "new stuff" will replace a given section with the new text. Alternately, you can add additional text using ~ + "additional stuff". Combined these let you replace or add to a section.

Usage

## S3 method for class 'mplusObject'
update(object, quiet = TRUE, ...)

Arguments

Value

An (updated) Mplus model object

Author(s)

Joshua F. Wiley <jwiley.psych@gmail.com>

Examples

example1 <- mplusObject(MODEL = "mpg ON wt;",
  usevariables = c("mpg", "hp"), rdata = mtcars)
x <- ~ "ESTIMATOR = ML;"
str(update(example1, rdata = iris))
str(update(example1, ANALYSIS = x))
str(update(example1, MODEL = ~ "wt ON hp;"))
str(update(example1, MODEL = ~ . + "wt ON hp;"))
str(update(example1, ANALYSIS = x, MODEL = ~ . + "wt ON hp;"))

## check that use variables can be updated & overridden
str(update(example1, usevariables = c("mpg", "hp", "cyl")))

# test to make sure . in Mplus code does not cause problems
str(update(example1, ANALYSIS = x, MODEL = ~ . + "wt ON hp*.5;"))
rm(example1, x)

Updates current values

Description

Body tags currentValues are substituted at the bottom-most level after init collection is finalized (recursively process any nested tags)

Usage

updateCurrentValues(templateTags, initCollection)

Arguments

Value

Updated current value or the original if no match.