diff --git a/DESCRIPTION b/DESCRIPTION index 6b12f92..8da00b0 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,7 +2,7 @@ Package: MplusAutomation Type: Package Title: An R Package for Facilitating Large-Scale Latent Variable Analyses in Mplus Version: 1.2 -Date: 2025-08-22 +Date: 2025-08-25 Authors@R: c(person("Michael", "Hallquist", role = c("aut", "cre"), email = "michael.hallquist@gmail.com"), person("Joshua", "Wiley", role = "aut", @@ -51,6 +51,7 @@ Suggests: LazyLoad: yes LazyData: yes VignetteBuilder: knitr +Roxygen: list(markdown = TRUE) RoxygenNote: 7.3.2 Encoding: UTF-8 Config/testthat/edition: 3 diff --git a/NEWS b/NEWS index b9a056d..c1bd3b3 100644 --- a/NEWS +++ b/NEWS @@ -1,4 +1,4 @@ -Version 1.2 (DEVELOPMENT) +Version 1.2 - notice: MplusAutomation examples vignette updated to refer to readModels, not outmoded extract* functions - feature: New pathfilter argument to readModels allows for selection of outputs to read based both on path name (pathfilter) and file name (filefilter) - feature: compareModels now returns a list of comparison results including chi-square difference tests when requested diff --git a/R/MplusAutomation.R b/R/MplusAutomation.R index c14c97f..df53d80 100644 --- a/R/MplusAutomation.R +++ b/R/MplusAutomation.R @@ -10,12 +10,10 @@ #' and tabulating model parameters and fit statistics. #' #' @details The MplusAutomation package has four primary purposes: -#' \enumerate{ -#' \item To automatically run groups/batches of models. -#' \item To provide routines to extract model fit statistics, parameter estimates, and raw data from 'Mplus' output files. -#' \item To facilitate comparisons among models -#' \item To provide a template language that allows for the creation of related input files. -#' } +#' * To automatically run groups/batches of models. +#' * To provide routines to extract model fit statistics, parameter estimates, and raw data from 'Mplus' output files. +#' * To facilitate comparisons among models +#' * To provide a template language that allows for the creation of related input files. #' The core routine for running batches of models is \code{\link{runModels}}, with #' an easy-to-use GUI wrapper, \code{\link{runModels_Interactive}}. #' diff --git a/R/compareModels.R b/R/compareModels.R index b1bab50..d1ec180 100644 --- a/R/compareModels.R +++ b/R/compareModels.R @@ -8,42 +8,37 @@ #' #' Model outputs to be compared should come from the \code{readModels} command. #' -#' The \code{show} parameter can be one or more of the following, which can be passed as a vector, such as c("equal", "pdiff"). +#' The \code{show} parameter can be one or more of the following, which can be +#' passed as a vector, such as c("equal", "pdiff"). #' -#' \describe{ -#' \item{show}{ -#' \describe{ -#' \item{"all"}{Display all available model comparison. Equivalent to -#' c("summaries", "equal", "diff", "pdiff", "unique").} -#' \item{"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")} -#' \item{"allsummaries"}{Prints a comparison of all summary statistics available in each model. May -#' generate a lot of output.} -#' \item{"equal"}{Print parameter estimates that are equal between models -#' (i.e., \code{<= equalityMargin["param"]})}. -#' \item{"diff"}{Print parameter estimates that are different between models -#' (i.e., \code{> equalityMargin["param"]})}. -#' \item{"pdiff"}{Print parameter estimates where the p-values differ between models -#' (i.e., \code{> equalityMargin["pvalue"]})}. -#' \item{"unique"}{Print parameter estimates that are unique to each model.} -#' } -#' } -#' } +#' * `"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"`: Print 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 \code{sort} parameter determines the order in which parameter estimates are displayed. The following options are available: +#' The \code{sort} parameter determines the order in which parameter estimates +#' are displayed. The following options are available: #' -#' \describe{ -#' \item{sort}{ -#' \describe{ -#' \item{"none"}{No sorting is performed, so parameters are output in the order presented in Mplus. (Default)} -#' \item{"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.} -#' \item{"alphabetical"}{Sort parameters in alphabetical order.} -#' \item{"maxDiff"}{Sort parameter output by the largest differences between models (high to low).} -#' } -#' } -#' } +#' * `"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). #' #' @param m1 The first Mplus model to be compared. Generated by \code{readModels}. #' @param m2 The second Mplus model to be compared. diff --git a/R/createModels.R b/R/createModels.R index c10789c..f69b95d 100644 --- a/R/createModels.R +++ b/R/createModels.R @@ -147,11 +147,9 @@ getInitTags <- function(initCollection) { #' @param initCollection The initial collection #' @return A list with three elements, where each list represents the location, #' start character, end character, tag type, etc. of each tag. -#' \describe{ -#' \item{initTags}{initMatches} -#' \item{bodyTags}{bodyMatches} -#' \item{bodyText}{bodySection} -#' } +#' * `initTags`: initMatches +#' * `bodyTags`: bodyMatches +#' * `bodyText`: bodySection #' @keywords internal parseTags <- function(bodySection, initCollection) { #first handle init tags diff --git a/R/data.R b/R/data.R index 42f0394..9bb2f44 100644 --- a/R/data.R +++ b/R/data.R @@ -1,22 +1,20 @@ -#' Latent Class Analysis Demonstration -#' -#' 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. -#' -#' @format A list containing 11 elements. -#' \describe{ -#' \item{Data}{2 Class LCA data simulated using Mplus} -#' \item{CFA}{Mplus output file for CFA} -#' \item{LCA2}{Mplus output file for 2 class LCA} -#' \item{LCA3}{Mplus output file for 3 class LCA} -#' \item{LCA4}{Mplus output file for 4 class LCA} -#' \item{LCA5}{Mplus output file for 5 class LCA} -#' \item{CFAGH5}{GH5 file for CFA} -#' \item{LCA2GH5}{GH5 file for 2 class LCA} -#' \item{LCA3GH5}{GH5 file for 3 class LCA} -#' \item{LCA4GH5}{GH5 file for 4 class LCA} -#' \item{LCA5GH5}{GH5 file for 5 class LCA} -#' } -"lcademo" - +#' Latent Class Analysis Demonstration +#' +#' 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. +#' +#' @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 +"lcademo" + diff --git a/R/extractModIndices.R b/R/extractModIndices.R index ece16cb..f28875b 100644 --- a/R/extractModIndices.R +++ b/R/extractModIndices.R @@ -150,15 +150,14 @@ extractModIndices_1file <- function(outfiletext, filename) { #' for a single file, and the top-level elements are named after the #' corresponding output file name. The basic \code{data.frame} containing #' the MODEL MODIFICATION INDICES section of \code{outfile}. Variables include -#' \item{modV1}{The first variable in the pair to be freed according to the M.I.} -#' \item{operator}{The suggested relationship between \code{modV1} and \code{modV2} +#' * `modV1`: The first variable in the pair to be freed according to the M.I. +#' * `operator`: The suggested relationship between \code{modV1} and \code{modV2 #' (e.g., WITH for freeing the covariance between \code{modV1} and \code{modV2})} -#' \item{modV2}{The first variable in the pair to be freed according to the M.I.} -#' \item{MI}{The decrease in model chi-square if the specified relationship is freely estimated} -#' \item{EPC}{The expected parameter estimate between \code{modV1} and \code{modV2} if freed.} -#' \item{Std_EPC}{The EPC value standardized using the variances of the continuous latent variables.} -#' \item{StdYX_EPC}{The EPC value standardized using the variances of the continuous latent -#' variables as well as the variances of the background and/or outcome variables.} +#' * `modV2`: The first variable in the pair to be freed according to the M.I. +#' * `MI`: The decrease in model chi-square if the specified relationship is freely estimated +#' * `EPC`: The expected parameter estimate between \code{modV1} and \code{modV2} if freed. +#' * `Std_EPC`: The EPC value standardized using the variances of the continuous latent variables. +#' * `StdYX_EPC`: The EPC value standardized using the variances of the continuous latent variables as well as the variances of the background and/or outcome variables. #' @author Michael Hallquist #' @seealso \code{\link{readModels}}, \code{\link{extractModelSummaries}}, \code{\link{extractModelParameters}} #' @keywords internal diff --git a/R/extractParameters.R b/R/extractParameters.R index 061f019..f043d3f 100644 --- a/R/extractParameters.R +++ b/R/extractParameters.R @@ -741,40 +741,40 @@ extractParameters_1file <- function(outfiletext, filename, resultType, efa = FAL #' #' The core \code{data.frame} for each MODEL RESULTS section typically has the following structure: #' -#' \item{paramHeader}{The header that begins a given parameter set. Example: "FACTOR1 BY"} -#' \item{param}{The particular parameter being measured (within \code{paramHeader}). Example: "ITEM1"} -#' \item{est}{Parameter estimate value.} -#' \item{se}{Standard error of the estimate} -#' \item{est_se}{Quotient of \code{est/se}, representing z-test/t-test in large samples} -#' \item{pval}{Two-tailed p-value for the \code{est_se} quotient.} +#' * `paramHeader`: The header that begins a given parameter set. Example: "FACTOR1 BY" +#' * `param`: The particular parameter being measured (within \code{paramHeader}). Example: "ITEM1" +#' * `est`: Parameter estimate value. +#' * `se`: Standard error of the estimate +#' * `est_se`: Quotient of \code{est/se}, representing z-test/t-test in large samples +#' * `pval`: Two-tailed p-value for the \code{est_se} quotient. #' #' In the case of output from Bayesian estimation (ESTIMATOR=BAYES), the \code{data.frame} will contain #' a different set of variables, including some of the above, as well as -#' \item{posterior_sd}{Posterior standard deviation of the estimate.} -#' \item{lower_2.5ci}{Lower 2.5 percentile of the estimate.} -#' \item{upper_2.5ci}{Upper 2.5 percentile (aka 97.5 percentile) of the estimate.} +#' * `posterior_sd`: Posterior standard deviation of the estimate. +#' * `lower_2.5ci`: Lower 2.5 percentile of the estimate. +#' * `upper_2.5ci`: Upper 2.5 percentile (aka 97.5 percentile) of the estimate. #' #' Also note that the \code{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 \code{data.frame} will contain #' a different set of variables, including some of the above, as well as -#' \item{population}{Population parameter value.} -#' \item{average}{Average parameter estimate across replications.} -#' \item{population_sd}{Standard deviation of parameter value in population across replications.} -#' \item{average_se}{Average standard error of estimated parameter value across replications.} -#' \item{mse}{Mean squared error.} -#' \item{cover_95}{Proportion of replications whose 95\% confidence interval for the parameter includes the population value.} -#' \item{pct_sig_coef}{Proportion of replications for which the two-tailed significance test of the parameter is significant (p < .05).} +#' * `population`: Population parameter value. +#' * `average`: Average parameter estimate across replications. +#' * `population_sd`: Standard deviation of parameter value in population across replications. +#' * `average_se`: Average standard error of estimated parameter value across replications. +#' * `mse`: Mean squared error. +#' * `cover_95`: Proportion of replications whose 95\% confidence interval for the parameter includes the population value. +#' * `pct_sig_coef`: Proportion of replications for which the two-tailed significance test of the parameter is significant (p < .05). #' #' In the case of confidence interval output (OUTPUT:CINTERVAL), the list element \code{ci.unstandardized} will contain #' a different set of variables, including some of the above, as well as -#' \item{low.5}{Lower 0.5\% CI estimate.} -#' \item{low2.5}{Lower 2.5\% CI estimate.} -#' \item{low5}{Lower 5\% CI estimate.} -#' \item{est}{Parameter estimate value.} -#' \item{up5}{Upper 5\% (i.e., 95\%) CI estimate.} -#' \item{up2.5}{Upper 2.5\% (i.e., 97.5\%) CI estimate.} -#' \item{up.5}{Upper 0.5\% (i.e., 99.5\%) CI estimate.} +#' * `low.5`: Lower 0.5\% CI estimate. +#' * `low2.5`: Lower 2.5\% CI estimate. +#' * `low5`: Lower 5\% CI estimate. +#' * `est`: Parameter estimate value. +#' * `up5`: Upper 5\% (i.e., 95\%) CI estimate. +#' * `up2.5`: Upper 2.5\% (i.e., 97.5\%) CI estimate. +#' * `up.5`: Upper 0.5\% (i.e., 99.5\%) CI estimate. #' #' If the model contains multiple latent classes, an additional variable, \code{LatentClass}, #' will be included, specifying the latent class number. Also, the Categorical Latent Variables section @@ -803,4 +803,4 @@ extractModelParameters <- function(target=getwd(), recursive=FALSE, filefilter, #extractParameters_1section: extract model parameters for a given section. #extractParameters_1chunk: extract model parameters for a given chunk (e.g., Latent class 2, Between Level) within a given section. -} \ No newline at end of file +} diff --git a/R/extractSaveData.R b/R/extractSaveData.R index 428f149..be16289 100644 --- a/R/extractSaveData.R +++ b/R/extractSaveData.R @@ -9,15 +9,14 @@ #' If \code{outfile} is a relative path or just the filename, then it is assumed that the file resides in #' the working directory \code{getwd()}. #' @return Returns a list of SAVEDATA file information that includes: -#' \item{fileName}{The name of the file containing the analysis dataset created by the Mplus SAVEDATA command.} -#' \item{fileVarNames}{A character vector containing the names of variables in the dataset.} -#' \item{fileVarFormats}{A character vector containing the Fortran-style formats of variables in the dataset.} -#' \item{fileVarWidths}{A numeric vector containing the widths of variables in the dataset (which is stored in fixed-width format).} -#' \item{bayesFile}{The name of the BPARAMETERS file containing draws from the posterior distribution created by -#' the Mplus SAVEDATA BPARAMETERS command.} -#' \item{bayesVarNames}{A character vector containing the names of variables in the BPARAMETERS dataset.} -#' \item{tech3File}{A character vector of the tech 3 output.} -#' \item{tech4File}{A character vector of the tech 4 output.} +#' * `fileName`: The name of the file containing the analysis dataset created by the Mplus SAVEDATA command. +#' * `fileVarNames`: A character vector containing the names of variables in the dataset. +#' * `fileVarFormats`: A character vector containing the Fortran-style formats of variables in the dataset. +#' * `fileVarWidths`: A numeric vector containing the widths of variables in the dataset (which is stored in fixed-width format). +#' * `bayesFile`: The name of the BPARAMETERS file containing draws from the posterior distribution created by the Mplus SAVEDATA BPARAMETERS command. +#' * `bayesVarNames`: A character vector containing the names of variables in the BPARAMETERS dataset. +#' * `tech3File`: A character vector of the tech 3 output. +#' * `tech4File`: A character vector of the tech 4 output. #' @author Michael Hallquist #' @seealso \code{\link{getSavedata_Data}} #' @examples @@ -55,15 +54,14 @@ getSavedata_Fileinfo <- function(outfile) { #' output file. #' @param outfiletext The contents of the output file, for example as read by \code{scan} #' @return A list that includes: -#' \item{fileName}{The name of the file containing the analysis dataset created by the Mplus SAVEDATA command.} -#' \item{fileVarNames}{A character vector containing the names of variables in the dataset.} -#' \item{fileVarFormats}{A character vector containing the Fortran-style formats of variables in the dataset.} -#' \item{fileVarWidths}{A numeric vector containing the widths of variables in the dataset (which is stored in fixed-width format).} -#' \item{bayesFile}{The name of the BPARAMETERS file containing draws from the posterior distribution created by -#' the Mplus SAVEDATA BPARAMETERS command.} -#' \item{bayesVarNames}{A character vector containing the names of variables in the BPARAMETERS dataset.} -#' \item{tech3File}{A character vector of the tech 3 output.} -#' \item{tech4File}{A character vector of the tech 4 output.} +#' * `fileName`: The name of the file containing the analysis dataset created by the Mplus SAVEDATA command. +#' * `fileVarNames`: A character vector containing the names of variables in the dataset. +#' * `fileVarFormats`: A character vector containing the Fortran-style formats of variables in the dataset. +#' * `fileVarWidths`: A numeric vector containing the widths of variables in the dataset (which is stored in fixed-width format). +#' * `bayesFile`: The name of the BPARAMETERS file containing draws from the posterior distribution created by the Mplus SAVEDATA BPARAMETERS command. +#' * `bayesVarNames`: A character vector containing the names of variables in the BPARAMETERS dataset. +#' * `tech3File`: A character vector of the tech 3 output. +#' * `tech4File`: A character vector of the tech 4 output. #' @importFrom gsubfn strapply #' @seealso \code{\link{getSavedata_Data}} #' @examples diff --git a/R/mplus.R b/R/mplus.R index 530fbc8..3dd7b72 100644 --- a/R/mplus.R +++ b/R/mplus.R @@ -153,27 +153,27 @@ detectVariables <- function(object, quiet = TRUE) { #' @param ... Arguments passed on to \code{\link{mplusModeler}} if #' \code{run > 0}. #' @return A list of class \code{mplusObject} with elements -#' \item{TITLE}{The title in Mplus (if defined)} -#' \item{DATA}{The data section in Mplus (if defined)} -#' \item{VARIABLE}{The variable section in Mplus (if defined)} -#' \item{DEFINE}{The define section in Mplus (if defined)} -#' \item{MONTECARLO}{The montecarlo section in Mplus (if defined)} -#' \item{MODELPOPULATION}{The modelpopulation section in Mplus (if defined)} -#' \item{MODELMISSING}{The modelmissing section in Mplus (if defined)} -#' \item{ANALYSIS}{The analysis section in Mplus (if defined)} -#' \item{MODEL}{The model section in Mplus (if defined)} -#' \item{MODELINDIRECT}{The modelindirect section in Mplus (if defined)} -#' \item{MODELCONSTRAINT}{The modelconstraint section in Mplus (if defined)} -#' \item{MODELTEST}{The modeltest section in Mplus (if defined)} -#' \item{MODELPRIORS}{The modelpriors section in Mplus (if defined)} -#' \item{OUTPUT}{The output section in Mplus (if defined)} -#' \item{SAVEDATA}{The savedata section in Mplus (if defined)} -#' \item{PLOT}{The plot section in Mplus (if defined)} -#' \item{results}{NULL by default, but can be later updated to include the results from the model run.} -#' \item{usevariables}{A character vector of the variables from the \code{R} data set to be used.} -#' \item{rdata}{The \code{R} data set to use for the model.} -#' \item{imputed}{A logical whether the data are multiply imputed.} -#' \item{autov}{A logical whether the data should have the usevariables detected automatically or not} +#' * `TITLE`: The title in Mplus (if defined) +#' * `DATA`: The data section in Mplus (if defined) +#' * `VARIABLE`: The variable section in Mplus (if defined) +#' * `DEFINE`: The define section in Mplus (if defined) +#' * `MONTECARLO`: The montecarlo section in Mplus (if defined) +#' * `MODELPOPULATION`: The modelpopulation section in Mplus (if defined) +#' * `MODELMISSING`: The modelmissing section in Mplus (if defined) +#' * `ANALYSIS`: The analysis section in Mplus (if defined) +#' * `MODEL`: The model section in Mplus (if defined) +#' * `MODELINDIRECT`: The modelindirect section in Mplus (if defined) +#' * `MODELCONSTRAINT`: The modelconstraint section in Mplus (if defined) +#' * `MODELTEST`: The modeltest section in Mplus (if defined) +#' * `MODELPRIORS`: The modelpriors section in Mplus (if defined) +#' * `OUTPUT`: The output section in Mplus (if defined) +#' * `SAVEDATA`: The savedata section in Mplus (if defined) +#' * `PLOT`: The plot section in Mplus (if defined) +#' * `results`: NULL by default, but can be later updated to include the results from the model run. +#' * `usevariables`: A character vector of the variables from the \code{R} data set to be used. +#' * `rdata`: The \code{R} data set to use for the model. +#' * `imputed`: A logical whether the data are multiply imputed. +#' * `autov`: A logical whether the data should have the usevariables detected automatically or not #' #' @author Joshua F. Wiley #' @export @@ -1020,12 +1020,10 @@ mplusModeler <- function(object, dataout, modelout, run = 0L, #' at the time of writing, Mplus does not allow more than 80 characters per row. #' Defaults to \code{FALSE}. #' @return A named character vector of class \sQuote{MplusRstructure} with four elements: -#' \item{all}{A character string collapsing all other sections.} -#' \item{Variances}{A character string containing all of the variances.} -#' \item{Covariances}{A character string containing all of the -#' covariances, properly labelled to allow constraints and the -#' autoregressive residual covariance structure.} -#' \item{Constraints}{A character string containing the \sQuote{MODEL CONSTRAINT} +#' * `all`: A character string collapsing all other sections. +#' * `Variances`: A character string containing all of the variances. +#' * `Covariances`: A character string containing all of the covariances, properly labelled to allow constraints and the autoregressive residual covariance structure. +#' * `Constraints`: A character string containing the \sQuote{MODEL CONSTRAINT #' section and code needed to parameterize the residual covariance structure #' as autoregressive.} #' @keywords interface diff --git a/R/mplusModel.R b/R/mplusModel.R index 35c953b..4888832 100644 --- a/R/mplusModel.R +++ b/R/mplusModel.R @@ -1,3 +1,14 @@ +# sections returned by readModels (used for dynamic active bindings) +.mplus_sections <- c( + "input", "warnings", "errors", "data_summary", "sampstat", + "covariance_coverage", "summaries", "invariance_testing", + "parameters", "class_counts", "indirect", "mod_indices", + "residuals", "savedata", "savedata_info", "bparameters", + "tech1", "tech3", "tech4", "tech7", "tech8", "tech9", + "tech10", "tech12", "tech15", "fac_score_stats", + "lcCondMeans", "r3step", "gh5", "h5results", "output" +) + #' Create an mplusModel object for a given model #' @param syntax a character vector of Mplus input syntax for this model #' @param data a data.frame to be used for estimating the model @@ -13,203 +24,222 @@ mplusModel <- function(syntax=NULL, data=NULL, inp_file=NULL, read=TRUE, Mplus_c return(mobj) } -#' An R6 class for a single Mplus model +#' @title mplusModel R6 class +#' @description An R6 class for a single Mplus model #' @details #' Wrapped by `mplusModel` -#' Note that this R6 class deliberately uses unlockBinding to populate private fields after the object is instantiated. -#' This allows the model outputs to be added to the relevant sections of the object while keeping the fields private. +#' @name mplusModel_r6 #' @keywords internal mplusModel_r6 <- R6::R6Class( classname = "mplusModel_r6", lock_objects=FALSE, - private=list( - pvt_output_loaded = FALSE, - pvt_syntax = NULL, # syntax for this model, parsed into a list - pvt_data = NULL, # data.frame containing data for model estimation - pvt_inp_file = NULL, # name of .inp file - pvt_out_file = NULL, # name of .out file - pvt_dat_file = NULL, # name of .dat file - pvt_model_dir = NULL, # location of model files - pvt_Mplus_command = NULL, # location of Mplus binary - pvt_variables = NULL, # names of columns in data to be written to the .dat file - pvt_is_montecarlo = FALSE, # whether this is a monte carlo model (in which case the data section is irrelevant) - - # read-only outputs (backing storage) - pvt_input = NULL, - pvt_warnings = NULL, - pvt_parameters = NULL, - pvt_summaries = NULL, - pvt_savedata = NULL, - - populate_output = function(o) { - private$pvt_output_loaded <- TRUE - private$pvt_parameters <- o$parameters - private$pvt_input <- o$input - private$pvt_warnings <- o$warnings - private$pvt_summaries <- o$summaries - private$pvt_savedata <- o$savedata - }, - - clear_output = function() { - private$pvt_output_loaded <- FALSE - private$pvt_parameters <- NULL - private$pvt_input <- NULL - private$pvt_warnings <- NULL - private$pvt_summaries <- NULL - private$pvt_savedata <- NULL - }, - - detect_variables = function() { - # both syntax and data must be present to attempt detection - if (is.null(private$pvt_syntax) || is.null(private$pvt_data)) return(invisible(NULL)) + private = c( + list( + pvt_output_loaded = FALSE, + pvt_syntax = NULL, # syntax for this model, parsed into a list + pvt_data = NULL, # data.frame containing data for model estimation + pvt_inp_file = NULL, # name of .inp file + pvt_out_file = NULL, # name of .out file + pvt_dat_file = NULL, # name of .dat file + pvt_model_dir = NULL, # location of model files + pvt_Mplus_command = NULL, # location of Mplus binary + pvt_variables = NULL, # names of columns in data to be written to the .dat file + pvt_is_montecarlo = FALSE, # whether this is a monte carlo model (in which case the data section is irrelevant) - # TODO: make variable detection better... detectVariables misses IDVARIABLE and CLUSTER, for example - # and we need to convert the pvt_syntax sections to strings to match detectVariables - - # this is preferred for now: use user-specified names - if (!is.null(private$pvt_syntax$variable$names)) { - private$pvt_variables <- strsplit(private$pvt_syntax$variable$names, "\\s+")[[1L]] - } else { - # mimic mplusObject to use detectVariables - obj <- list() - obj$MODEL <- private$pvt_syntax$model - obj$DEFINE <- private$pvt_syntax$define - obj$VARIABLE <- private$pvt_syntax$variable - obj$rdata <- private$pvt_data - - private$pvt_variables <- detectVariables(obj) - } - } - ), - active = list( - #' @field model_dir the directory for Mplus files corresponding to this model - model_dir = function(value) { - if (missing(value)) { - private$pvt_model_dir - } else { - if (!dir.exists(value)) dir.create(value, recursive = TRUE) - private$pvt_model_dir <- value - } - }, - - #' @field inp_file the location of the Mplus .inp file for this model - inp_file = function(value) { - if (missing(value)) file.path(private$pvt_model_dir, private$pvt_inp_file) - else stop("Cannot set read-only field") - }, - - #' @field out_file the location of the Mplus .out file for this model - out_file = function(value) { - if (missing(value)) file.path(private$pvt_model_dir, private$pvt_out_file) - else stop("Cannot set read-only field") - }, - - #' @field dat_file the location of the Mplus .dat (data) file for this model - dat_file = function(value) { - if (missing(value)) file.path(private$pvt_model_dir, private$pvt_dat_file) - else stop("Cannot set read-only field") - }, - - #' @field data the dataset used for estimating this model - data = function(value) { - if (missing(value)) { - private$pvt_data - } else { - had_data <- !is.null(private$pvt_data) # is the user updating data for an existing model? - if (is.null(value)) { - private$pvt_data <- NULL # unset data - } else if (checkmate::test_data_table(value)) { - private$pvt_data <- as.data.frame(value) - } else if (checkmate::test_data_frame(value)) { - private$pvt_data <- value - } else { - stop("data must be a data.frame object") - } + # private method to populate mplus output fields from readModels result + populate_output = function(o) { + private$pvt_output_loaded <- TRUE + for (sec in .mplus_sections) private[[paste0("pvt_", sec)]] <- o[[sec]] + }, + + # private method to clear mplus output fields (if output is invalidated) + clear_output = function() { + private$pvt_output_loaded <- FALSE + for (sec in .mplus_sections) private[[paste0("pvt_", sec)]] <- NULL + }, + + detect_variables = function() { + # both syntax and data must be present to attempt detection + if (is.null(private$pvt_syntax) || is.null(private$pvt_data)) return(invisible(NULL)) - if (had_data) { - # invalidate loaded output if data changes - message("Data has changed. Unloading model results from object.") - private$clear_output() - } + # TODO: make variable detection better... detectVariables misses IDVARIABLE and CLUSTER, for example + # and we need to convert the pvt_syntax sections to strings to match detectVariables - # if we are updating the dataset, make sure that all expected variables are present - if (!is.null(value) && !is.null(private$pvt_variables)) { - missing_vars <- setdiff(private$pvt_variables, names(value)) - if (length(missing_vars) > 0L) - warning("The following variables are mentioned in the model syntax, but missing in the data: ", - paste(missing_vars, collapse=", ")) + # this is preferred for now: use user-specified names + if (!is.null(private$pvt_syntax$variable$names)) { + private$pvt_variables <- strsplit(private$pvt_syntax$variable$names, "\\s+")[[1L]] + } else { + # mimic mplusObject to use detectVariables + obj <- list() + obj$MODEL <- private$pvt_syntax$model + obj$DEFINE <- private$pvt_syntax$define + obj$VARIABLE <- private$pvt_syntax$variable + obj$rdata <- private$pvt_data + + private$pvt_variables <- detectVariables(obj) } } - }, + ), - #' @field Mplus_command the location of the Mplus program - Mplus_command = function(value) { - if (missing(value)) { - private$pvt_Mplus_command - } else { - if (is.null(value)) { - private$pvt_Mplus_command <- MplusAutomation::detectMplus() # default - } else if (!checkmate::test_string(value)) { - warning("Mplus_command must be a character string pointing to the location of Mplus") + # all output sections from readModels + setNames(vector("list", length(.mplus_sections)), paste0("pvt_", .mplus_sections)) + ), + active = c( + list( + #' @field model_dir the directory for Mplus files corresponding to this model + model_dir = function(value) { + if (missing(value)) { + private$pvt_model_dir } else { - private$pvt_Mplus_command <- value - if (!checkmate::test_file_exists(value)) warning("Mplus_command does not point to a valid location. This could cause problems!") + if (!dir.exists(value)) dir.create(value, recursive = TRUE) + private$pvt_model_dir <- value } - } - }, - - #' @field syntax the Mplus syntax for this model as a character vector - syntax = function(value) { - if (missing(value)) { - mplusInpToString(private$pvt_syntax) - #unname(unlist(private$pvt_syntax)) # unlist to return as character - } else { - if (!checkmate::test_character(value)) { - stop("Syntax must be a character vector") + }, + + #' @field inp_file the location of the Mplus .inp file for this model + inp_file = function(value) { + if (missing(value)) file.path(private$pvt_model_dir, private$pvt_inp_file) + else stop("Cannot set read-only field", call. = FALSE) + }, + + #' @field out_file the location of the Mplus .out file for this model + out_file = function(value) { + if (missing(value)) file.path(private$pvt_model_dir, private$pvt_out_file) + else stop("Cannot set read-only field", call. = FALSE) + }, + + #' @field dat_file the location of the Mplus .dat (data) file for this model + dat_file = function(value) { + if (missing(value)) file.path(private$pvt_model_dir, private$pvt_dat_file) + else stop("Cannot set read-only field", call. = FALSE) + }, + + #' @field data the dataset used for estimating this model + data = function(value) { + if (missing(value)) { + private$pvt_data } else { - private$pvt_syntax <- parseMplusSyntax(value, dropSectionNames = TRUE) - - # detect variables in syntax - private$detect_variables() - - if (!is.null(private$pvt_data) && !is.null(private$pvt_variables)) { - missing_vars <- setdiff(private$pvt_variables, names(private$pvt_data)) + had_data <- !is.null(private$pvt_data) # is the user updating data for an existing model? + if (is.null(value)) { + private$pvt_data <- NULL # unset data + } else if (checkmate::test_data_table(value)) { + private$pvt_data <- as.data.frame(value) + } else if (checkmate::test_data_frame(value)) { + private$pvt_data <- value + } else { + stop("data must be a data.frame object") + } + + if (had_data) { + # invalidate loaded output if data changes + message("Data has changed. Unloading model results from object.") + private$clear_output() + } + + # if we are updating the dataset, make sure that all expected variables are present + if (!is.null(value) && !is.null(private$pvt_variables)) { + missing_vars <- setdiff(private$pvt_variables, names(value)) if (length(missing_vars) > 0L) warning("The following variables are mentioned in the model syntax, but missing in the data: ", paste(missing_vars, collapse=", ")) } - - # determine whether this is a montecarlo model - private$pvt_is_montecarlo <- any(grepl("^\\s*montecarlo\\s*:", value, ignore.case = TRUE, perl=TRUE)) + } + }, + + #' @field Mplus_command the location of the Mplus program + Mplus_command = function(value) { + if (missing(value)) { + private$pvt_Mplus_command + } else { + if (is.null(value)) { + private$pvt_Mplus_command <- MplusAutomation::detectMplus() # default + } else if (!checkmate::test_string(value)) { + warning("Mplus_command must be a character string pointing to the location of Mplus") + } else { + private$pvt_Mplus_command <- value + if (!checkmate::test_file_exists(value)) warning("Mplus_command does not point to a valid location. This could cause problems!") + } + } + }, + + #' @field syntax the Mplus syntax for this model as a character vector + syntax = function(value) { + if (missing(value)) { + mplusInpToString(private$pvt_syntax) + #unname(unlist(private$pvt_syntax)) # unlist to return as character + } else { + if (!checkmate::test_character(value)) { + stop("Syntax must be a character vector") + } else { + private$pvt_syntax <- parseMplusSyntax(value, dropSectionNames = TRUE) + + # detect variables in syntax + private$detect_variables() + + if (!is.null(private$pvt_data) && !is.null(private$pvt_variables)) { + missing_vars <- setdiff(private$pvt_variables, names(private$pvt_data)) + if (length(missing_vars) > 0L) + warning("The following variables are mentioned in the model syntax, but missing in the data: ", + paste(missing_vars, collapse=", ")) + } + + # determine whether this is a montecarlo model + private$pvt_is_montecarlo <- any(grepl("^\\s*montecarlo\\s*:", value, ignore.case = TRUE, perl=TRUE)) + } } } - }, + ), - # ---- read-only output fields (active bindings) ---- - #' @field input Parsed Mplus input sections (read-only) - input = function(value) { - if (missing(value)) private$pvt_input - else stop("`input` is read-only.") - }, - #' @field warnings Mplus warnings (read-only) - warnings = function(value) { - if (missing(value)) private$pvt_warnings - else stop("`warnings` is read-only.") - }, - #' @field parameters Parameter estimates (read-only) - parameters = function(value) { - if (missing(value)) private$pvt_parameters - else stop("`parameters` is read-only.") - }, - #' @field summaries Model summaries/statistics (read-only) - summaries = function(value) { - if (missing(value)) private$pvt_summaries - else stop("`summaries` is read-only.") - }, - #' @field savedata Data produced by SAVEDATA (read-only) - savedata = function(value) { - if (missing(value)) private$pvt_savedata - else stop("`savedata` is read-only.") + # Dynamic read-only active bindings for all .mplus_sections + # Pass through the argument sec as a function attribute because R6 resets the function environment + # to point to the R6 object itself (so self and private are visible) + + #' @section Active bindings (from `readModels()`): + #' @field input Read-only accessor for the `input` section returned by `readModels()`. + #' @field warnings Read-only accessor for the `warnings` section returned by `readModels()`. + #' @field errors Read-only accessor for the `errors` section returned by `readModels()`. + #' @field data_summary Read-only accessor for the `data_summary` section returned by `readModels()`. + #' @field sampstat Read-only accessor for the `sampstat` section returned by `readModels()`. + #' @field covariance_coverage Read-only accessor for the `covariance_coverage` section returned by `readModels()`. + #' @field summaries Read-only accessor for the `summaries` section returned by `readModels()`. + #' @field invariance_testing Read-only accessor for the `invariance_testing` section returned by `readModels()`. + #' @field parameters Read-only accessor for the `parameters` section returned by `readModels()`. + #' @field class_counts Read-only accessor for the `class_counts` section returned by `readModels()`. + #' @field indirect Read-only accessor for the `indirect` section returned by `readModels()`. + #' @field mod_indices Read-only accessor for the `mod_indices` section returned by `readModels()`. + #' @field residuals Read-only accessor for the `residuals` section returned by `readModels()`. + #' @field savedata Read-only accessor for the `savedata` section returned by `readModels()`. + #' @field savedata_info Read-only accessor for the `savedata_info` section returned by `readModels()`. + #' @field bparameters Read-only accessor for the `bparameters` section returned by `readModels()`. + #' @field tech1 Read-only accessor for the `tech1` section returned by `readModels()`. + #' @field tech3 Read-only accessor for the `tech3` section returned by `readModels()`. + #' @field tech4 Read-only accessor for the `tech4` section returned by `readModels()`. + #' @field tech7 Read-only accessor for the `tech7` section returned by `readModels()`. + #' @field tech8 Read-only accessor for the `tech8` section returned by `readModels()`. + #' @field tech9 Read-only accessor for the `tech9` section returned by `readModels()`. + #' @field tech10 Read-only accessor for the `tech10` section returned by `readModels()`. + #' @field tech12 Read-only accessor for the `tech12` section returned by `readModels()`. + #' @field tech15 Read-only accessor for the `tech15` section returned by `readModels()`. + #' @field fac_score_stats Read-only accessor for the `fac_score_stats` section returned by `readModels()`. + #' @field lcCondMeans Read-only accessor for the `lcCondMeans` section returned by `readModels()`. + #' @field r3step Read-only accessor for the `r3step` section returned by `readModels()`. + #' @field gh5 Read-only accessor for the `gh5` section returned by `readModels()`. + #' @field h5results Read-only accessor for the `h5results` section returned by `readModels()`. + #' @field output Read-only accessor for the `output` section returned by `readModels()`. + { + .make_ro_binding <- function(section) { + f <- function(value) { + s <- attr(sys.function(), "section") + if (missing(value)) { + private[[paste0("pvt_", s)]] + } else { + stop(sprintf("`%s` is read-only.", s), call. = FALSE) + } + } + attr(f, "section") <- section + f + } + setNames(lapply(.mplus_sections, .make_ro_binding), .mplus_sections) } ), public=list( @@ -271,14 +301,6 @@ mplusModel_r6 <- R6::R6Class( # set Mplus command self$Mplus_command <- Mplus_command - - ### args from submitModels - # function(target=getwd(), recursive=FALSE, filefilter = NULL, - # replaceOutfile="modifiedDate", Mplus_command = NULL, quiet = FALSE, - # scheduler="slurm", sched_args=NULL, env_variables=NULL, export_all=FALSE, - # cores_per_model = 1L, memgb_per_model = 8L, time_per_model="1:00:00", - # time_per_command = NULL, pre=NULL, post=NULL, batch_outdir=NULL, job_script_prefix=NULL, - # debug = FALSE, fail_on_error = TRUE }, #' @description read the results of an Mplus model from the .out file using `readModels` @@ -308,14 +330,14 @@ mplusModel_r6 <- R6::R6Class( if (!quiet) message("Not overwriting existing data file: ", self$dat_file) return(invisible(self)) } - + inp_syntax <- prepareMplusData(df = self$data, filename = self$dat_file, keepCols=private$pvt_variables, quiet = TRUE, use_relative_path = TRUE, ...) # ensure that the variable names in the syntax match what we detected private$pvt_syntax$variable$names <- attr(inp_syntax, "variable_names") private$pvt_syntax$variable$missing <- attr(inp_syntax, "missing") private$pvt_syntax$data$file <- attr(inp_syntax, "data_file") # update FILE = in DATA section to match absolute/relative (NB, this is overridden in write_inp... need to unify) - + if (!quiet) message("Writing data to file: ", self$dat_file) return(invisible(self)) }, @@ -381,7 +403,7 @@ mplusModel_r6 <- R6::R6Class( self$write_inp() runModels(target = self$inp_file, replaceOutfile = replaceOutfile, Mplus_command = self$Mplus_command, ...) self$read(force = TRUE) # read/re-read after estimation - + } ) ) @@ -403,99 +425,152 @@ joinRegexExpand <- function(cmd, argExpand, matches, iterator, matchLength = "ma return(cmd.expand) } - -# expand Mplus hyphen syntax (will also expand constraints with hyphens) -expandCmd <- function(cmd) { - # use negative lookahead and negative lookbehind to eliminate possibility of hyphen being used as a negative starting value (e.g., x*-1) - # also avoid match of anything that includes a decimal point, such as a floating-point starting value -10.5*x1 - - # need to do a better job of this so that u1-u20* is supported... I don't think the regexp below is general enough - - # hyphens <- gregexpr("(?!<(\\*|\\.))\\w+(?!(\\*|\\.))\\s*-\\s*(?!<(\\*|\\.))\\w+(?!(\\*|\\.))", cmd, perl=TRUE)[[1]] +#' Expand Mplus-style hyphenated variable ranges +#' +#' Expands Mplus shorthand expressions that specify sequences of variables +#' using hyphenated ranges (e.g., \code{y1-y3}) into the full list of +#' variables (e.g., \code{y1 y2 y3}). This function also propagates suffixes +#' from the right-hand token (e.g., \code{@c}, \code{*c}, or bare \code{*}) +#' to every expanded variable (e.g., \code{y1-y3@1} → \code{y1@1 y2@1 y3@1}). +#' +#' By default, the function does **not** expand pure numeric ranges (e.g., +#' \code{1-3}) to avoid confusion with arithmetic subtraction. If +#' \code{expand_numeric = TRUE}, such ranges will be expanded when they +#' appear in list-like contexts (whitespace/comma/semicolon/parentheses +#' boundaries) and the line does not contain an equals sign (to avoid +#' accidental expansion of arithmetic like \code{d = 1 - 3}). +#' +#' Hyphens in \code{MODEL CONSTRAINT} expressions such as +#' \code{a = b1-b2} are explicitly protected and left untouched. +#' +#' @param cmd A single character string containing Mplus syntax to expand. +#' @param expand_numeric Logical. If \code{TRUE}, expand pure numeric ranges +#' (e.g., \code{1-3} → \code{1 2 3}) in list-like contexts. Default: \code{FALSE}. +#' +#' @return A character string with hyphenated ranges expanded to explicit +#' variable lists. +#' +#' @examples +#' expandCmd("y1-y3 y5-y6") +#' # "y1 y2 y3 y5 y6" +#' +#' expandCmd("BY y1-y3@0.5;") +#' # "BY y1@0.5 y2@0.5 y3@0.5;" +#' +#' expandCmd("z10-z12*2") +#' # "z10*2 z11*2 z12*2" +#' +#' expandCmd("MODEL CONSTRAINT: a = b1-b2;") +#' # "MODEL CONSTRAINT: a = b1-b2;" (unchanged) +#' +#' expandCmd("1 - 3", expand_numeric = TRUE) +#' # "1 2 3" +#' +#' expandCmd("d = 1 - 3;", expand_numeric = TRUE) +#' # "d = 1 - 3;" (unchanged because of '=') +#' +#' @keywords internal +expandCmd <- function(cmd, expand_numeric = FALSE) { + x <- cmd - # support trailing @XXX. Still still fail on Trait1-Trait3*XXX - hyphens <- gregexpr("(?!<(\\*|\\.))\\w+(?!(\\*|\\.))\\s*-\\s*(?!<(\\*|\\.))\\w+(?!(\\*|\\.))(@[\\d\\.\\-]+)?", cmd, perl = TRUE)[[1]] + # --- Protect constraint-style identifier subtraction (preserve spacing) --- + # Example: "a = b1-b2" becomes "a = b1‹MINUS›b2" + # The space after '=' is captured and restored unchanged. + x <- gsub( + "(=\\s*)([A-Za-z_][A-Za-z_0-9]*\\d+)\\s*-\\s*([A-Za-z_][A-Za-z_0-9]*\\d+)", + "\\1\\2‹MINUS›\\3", + x, perl = TRUE + ) - #hyphens <- unlist(gregexpr('-', cmd)) - #hyphens <- gregexpr("(\\w)(\\d+)-(\\w)(\\d+)", cmd, perl=TRUE)[[1]] + # --- Expand identifier ranges (prefixN - prefixM) --- + # Boundaries: whitespace, comma, semicolon, parentheses, or string edges. + bL <- "(?:(?<=^)|(?<=[\\s,;\\(]))" + bR <- "(?:(?=$)|(?=[\\s,;\\)]))" - # Promising, but this is still failing in the case of x3*1 -4.25*x4 - # On either side of a hyphen, require alpha character followed by alphanumeric - # This enforces that neither side of the hyphen can be a number - # Alternatively, match digits on either side alone - # hyphens <- gregexpr("([A-z]+\\w*\\s*-\\s*[A-z]+\\w*(@[\\d\\.-]+)?|\\d+\\s*-\\s*\\d+)", cmd, perl=TRUE)[[1]] + id_pattern <- paste0( + bL, + "(?", + "(?[A-Za-z_][A-Za-z_0-9]*?)(?\\d+)", + "\\s*-\\s*", + "(?[A-Za-z_][A-Za-z_0-9]*?)(?\\d+)", + "(?(?:@[-+]?\\d+(?:\\.\\d+)?|\\*[-+]?\\d*(?:\\.\\d+)?)?)", + ")", + bR + ) - if (hyphens[1L] > 0) { - cmd.expand <- c() - ep <- 1 + m <- gregexpr(id_pattern, x, perl = TRUE) + if (m[[1]][1L] != -1L) { + starts <- as.integer(m[[1]]) + caps <- attr(m[[1]], "capture.start") + clen <- attr(m[[1]], "capture.length") + nm <- attr(m[[1]], "capture.names") + + cap <- function(k, name) { + i <- match(name, nm) + if (is.na(i) || caps[k, i] == -1L) "" else + substr(x, caps[k, i], caps[k, i] + clen[k, i] - 1L) + } - for (v in 1:length(hyphens)) { - # match one keyword before and after hyphen - argsplit <- strsplit(substr(cmd, hyphens[v], hyphens[v] + attr(hyphens, "match.length")[v] - 1), "\\s*-\\s*", perl = TRUE)[[1]] + # Replace matches from right to left so string indices stay valid. + for (k in rev(seq_along(starts))) { + a1 <- cap(k, "alpha1"); a2 <- cap(k, "alpha2") + i1 <- as.integer(cap(k, "i1")); i2 <- as.integer(cap(k, "i2")) + suf <- cap(k, "suf") - v_pre <- argsplit[1] - v_post <- argsplit[2] + # Skip if prefixes differ or indices invalid. + if (!nzchar(a1) || a1 != a2 || is.na(i1) || is.na(i2) || i2 < i1) next - v_post.suffix <- sub("^([^@\\*]+)([@\\*][\\d\\-.]+)?$", "\\2", v_post, perl = TRUE) # will be empty string if not present - v_post <- sub("[@\\*][\\d\\-.]+$", "", v_post, perl = TRUE) # trim @ suffix + # Build expansion sequence. + seq_ids <- paste0(a1, i1:i2) + if (nzchar(suf)) seq_ids <- paste0(seq_ids, suf) + repl <- paste(seq_ids, collapse = " ") - # If v_pre and v_post contain leading alpha characters, verify that these prefixes match. - # Otherwise, there is nothing to expand, as in the case of MODEL CONSTRAINT: e1e2=e1-e2_n. - v_pre.alpha <- sub("\\d+$", "", v_pre, perl = TRUE) - v_post.alpha <- sub("\\d+$", "", v_post, perl = TRUE) + # Replace full match with expanded list. + full_start <- caps[k, match("full", nm)] + full_len <- clen[k, match("full", nm)] + x <- paste0( + substr(x, 1L, full_start - 1L), + repl, + substr(x, full_start + full_len, nchar(x)) + ) + } + } + + # --- Optional: expand pure numeric ranges (1 - 3 → 1 2 3) --- + # Only applied if expand_numeric = TRUE and no '=' is present in the line + # (to avoid arithmetic like "d = 1 - 3;"). + if (isTRUE(expand_numeric) && !grepl("=", x, fixed = TRUE)) { + num_pattern <- paste0(bL, "(?(?\\d+)\\s*-\\s*(?\\d+))", bR) + m2 <- gregexpr(num_pattern, x, perl = TRUE) + if (m2[[1]][1L] != -1L) { + starts <- as.integer(m2[[1]]) + caps <- attr(m2[[1]], "capture.start") + clen <- attr(m2[[1]], "capture.length") + nm <- attr(m2[[1]], "capture.names") - # only enforce prefix match if we have leading alpha characters (i.e., not simple numeric 1 - 3 syntax) - if (length(v_pre.alpha) > 0L && length(v_post.alpha) > 0L) { - # if alpha prefixes do match, assume that the hyphen is not for expansion (e.g., in subtraction case) - if (v_pre.alpha != v_post.alpha) { - return(cmd) - } + cap2 <- function(k, name) { + i <- match(name, nm) + if (is.na(i) || caps[k, i] == -1L) "" else + substr(x, caps[k, i], caps[k, i] + clen[k, i] - 1L) } - # the basic positive lookbehind blows up with pure numeric constraints (1 - 3) because no alpha char precedes digit - # can use an non-capturing alternation grouping to allow for digits only or the final digits after alphas (as in v_post.num) - v_pre.num <- as.integer(sub("\\w*(?<=[A-Za-z_])(\\d+)$", "\\1", v_pre, perl = TRUE)) # use positive lookbehind to avoid greedy \w+ match -- capture all digits - - v_post.match <- regexpr("^(?:\\w*(?<=[A-Za-z_])(\\d+)|(\\d+))$", v_post, perl = TRUE) - stopifnot(v_post.match[1L] > 0) - - # match mat be under capture[1] or capture[2] because of alternation above - whichCapture <- which(attr(v_post.match, "capture.start") > 0) - - v_post.num <- as.integer(substr(v_post, attr(v_post.match, "capture.start")[whichCapture], attr(v_post.match, "capture.start")[whichCapture] + attr(v_post.match, "capture.length")[whichCapture] - 1)) - v_post.prefix <- substr(v_post, 1, attr(v_post.match, "capture.start")[whichCapture] - 1) # just trusting that pre and post match - - if (is.na(v_pre.num) || is.na(v_post.num)) stop("Cannot expand variables: ", v_pre, ", ", v_post) - v_expand <- paste(v_post.prefix, v_pre.num:v_post.num, v_post.suffix, sep = "", collapse = " ") - - # for first hyphen, there may be non-hyphenated syntax preceding the initial match - cmd.expand[ep] <- joinRegexExpand(cmd, v_expand, hyphens, v) - - # This won't really work because the cmd.expand element may contain other variables - # that are at the beginning or end, prior to hyphen stuff - # This is superseded by logic above where @ is included in hyphen match, then trapped as suffix - # I don't think it will work yet for this Mplus syntax: y1-y10*5 -- the 5 wouldn't propagate - # handle the case of @ fixed values or * starting values used in a list - # example: Trait1-Trait3@1 - ## if (grepl("@|\\*", cmd.expand[ep], perl=TRUE)) { - ## exp_split <- strsplit(cmd.expand[ep], "\\s+", perl=TRUE)[[1]] - ## suffixes <- sub("^([^@\\*]+)([@*][\\d\\.-]+)?$", "\\2", exp_split, perl=TRUE) - ## variables <- sub("^([^@\\*]+)([@*][\\d\\.-]+)?$", "\\1", exp_split, perl=TRUE) - ## suffixes <- suffixes[suffixes != ""] - ## if (length(unique(suffixes)) > 1L) { - ## browser() - - ## #stop("Don't know how to interpret syntax: ", cmd) - ## } else { - ## variables <- paste0(variables, suffixes[1]) - ## cmd.expand[ep] <- paste(variables, collapse=" ") - ## } - ## } - - ep <- ep + 1 + for (k in rev(seq_along(starts))) { + a <- as.integer(cap2(k, "a")); b <- as.integer(cap2(k, "b")) + if (is.na(a) || is.na(b) || b < a) next + repl <- paste(a:b, collapse = " ") + full_start <- caps[k, match("full", nm)] + full_len <- clen[k, match("full", nm)] + x <- paste0( + substr(x, 1L, full_start - 1L), + repl, + substr(x, full_start + full_len, nchar(x)) + ) + } } - return(paste(cmd.expand, collapse = "")) - } else { - return(cmd) # no hyphens to expand } -} + + # --- Unprotect sentinels --- + x <- gsub("‹MINUS›", "-", x, fixed = TRUE) + + x +} \ No newline at end of file diff --git a/R/parseOutput.R b/R/parseOutput.R index 21af0bf..b7b5073 100644 --- a/R/parseOutput.R +++ b/R/parseOutput.R @@ -500,8 +500,8 @@ divideIntoFields <- function(section.text, required) { #' @param filename The filename #' @param input The input #' @return A list with two elements -#' \item{errors}{Mplus Errors} -#' \item{warnings}{Mplus Warnings} +#' * `errors`: Mplus Errors +#' * `warnings`: Mplus Warnings #' @keywords internal #' @examples #' # make me!!! @@ -1047,56 +1047,56 @@ extractSummaries_1file <- function(outfiletext, filename, input) #' #' @return Returns a \code{data.frame} containing model fit statistics for all output files within \code{directory}. #' The \code{data.frame} contains some of the following variables (depends on model type): -#' \item{Title}{Title for the model, specified by the TITLE: command} -#' \item{Filename}{Filename of the output file} -#' \item{Estimator}{Estimator used for the model (e.g., ML, MLR, WLSMV, etc.)} -#' \item{LL}{Log-likelihood of the model} -#' \item{BIC}{Bayesian Information Criterion} -#' \item{aBIC}{Sample-Size-Adjusted BIC (Sclove, 1987)} -#' \item{AIC}{Akaike's Information Criterion} -#' \item{AICC}{Corrected AIC, based on Sugiura (1978) and recommended by Burnham & Anderson (2002)} -#' \item{DIC}{Deviance Information Criterion. Available in ESTIMATOR=BAYES output.} -#' \item{Parameters}{Number of parameters estimated by the model} -#' \item{pD}{Estimated number of parameters in Bayesian output} -#' \item{Observations}{The number of observations for the model (does not suppport multiple-groups analysis at this time)} -#' \item{CFI}{Confirmatory Fit Index} -#' \item{TLI}{Tucker-Lewis Index} -#' \item{RMSEA_Estimate}{Point estimate of root mean squared error of approximation} -#' \item{RMSEA_90CI_LB}{Lower bound of the 90\% Confidence Interval around the RMSEA estimate.} -#' \item{RMSEA_90CI_UB}{Upper bound of the 90\% Confidence Interval around the RMSEA estimate.} -#' \item{RMSEA_pLT05}{Probability that the RMSEA estimate falls below .05, indicating good fit.} -#' \item{ChiSqM_Value}{Model chi-squared value} -#' \item{ChiSqM_DF}{Model chi-squared degrees of freedom} -#' \item{ChiSqM_PValue}{Model chi-squared p value} -#' \item{ChiSqM_ScalingCorrection}{H0 Scaling Correction Factor} -#' \item{ObsRepChiSqDiff_95CI_LB}{Lower bound of 95\% confidence interval for the difference between observed and replicated chi-square values} -#' \item{ObsRepChiSqDiff_95CI_UB}{Upper bound of 95\% confidence interval for the difference between observed and replicated chi-square values} -#' \item{PostPred_PValue}{Posterior predictive p-value} -#' \item{PriorPostPred_PValue}{Prior Posterior Predictive P-Value} -#' \item{BLRT_RequestedDraws}{Number of requested bootstrap draws for TECH14.} -#' \item{BLRT_KM1LL}{Log-likelihood of the K-1 model (one less class) for the Bootstrapped Likelihood Ratio Test (TECH14).} -#' \item{BLRT_2xLLDiff}{Two times the log-likelihood difference of the models with K and K-1 classes (TECH14).} -#' \item{BLRT_ParamDiff}{Difference in the number of parameters for models with K and K-1 classes (TECH14).} -#' \item{BLRT_PValue}{P-value of the Bootstrapped Likelihood Ratio Test (TECH14) testing whether the K class model is significantly better than K-1} -#' \item{BLRT_SuccessfulDraws}{The number of successful bootstrapped samples used in the Bootstrapped Likelihood Ratio Test} -#' \item{SRMR}{Standardized root mean square residual} -#' \item{SRMR.Between}{For TYPE=TWOLEVEL output, standardized root mean square residual for between level} -#' \item{SRMR.Within}{For TYPE=TWOLEVEL output, standardized root mean square residual for within level} -#' \item{WRMR}{Weighted root mean square residual} -#' \item{ChiSqBaseline_Value}{Baseline (unstructured) chi-squared value} -#' \item{ChiSqBaseline_DF}{Baseline (unstructured) chi-squared degrees of freedom} -#' \item{ChiSqBaseline_PValue}{Baseline (unstructured) chi-squared p value} -#' \item{NumFactors}{For TYPE=EFA output, the number of factors} -#' \item{T11_KM1Starts}{TECH11: Number of initial stage random starts for k-1 model} -#' \item{T11_KM1Final}{TECH11: Number of final stage optimizations for k-1 model} -#' \item{T11_KM1LL}{TECH11: Log-likelihood of the K-1 model used for the Vuong-Lo-Mendell-Rubin LRT} -#' \item{T11_VLMR_2xLLDiff}{TECH11: 2 * Log-likelihood Difference of K-class vs. K-1-class model for the Vuong-Lo-Mendell-Rubin LRT} -#' \item{T11_VLMR_ParamDiff}{TECH11: Difference in number of parameters between K-class and K-1-class model for the Vuong-Lo-Mendell-Rubin LRT} -#' \item{T11_VLMR_Mean}{TECH11: Vuong-Lo-Mendell-Rubin LRT mean} -#' \item{T11_VLMR_SD}{TECH11: Vuong-Lo-Mendell-Rubin LRT standard deviation} -#' \item{T11_VLMR_PValue}{TECH11: Vuong-Lo-Mendell-Rubin LRT p-value} -#' \item{T11_LMR_Value}{TECH11: Lo-Mendell-Rubin Adjusted LRT value} -#' \item{T11_LMR_PValue}{TECH11: Lo-Mendell-Rubin Adjusted LRT p-value} +#' * `Title`: Title for the model, specified by the TITLE: command +#' * `Filename`: Filename of the output file +#' * `Estimator`: Estimator used for the model (e.g., ML, MLR, WLSMV, etc.) +#' * `LL`: Log-likelihood of the model +#' * `BIC`: Bayesian Information Criterion +#' * `aBIC`: Sample-Size-Adjusted BIC (Sclove, 1987) +#' * `AIC`: Akaike's Information Criterion +#' * `AICC`: Corrected AIC, based on Sugiura (1978) and recommended by Burnham & Anderson (2002) +#' * `DIC`: Deviance Information Criterion. Available in ESTIMATOR=BAYES output. +#' * `Parameters`: Number of parameters estimated by the model +#' * `pD`: Estimated number of parameters in Bayesian output +#' * `Observations`: The number of observations for the model (does not suppport multiple-groups analysis at this time) +#' * `CFI`: Confirmatory Fit Index +#' * `TLI`: Tucker-Lewis Index +#' * `RMSEA_Estimate`: Point estimate of root mean squared error of approximation +#' * `RMSEA_90CI_LB`: Lower bound of the 90\% Confidence Interval around the RMSEA estimate. +#' * `RMSEA_90CI_UB`: Upper bound of the 90\% Confidence Interval around the RMSEA estimate. +#' * `RMSEA_pLT05`: Probability that the RMSEA estimate falls below .05, indicating good fit. +#' * `ChiSqM_Value`: Model chi-squared value +#' * `ChiSqM_DF`: Model chi-squared degrees of freedom +#' * `ChiSqM_PValue`: Model chi-squared p value +#' * `ChiSqM_ScalingCorrection`: H0 Scaling Correction Factor +#' * `ObsRepChiSqDiff_95CI_LB`: Lower bound of 95\% confidence interval for the difference between observed and replicated chi-square values +#' * `ObsRepChiSqDiff_95CI_UB`: Upper bound of 95\% confidence interval for the difference between observed and replicated chi-square values +#' * `PostPred_PValue`: Posterior predictive p-value +#' * `PriorPostPred_PValue`: Prior Posterior Predictive P-Value +#' * `BLRT_RequestedDraws`: Number of requested bootstrap draws for TECH14. +#' * `BLRT_KM1LL`: Log-likelihood of the K-1 model (one less class) for the Bootstrapped Likelihood Ratio Test (TECH14). +#' * `BLRT_2xLLDiff`: Two times the log-likelihood difference of the models with K and K-1 classes (TECH14). +#' * `BLRT_ParamDiff`: Difference in the number of parameters for models with K and K-1 classes (TECH14). +#' * `BLRT_PValue`: P-value of the Bootstrapped Likelihood Ratio Test (TECH14) testing whether the K class model is significantly better than K-1 +#' * `BLRT_SuccessfulDraws`: The number of successful bootstrapped samples used in the Bootstrapped Likelihood Ratio Test +#' * `SRMR`: Standardized root mean square residual +#' * `SRMR.Between`: For TYPE=TWOLEVEL output, standardized root mean square residual for between level +#' * `SRMR.Within`: For TYPE=TWOLEVEL output, standardized root mean square residual for within level +#' * `WRMR`: Weighted root mean square residual +#' * `ChiSqBaseline_Value`: Baseline (unstructured) chi-squared value +#' * `ChiSqBaseline_DF`: Baseline (unstructured) chi-squared degrees of freedom +#' * `ChiSqBaseline_PValue`: Baseline (unstructured) chi-squared p value +#' * `NumFactors`: For TYPE=EFA output, the number of factors +#' * `T11_KM1Starts`: TECH11: Number of initial stage random starts for k-1 model +#' * `T11_KM1Final`: TECH11: Number of final stage optimizations for k-1 model +#' * `T11_KM1LL`: TECH11: Log-likelihood of the K-1 model used for the Vuong-Lo-Mendell-Rubin LRT +#' * `T11_VLMR_2xLLDiff`: TECH11: 2 * Log-likelihood Difference of K-class vs. K-1-class model for the Vuong-Lo-Mendell-Rubin LRT +#' * `T11_VLMR_ParamDiff`: TECH11: Difference in number of parameters between K-class and K-1-class model for the Vuong-Lo-Mendell-Rubin LRT +#' * `T11_VLMR_Mean`: TECH11: Vuong-Lo-Mendell-Rubin LRT mean +#' * `T11_VLMR_SD`: TECH11: Vuong-Lo-Mendell-Rubin LRT standard deviation +#' * `T11_VLMR_PValue`: TECH11: Vuong-Lo-Mendell-Rubin LRT p-value +#' * `T11_LMR_Value`: TECH11: Lo-Mendell-Rubin Adjusted LRT value +#' * `T11_LMR_PValue`: TECH11: Lo-Mendell-Rubin Adjusted LRT p-value #' #' @author Michael Hallquist #' @seealso \code{\link{regex}}, \code{\link{runModels}}, \code{\link{readModels}} diff --git a/R/readModels.R b/R/readModels.R index c1790c6..7a84180 100644 --- a/R/readModels.R +++ b/R/readModels.R @@ -41,36 +41,35 @@ #' elements containing major output sections, as detailed below. If #' \code{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: -#' \item{input}{Mplus input syntax parsed into a list by major section} -#' \item{warnings}{Syntax and estimation warnings as a list} -#' \item{errors}{Syntax and estimation errors as a list} -#' \item{data_summary}{Output of SUMMARY OF DATA section, including cluster sizes and ICCs} -#' \item{sampstat}{Sample statistics provided by OUTPUT: SAMPSTAT, if specified} -#' \item{covariance_coverage}{Covariance coverage matrix for checking missingness patterns} -#' \item{summaries}{Summary statistics from \code{extractModelSummaries}, having structure as specified by that function} -#' \item{parameters}{Model parameters from \code{extractModelParameters}, having structure as specified by that function} -#' \item{class_counts}{Latent class counts and proportions for models that include a categorical latent variable} -#' \item{indirect}{Output of MODEL INDIRECT if available in output. Contains \code{$overall} and \code{$specific} data.frames for each indirect effect section} -#' \item{mod_indices}{Model modification indices from \code{extractModIndices}, having structure as specified by that function} -#' \item{residuals}{a list containing relevant information from OUTPUT: RESIDUALS} -#' \item{savedata_info}{File information about SAVEDATA files related to this output} -#' \item{savedata}{SAVEDATA file as an R \code{data.frame}, as described in \code{getSavedata_Data}} -#' \item{bparameters}{an \code{mcmc.list} object containing the draws from the MCMC chains for a Bayesian model that uses the -#' SAVEDATA: BPARAMETERS command} -#' \item{tech1}{a list containing parameter specification and starting values from OUTPUT: TECH1} -#' \item{tech3}{a list containing parameter covariance and correlation matrices from OUTPUT: TECH3} -#' \item{tech4}{a list containing means, covariances, and correlations for latent variables from OUTPUT: TECH4} -#' \item{tech7}{a list containing sample statistics for each latent class from OUTPUT: TECH7} -#' \item{tech8}{a list containing optimization history of the model. Currently only supports potential scale reduction in BAYES. OUTPUT: TECH8} -#' \item{tech9}{a list containing warnings/errors from replication runs for MONTECARLO analyses from OUTPUT: TECH9} -#' \item{tech10}{a list containing model fit information from OUTPUT: TECH10} -#' \item{tech12}{a list containing observed versus estimated sample statistics for TYPE=MIXTURE analyses from OUTPUT: TECH12} -#' \item{fac_score_stats}{factor score mean, correlation, and covariance structure from SAMPLE STATISTICS FOR ESTIMATED FACTOR SCORES section} -#' \item{lcCondMeans}{conditional latent class means and pairwise comparisons, obtained using auxiliary(e) syntax in latent class models} -#' \item{r3step}{predictors of latent class membership using the 3-step procedure (R3STEP)} -#' \item{gh5}{a list containing data from the gh5 (graphics) file corresponding to this output. (Requires rhdf5 package)} -#' \item{h5results}{a list containing data from h5results file produced by Mplus v8.11+. (Requires rhdf5 package)} -#' \item{output}{The entire, raw output file.} +#' * `input`: Mplus input syntax parsed into a list by major section +#' * `warnings`: Syntax and estimation warnings as a list +#' * `errors`: Syntax and estimation errors as a list +#' * `data_summary`: Output of SUMMARY OF DATA section, including cluster sizes and ICCs +#' * `sampstat`: Sample statistics provided by OUTPUT: SAMPSTAT, if specified +#' * `covariance_coverage`: Covariance coverage matrix for checking missingness patterns +#' * `summaries`: Summary statistics from \code{extractModelSummaries}, having structure as specified by that function +#' * `parameters`: Model parameters from \code{extractModelParameters}, having structure as specified by that function +#' * `class_counts`: Latent class counts and proportions for models that include a categorical latent variable +#' * `indirect`: Output of MODEL INDIRECT if available in output. Contains \code{$overall} and \code{$specific} data.frames for each indirect effect section +#' * `mod_indices`: Model modification indices from \code{extractModIndices}, having structure as specified by that function +#' * `residuals`: a list containing relevant information from OUTPUT: RESIDUALS +#' * `savedata_info`: File information about SAVEDATA files related to this output +#' * `savedata`: SAVEDATA file as an R \code{data.frame}, as described in \code{getSavedata_Data} +#' * `bparameters`: an \code{mcmc.list} object containing the draws from the MCMC chains for a Bayesian model that uses the SAVEDATA: BPARAMETERS command +#' * `tech1`: a list containing parameter specification and starting values from OUTPUT: TECH1 +#' * `tech3`: a list containing parameter covariance and correlation matrices from OUTPUT: TECH3 +#' * `tech4`: a list containing means, covariances, and correlations for latent variables from OUTPUT: TECH4 +#' * `tech7`: a list containing sample statistics for each latent class from OUTPUT: TECH7 +#' * `tech8`: a list containing optimization history of the model. Currently only supports potential scale reduction in BAYES. OUTPUT: TECH8 +#' * `tech9`: a list containing warnings/errors from replication runs for MONTECARLO analyses from OUTPUT: TECH9 +#' * `tech10`: a list containing model fit information from OUTPUT: TECH10 +#' * `tech12`: a list containing observed versus estimated sample statistics for TYPE=MIXTURE analyses from OUTPUT: TECH12 +#' * `fac_score_stats`: factor score mean, correlation, and covariance structure from SAMPLE STATISTICS FOR ESTIMATED FACTOR SCORES section +#' * `lcCondMeans`: conditional latent class means and pairwise comparisons, obtained using auxiliary(e) syntax in latent class models +#' * `r3step`: predictors of latent class membership using the 3-step procedure (R3STEP) +#' * `gh5`: a list containing data from the gh5 (graphics) file corresponding to this output. (Requires rhdf5 package) +#' * `h5results`: a list containing data from h5results file produced by Mplus v8.11+. (Requires rhdf5 package) +#' * `output`: The entire, raw output file. #' @author Michael Hallquist #' @keywords interface #' @export diff --git a/man/HTMLSummaryTable.Rd b/man/HTMLSummaryTable.Rd index e32ff07..ed71c36 100644 --- a/man/HTMLSummaryTable.Rd +++ b/man/HTMLSummaryTable.Rd @@ -29,7 +29,7 @@ Any column not included in this list will be displayed. By default, \code{dropCo Example: \code{c("InputInstructions", "TLI")}} \item{sortBy}{optional. Field name (as character string) by which to sort the table. Typically an information criterion -(e.g., "AIC" or "BIC") is used to sort the table. +(e.g., "AIC" or "BIC") is used to sort the table. Defaults to \code{NULL}, which does not sort the table.} \item{display}{optional. This parameter specifies whether to display the table in a web @@ -45,7 +45,7 @@ but these are customizable using the \code{keepCols} and \code{dropCols} paramet } \note{ You must choose between \code{keepCols} and \code{dropCols} because it is not sensible to use these - together to include and exclude columns. The function will error if you include both parameters. +together to include and exclude columns. The function will error if you include both parameters. } \examples{ # make me!!! diff --git a/man/LatexSummaryTable.Rd b/man/LatexSummaryTable.Rd index fd80758..18e722f 100644 --- a/man/LatexSummaryTable.Rd +++ b/man/LatexSummaryTable.Rd @@ -45,7 +45,7 @@ but these are customizable using the \code{keepCols} and \code{dropCols} paramet } \note{ You must choose between \code{keepCols} and \code{dropCols} because it is not sensible to use these together - to include and exclude columns. The function will error if you include both parameters. +to include and exclude columns. The function will error if you include both parameters. } \examples{ # make me!!! diff --git a/man/MplusAutomation.Rd b/man/MplusAutomation.Rd index 70050b7..60989ad 100644 --- a/man/MplusAutomation.Rd +++ b/man/MplusAutomation.Rd @@ -5,53 +5,53 @@ \title{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 (\url{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. +R language to automate latent variable model estimation and interpretation +using 'Mplus', a powerful latent variable modeling program developed by Muthen +and Muthen (\url{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: \enumerate{ - \item To automatically run groups/batches of models. - \item To provide routines to extract model fit statistics, parameter estimates, and raw data from 'Mplus' output files. - \item To facilitate comparisons among models - \item To provide a template language that allows for the creation of related input files. +\item To automatically run groups/batches of models. +\item To provide routines to extract model fit statistics, parameter estimates, and raw data from 'Mplus' output files. +\item To facilitate comparisons among models +\item To provide a template language that allows for the creation of related input files. } The core routine for running batches of models is \code{\link{runModels}}, with - an easy-to-use GUI wrapper, \code{\link{runModels_Interactive}}. +an easy-to-use GUI wrapper, \code{\link{runModels_Interactive}}. The core routine for extracting information from 'Mplus' outputs is \code{\link{readModels}}, which - returns a list containing all output sections that the package can extract. +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 \code{\link{readModels}} function. This is the recommended way to extract 'Mplus' - output with this package. If the \code{target} argument to \code{\link{readModels}} is a single .out file, - an \code{mplus.model} (that is also a \code{list}) will be returned containing all output sections that - the package can extract. If \code{target} is a directory, a list of \code{mplus.model} objects will be returned, - named according to the output filenames. +can understand, use the \code{\link{readModels}} function. This is the recommended way to extract 'Mplus' +output with this package. If the \code{target} argument to \code{\link{readModels}} is a single .out file, +an \code{mplus.model} (that is also a \code{list}) will be returned containing all output sections that +the package can extract. If \code{target} is a directory, a list of \code{mplus.model} objects will be returned, +named according to the output filenames. Note: \code{\link{extractModelSummaries}} is deprecated and \code{\link{readModels}} should be preferred. - To extract model summary statistics from one or more output files, see - \code{\link{extractModelSummaries}}, which returns a \code{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 - \code{\link{showSummaryTable}} (displays table in separate window), - \code{\link{HTMLSummaryTable}} (creates HTML file containing summary table), - or \code{\link{LatexSummaryTable}} (returns a LaTex-formatted table of - summary statistics). +To extract model summary statistics from one or more output files, see +\code{\link{extractModelSummaries}}, which returns a \code{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 +\code{\link{showSummaryTable}} (displays table in separate window), +\code{\link{HTMLSummaryTable}} (creates HTML file containing summary table), +or \code{\link{LatexSummaryTable}} (returns a LaTex-formatted table of +summary statistics). Detailed model fit and parameter comparisons between two models can be obtained using - \code{\link{compareModels}}. +\code{\link{compareModels}}. To create a group of related models from a single template, see \code{\link{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"). +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: \code{\link{prepareMplusData}}. This converts the - data.frame to a tab-delimited file and provides an 'Mplus' syntax stub for variable names. +for use with 'Mplus' is provided: \code{\link{prepareMplusData}}. This converts the +data.frame to a tab-delimited file and provides an 'Mplus' syntax stub for variable names. \tabular{ll}{ Package: \tab MplusAutomation\cr diff --git a/man/MplusAutomationUtils.Rd b/man/MplusAutomationUtils.Rd index 29f35e5..75c0023 100644 --- a/man/MplusAutomationUtils.Rd +++ b/man/MplusAutomationUtils.Rd @@ -38,7 +38,7 @@ in which case the hash is added to the user specified filename} 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. +whether a filename with the hash already existed or not. } \description{ Internal utility function, primarily for \code{prepareMplusData}. diff --git a/man/OS.Rd b/man/OS.Rd index a7111ba..9ca5efb 100644 --- a/man/OS.Rd +++ b/man/OS.Rd @@ -33,6 +33,6 @@ MplusAutomation:::is.linux() MplusAutomation:::os() } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \keyword{internal} diff --git a/man/SummaryTable.Rd b/man/SummaryTable.Rd index 338c0d1..9bd704c 100644 --- a/man/SummaryTable.Rd +++ b/man/SummaryTable.Rd @@ -21,7 +21,7 @@ SummaryTable( \item{modelList}{A list of models returned from the \code{extractModelSummaries} function.} \item{type}{A character vector indicating the type of output format to be generated. One of: -\dQuote{none}, \dQuote{screen}, \dQuote{popup}, \dQuote{html}, \dQuote{latex}, or \dQuote{markdown}. +\dQuote{none}, \dQuote{screen}, \dQuote{popup}, \dQuote{html}, \dQuote{latex}, or \dQuote{markdown}. Screen results in a simple summary table being sent to the R console.} \item{filename}{The name of the file to be created. Can be an absolute or relative path. If \code{filename} @@ -65,7 +65,7 @@ but these are customizable using the \code{keepCols} and \code{dropCols} paramet } \note{ You must choose between \code{keepCols} and \code{dropCols} because it is not sensible to use these - together to include and exclude columns. The function will error if you include both parameters. +together to include and exclude columns. The function will error if you include both parameters. } \examples{ \dontrun{ diff --git a/man/cd.Rd b/man/cd.Rd index f4593ab..cd4fe95 100644 --- a/man/cd.Rd +++ b/man/cd.Rd @@ -45,6 +45,6 @@ cd(base, pre, 2) } } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \keyword{utilities} diff --git a/man/checkSubmission.Rd b/man/checkSubmission.Rd index c892b85..a0c51bb 100644 --- a/man/checkSubmission.Rd +++ b/man/checkSubmission.Rd @@ -13,7 +13,7 @@ jobs to check on} \item{quiet}{If \code{TRUE}, do not print out the submission data.frame with current status} } \value{ -invisibly, the \code{mplus_submission_df} with `$status` amd `$status_time` updated +invisibly, the \code{mplus_submission_df} with \verb{$status} amd \verb{$status_time} updated } \description{ check on the status of submitted Mplus jobs on the cluster diff --git a/man/coef.mplus.model.Rd b/man/coef.mplus.model.Rd index 1a39986..c4f2141 100644 --- a/man/coef.mplus.model.Rd +++ b/man/coef.mplus.model.Rd @@ -37,9 +37,9 @@ vector.} } \value{ Either a data frame of class \sQuote{mplus.model.coefs}, or in - the case of multiple group models, a list of class \sQuote{mplus.model.coefs}, - where each element of the list is a data frame of class \sQuote{mplus.model.coefs}, - or a named vector of coefficients, if \code{raw=TRUE}. +the case of multiple group models, a list of class \sQuote{mplus.model.coefs}, +where each element of the list is a data frame of class \sQuote{mplus.model.coefs}, +or a named vector of coefficients, if \code{raw=TRUE}. } \description{ This is a method for returning the coefficients of an mplus.model object. @@ -91,7 +91,7 @@ Other Mplus-Formatting: \code{\link{summary.mplusObject}()} } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \concept{Mplus-Formatting} \keyword{interface} diff --git a/man/compareModels.Rd b/man/compareModels.Rd index 9758246..17b6d2f 100644 --- a/man/compareModels.Rd +++ b/man/compareModels.Rd @@ -38,7 +38,7 @@ Options are "none", "type", "alphabetical", and "maxDiff". See below for details where the est/se = 999.000, per Mplus convention). Default to \code{FALSE}.} \item{showNS}{Whether to display non-significant parameter estimates. Can be - \code{TRUE} or \code{FALSE}, or a numeric value (e.g., .10) that defines +\code{TRUE} or \code{FALSE}, or a numeric value (e.g., .10) that defines what p-value is filtered as non-significant.} \item{diffTest}{Whether to compute a chi-square difference test between the models. @@ -47,10 +47,10 @@ Use DIFFTEST in Mplus instead.} } \value{ A list containing the results of the comparison. Elements include - \code{summaries} with selected summary statistics for both models, - \code{parameters} listing equal and differing parameters as well as those - unique to each model, and, when \code{diffTest = TRUE}, a \code{diffTest} - element with the chi-square difference test. +\code{summaries} with selected summary statistics for both models, +\code{parameters} listing equal and differing parameters as well as those +unique to each model, and, when \code{diffTest = TRUE}, a \code{diffTest} +element with the chi-square difference test. } \description{ The \code{compareModels} function compares the output of two Mplus files and prints similarities and @@ -65,38 +65,38 @@ Model outputs to be compared should come from the \code{readModels} command. The \code{show} parameter can be one or more of the following, which can be passed as a vector, such as c("equal", "pdiff"). \describe{ - \item{show}{ - \describe{ - \item{"all"}{Display all available model comparison. Equivalent to - c("summaries", "equal", "diff", "pdiff", "unique").} - \item{"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")} - \item{"allsummaries"}{Prints a comparison of all summary statistics available in each model. May - generate a lot of output.} - \item{"equal"}{Print parameter estimates that are equal between models - (i.e., \code{<= equalityMargin["param"]})}. - \item{"diff"}{Print parameter estimates that are different between models - (i.e., \code{> equalityMargin["param"]})}. - \item{"pdiff"}{Print parameter estimates where the p-values differ between models - (i.e., \code{> equalityMargin["pvalue"]})}. - \item{"unique"}{Print parameter estimates that are unique to each model.} - } - } +\item{show}{ +\describe{ +\item{"all"}{Display all available model comparison. Equivalent to +c("summaries", "equal", "diff", "pdiff", "unique").} +\item{"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")} +\item{"allsummaries"}{Prints a comparison of all summary statistics available in each model. May +generate a lot of output.} +\item{"equal"}{Print parameter estimates that are equal between models +(i.e., \code{<= equalityMargin["param"]})}. +\item{"diff"}{Print parameter estimates that are different between models +(i.e., \code{> equalityMargin["param"]})}. +\item{"pdiff"}{Print parameter estimates where the p-values differ between models +(i.e., \code{> equalityMargin["pvalue"]})}. +\item{"unique"}{Print parameter estimates that are unique to each model.} +} +} } The \code{sort} parameter determines the order in which parameter estimates are displayed. The following options are available: \describe{ - \item{sort}{ - \describe{ - \item{"none"}{No sorting is performed, so parameters are output in the order presented in Mplus. (Default)} - \item{"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.} - \item{"alphabetical"}{Sort parameters in alphabetical order.} - \item{"maxDiff"}{Sort parameter output by the largest differences between models (high to low).} - } - } +\item{sort}{ +\describe{ +\item{"none"}{No sorting is performed, so parameters are output in the order presented in Mplus. (Default)} +\item{"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.} +\item{"alphabetical"}{Sort parameters in alphabetical order.} +\item{"maxDiff"}{Sort parameter output by the largest differences between models (high to low).} +} +} } } \examples{ diff --git a/man/confint.mplus.model.Rd b/man/confint.mplus.model.Rd index 7b95cf4..7b089f8 100644 --- a/man/confint.mplus.model.Rd +++ b/man/confint.mplus.model.Rd @@ -38,8 +38,8 @@ are used and all parameters are returned.} } \value{ A data frame of class \sQuote{mplus.model.cis}, or in - the case of multiple group models, a list of class \sQuote{mplus.model.cis}, - where each element of the list is a data frame of class \sQuote{mplus.model.cis}. +the case of multiple group models, a list of class \sQuote{mplus.model.cis}, +where each element of the list is a data frame of class \sQuote{mplus.model.cis}. } \description{ This is a method for returning the confidence of an mplus.model object. @@ -92,7 +92,7 @@ Other Mplus-Formatting: \code{\link{summary.mplusObject}()} } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \concept{Mplus-Formatting} \keyword{interface} diff --git a/man/convert_to_filelist.Rd b/man/convert_to_filelist.Rd index 267dbb6..1e11584 100644 --- a/man/convert_to_filelist.Rd +++ b/man/convert_to_filelist.Rd @@ -8,7 +8,7 @@ then locate all .inp files, and convert them to absolute paths} convert_to_filelist(target, filefilter = NULL, recursive = FALSE) } \arguments{ -\item{target}{a character vector where each element is a directory containing Mplus input files +\item{target}{a character vector where each element is a directory containing Mplus input files (.inp) to run OR a single .inp file to be run. Elements may be a full path, relative path, or a filename within the working directory.} diff --git a/man/createMixtures.Rd b/man/createMixtures.Rd index eeaee8a..4e73342 100644 --- a/man/createMixtures.Rd +++ b/man/createMixtures.Rd @@ -28,8 +28,8 @@ the syntax and data files.} \item{model_overall}{Character. Mplus syntax for the overall model (across classes).} -\item{model_class_specific}{Character vector. Mplus syntax for the -class-specific model(s) of one or more categorical latent variables. Each +\item{model_class_specific}{Character vector. Mplus syntax for the +class-specific model(s) of one or more categorical latent variables. Each element of \code{model_class_specific} is used as the class-specific syntax of a different categorical latent variable. This allows one to easily specify latent transition analyses (see second example). The character string @@ -39,7 +39,7 @@ constraints.} \item{rdata}{Data.frame. An R dataset to be used for the model.} -\item{usevariables}{Character vector, specifying the names of variables in +\item{usevariables}{Character vector, specifying the names of variables in the rdata object which should be included in the Mplus data file and model.} \item{OUTPUT}{Character. Syntax for Mplus' OUTPUT option. Highly diff --git a/man/createSyntax.Rd b/man/createSyntax.Rd index 1c5379e..098cb3a 100644 --- a/man/createSyntax.Rd +++ b/man/createSyntax.Rd @@ -23,7 +23,7 @@ Defaults to \code{FALSE}.} } \value{ A character string containing all the text for the Mplus - input file. +input file. } \description{ This function takes an object of class \code{mplusObject} and creates @@ -51,6 +51,6 @@ rm(example1) \code{\link{prepareMplusData}}, \code{\link{mplusModeler}} } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \keyword{interface} diff --git a/man/detectColumnNames.Rd b/man/detectColumnNames.Rd index 77e6051..e822058 100644 --- a/man/detectColumnNames.Rd +++ b/man/detectColumnNames.Rd @@ -15,7 +15,7 @@ detectColumnNames(filename, modelSection, sectionType = "model_results") } \value{ A list with elements for the directory, filename, - and absolute path. +and absolute path. } \description{ Helper function to detect model results columns. diff --git a/man/detectMplus.Rd b/man/detectMplus.Rd index 3a2728a..7e1e831 100644 --- a/man/detectMplus.Rd +++ b/man/detectMplus.Rd @@ -24,5 +24,5 @@ It does not require any arguments. ## detectMplus() } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } diff --git a/man/detectVariables.Rd b/man/detectVariables.Rd index 071de40..ded90fe 100644 --- a/man/detectVariables.Rd +++ b/man/detectVariables.Rd @@ -38,6 +38,6 @@ rm(example1, example2, example3) \code{\link{mplusModeler}}, \code{\link{mplusObject}} } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \keyword{internal} diff --git a/man/dot-convertData.Rd b/man/dot-convertData.Rd index c7e2fba..2cc3b28 100644 --- a/man/dot-convertData.Rd +++ b/man/dot-convertData.Rd @@ -11,8 +11,8 @@ } \value{ An error if it cannot be converted or - a matrix or data frame with all variables converted to - numeric or integer classes +a matrix or data frame with all variables converted to +numeric or integer classes } \description{ Primarily an internal utility function, for \code{prepareMplusData}. diff --git a/man/dot-mplusMultinomial.Rd b/man/dot-mplusMultinomial.Rd index 00920eb..f562252 100644 --- a/man/dot-mplusMultinomial.Rd +++ b/man/dot-mplusMultinomial.Rd @@ -81,5 +81,5 @@ tmpres3 <- MplusAutomation:::.mplusMultinomial( } } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } diff --git a/man/expandCmd.Rd b/man/expandCmd.Rd new file mode 100644 index 0000000..c80e998 --- /dev/null +++ b/man/expandCmd.Rd @@ -0,0 +1,57 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/mplusModel.R +\name{expandCmd} +\alias{expandCmd} +\title{Expand Mplus-style hyphenated variable ranges} +\usage{ +expandCmd(cmd, expand_numeric = FALSE) +} +\arguments{ +\item{cmd}{A single character string containing Mplus syntax to expand.} + +\item{expand_numeric}{Logical. If \code{TRUE}, expand pure numeric ranges +(e.g., \code{1-3} → \code{1 2 3}) in list-like contexts. Default: \code{FALSE}.} +} +\value{ +A character string with hyphenated ranges expanded to explicit +variable lists. +} +\description{ +Expands Mplus shorthand expressions that specify sequences of variables +using hyphenated ranges (e.g., \code{y1-y3}) into the full list of +variables (e.g., \code{y1 y2 y3}). This function also propagates suffixes +from the right-hand token (e.g., \code{@c}, \code{*c}, or bare \code{*}) +to every expanded variable (e.g., \code{y1-y3@1} → \code{y1@1 y2@1 y3@1}). +} +\details{ +By default, the function does \strong{not} expand pure numeric ranges (e.g., +\code{1-3}) to avoid confusion with arithmetic subtraction. If +\code{expand_numeric = TRUE}, such ranges will be expanded when they +appear in list-like contexts (whitespace/comma/semicolon/parentheses +boundaries) and the line does not contain an equals sign (to avoid +accidental expansion of arithmetic like \code{d = 1 - 3}). + +Hyphens in \code{MODEL CONSTRAINT} expressions such as +\code{a = b1-b2} are explicitly protected and left untouched. +} +\examples{ +expandCmd("y1-y3 y5-y6") +# "y1 y2 y3 y5 y6" + +expandCmd("BY y1-y3@0.5;") +# "BY y1@0.5 y2@0.5 y3@0.5;" + +expandCmd("z10-z12*2") +# "z10*2 z11*2 z12*2" + +expandCmd("MODEL CONSTRAINT: a = b1-b2;") +# "MODEL CONSTRAINT: a = b1-b2;" (unchanged) + +expandCmd("1 - 3", expand_numeric = TRUE) +# "1 2 3" + +expandCmd("d = 1 - 3;", expand_numeric = TRUE) +# "d = 1 - 3;" (unchanged because of '=') + +} +\keyword{internal} diff --git a/man/extract.Rd b/man/extract.Rd index 4699a0d..22efc38 100644 --- a/man/extract.Rd +++ b/man/extract.Rd @@ -40,7 +40,7 @@ coefficient names for LaTeX. Defaults to \code{FALSE}.} } \value{ A \code{texreg} object, or for multiple group models, - a list of \code{texreg} objects. +a list of \code{texreg} objects. } \description{ This is a method for extracting output in a format @@ -94,7 +94,7 @@ Other Mplus-Formatting: \code{\link{summary.mplusObject}()} } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \concept{Mplus-Formatting} \keyword{interface} diff --git a/man/extractModIndices.Rd b/man/extractModIndices.Rd index fbaa396..abe343c 100644 --- a/man/extractModIndices.Rd +++ b/man/extractModIndices.Rd @@ -23,21 +23,21 @@ details about regular expression syntax.} } \value{ If \code{target} is a single file, a data.frame - containing modification results for the target output file will be - returned. If \code{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 \code{data.frame} containing - the MODEL MODIFICATION INDICES section of \code{outfile}. Variables include - \item{modV1}{The first variable in the pair to be freed according to the M.I.} - \item{operator}{The suggested relationship between \code{modV1} and \code{modV2} - (e.g., WITH for freeing the covariance between \code{modV1} and \code{modV2})} - \item{modV2}{The first variable in the pair to be freed according to the M.I.} - \item{MI}{The decrease in model chi-square if the specified relationship is freely estimated} - \item{EPC}{The expected parameter estimate between \code{modV1} and \code{modV2} if freed.} - \item{Std_EPC}{The EPC value standardized using the variances of the continuous latent variables.} - \item{StdYX_EPC}{The EPC value standardized using the variances of the continuous latent - variables as well as the variances of the background and/or outcome variables.} +containing modification results for the target output file will be +returned. If \code{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 \code{data.frame} containing +the MODEL MODIFICATION INDICES section of \code{outfile}. Variables include +\item{modV1}{The first variable in the pair to be freed according to the M.I.} +\item{operator}{The suggested relationship between \code{modV1} and \code{modV2} +(e.g., WITH for freeing the covariance between \code{modV1} and \code{modV2})} +\item{modV2}{The first variable in the pair to be freed according to the M.I.} +\item{MI}{The decrease in model chi-square if the specified relationship is freely estimated} +\item{EPC}{The expected parameter estimate between \code{modV1} and \code{modV2} if freed.} +\item{Std_EPC}{The EPC value standardized using the variances of the continuous latent variables.} +\item{StdYX_EPC}{The EPC value standardized using the variances of the continuous latent +variables as well as the variances of the background and/or outcome variables.} } \description{ Extracts the model modification indices from the MODEL MODIFICATION INDICES section of one diff --git a/man/extractModelParameters.Rd b/man/extractModelParameters.Rd index 76988a5..eabe100 100644 --- a/man/extractModelParameters.Rd +++ b/man/extractModelParameters.Rd @@ -71,18 +71,18 @@ a different set of variables, including some of the above, as well as \item{population_sd}{Standard deviation of parameter value in population across replications.} \item{average_se}{Average standard error of estimated parameter value across replications.} \item{mse}{Mean squared error.} -\item{cover_95}{Proportion of replications whose 95\% confidence interval for the parameter includes the population value.} +\item{cover_95}{Proportion of replications whose 95\\% confidence interval for the parameter includes the population value.} \item{pct_sig_coef}{Proportion of replications for which the two-tailed significance test of the parameter is significant (p < .05).} In the case of confidence interval output (OUTPUT:CINTERVAL), the list element \code{ci.unstandardized} will contain a different set of variables, including some of the above, as well as -\item{low.5}{Lower 0.5\% CI estimate.} -\item{low2.5}{Lower 2.5\% CI estimate.} -\item{low5}{Lower 5\% CI estimate.} +\item{low.5}{Lower 0.5\\% CI estimate.} +\item{low2.5}{Lower 2.5\\% CI estimate.} +\item{low5}{Lower 5\\% CI estimate.} \item{est}{Parameter estimate value.} -\item{up5}{Upper 5\% (i.e., 95\%) CI estimate.} -\item{up2.5}{Upper 2.5\% (i.e., 97.5\%) CI estimate.} -\item{up.5}{Upper 0.5\% (i.e., 99.5\%) CI estimate.} +\item{up5}{Upper 5\\% (i.e., 95\\%) CI estimate.} +\item{up2.5}{Upper 2.5\\% (i.e., 97.5\\%) CI estimate.} +\item{up.5}{Upper 0.5\\% (i.e., 99.5\\%) CI estimate.} If the model contains multiple latent classes, an additional variable, \code{LatentClass}, will be included, specifying the latent class number. Also, the Categorical Latent Variables section diff --git a/man/extractModelSummaries.Rd b/man/extractModelSummaries.Rd index 36da3ae..35d9efa 100644 --- a/man/extractModelSummaries.Rd +++ b/man/extractModelSummaries.Rd @@ -36,15 +36,15 @@ The \code{data.frame} contains some of the following variables (depends on model \item{CFI}{Confirmatory Fit Index} \item{TLI}{Tucker-Lewis Index} \item{RMSEA_Estimate}{Point estimate of root mean squared error of approximation} -\item{RMSEA_90CI_LB}{Lower bound of the 90\% Confidence Interval around the RMSEA estimate.} -\item{RMSEA_90CI_UB}{Upper bound of the 90\% Confidence Interval around the RMSEA estimate.} +\item{RMSEA_90CI_LB}{Lower bound of the 90\\% Confidence Interval around the RMSEA estimate.} +\item{RMSEA_90CI_UB}{Upper bound of the 90\\% Confidence Interval around the RMSEA estimate.} \item{RMSEA_pLT05}{Probability that the RMSEA estimate falls below .05, indicating good fit.} \item{ChiSqM_Value}{Model chi-squared value} \item{ChiSqM_DF}{Model chi-squared degrees of freedom} \item{ChiSqM_PValue}{Model chi-squared p value} \item{ChiSqM_ScalingCorrection}{H0 Scaling Correction Factor} -\item{ObsRepChiSqDiff_95CI_LB}{Lower bound of 95\% confidence interval for the difference between observed and replicated chi-square values} -\item{ObsRepChiSqDiff_95CI_UB}{Upper bound of 95\% confidence interval for the difference between observed and replicated chi-square values} +\item{ObsRepChiSqDiff_95CI_LB}{Lower bound of 95\\% confidence interval for the difference between observed and replicated chi-square values} +\item{ObsRepChiSqDiff_95CI_UB}{Upper bound of 95\\% confidence interval for the difference between observed and replicated chi-square values} \item{PostPred_PValue}{Posterior predictive p-value} \item{PriorPostPred_PValue}{Prior Posterior Predictive P-Value} \item{BLRT_RequestedDraws}{Number of requested bootstrap draws for TECH14.} diff --git a/man/extractWarningsErrors_1file.Rd b/man/extractWarningsErrors_1file.Rd index 7f52631..0549fbd 100644 --- a/man/extractWarningsErrors_1file.Rd +++ b/man/extractWarningsErrors_1file.Rd @@ -15,8 +15,8 @@ extractWarningsErrors_1file(outfiletext, filename, input) } \value{ A list with two elements - \item{errors}{Mplus Errors} - \item{warnings}{Mplus Warnings} +\item{errors}{Mplus Errors} +\item{warnings}{Mplus Warnings} } \description{ Helper function diff --git a/man/friendlyGregexpr.Rd b/man/friendlyGregexpr.Rd index 10377d9..707966a 100644 --- a/man/friendlyGregexpr.Rd +++ b/man/friendlyGregexpr.Rd @@ -15,7 +15,7 @@ friendlyGregexpr(pattern, charvector, perl = TRUE, include_tag = TRUE) regular expressions. Defaults to \code{TRUE}.} \item{include_tag}{if TRUE, return the match as a character string. This is the default, but -setting to `FALSE` is a bit faster} +setting to \code{FALSE} is a bit faster} } \value{ A \code{data.frame} diff --git a/man/getSavedata_Fileinfo.Rd b/man/getSavedata_Fileinfo.Rd index e73a277..ae7a0a0 100644 --- a/man/getSavedata_Fileinfo.Rd +++ b/man/getSavedata_Fileinfo.Rd @@ -18,7 +18,7 @@ Returns a list of SAVEDATA file information that includes: \item{fileVarFormats}{A character vector containing the Fortran-style formats of variables in the dataset.} \item{fileVarWidths}{A numeric vector containing the widths of variables in the dataset (which is stored in fixed-width format).} \item{bayesFile}{The name of the BPARAMETERS file containing draws from the posterior distribution created by - the Mplus SAVEDATA BPARAMETERS command.} +the Mplus SAVEDATA BPARAMETERS command.} \item{bayesVarNames}{A character vector containing the names of variables in the BPARAMETERS dataset.} \item{tech3File}{A character vector of the tech 3 output.} \item{tech4File}{A character vector of the tech 4 output.} diff --git a/man/get_job_status.Rd b/man/get_job_status.Rd index 63da659..d13f22e 100644 --- a/man/get_job_status.Rd +++ b/man/get_job_status.Rd @@ -24,7 +24,7 @@ This function checks the status of one or more compute jobs } \details{ Note that for the \code{scheduler} argument, "torque" and "qsub" are the same; - "slurm" and "sbatch" are the same, and "sh" and "local" are the same. +"slurm" and "sbatch" are the same, and "sh" and "local" are the same. } \examples{ \dontrun{ diff --git a/man/htmlout.Rd b/man/htmlout.Rd index 4c9b115..7287ef8 100644 --- a/man/htmlout.Rd +++ b/man/htmlout.Rd @@ -11,7 +11,7 @@ htmlout(url) } \value{ A character string that is the filename where the output file was written. - Always a temp file in a temp directory. +Always a temp file in a temp directory. } \description{ This is an internal utility function to help with testing MplusAutomation. @@ -26,6 +26,6 @@ for testing. MplusAutomation:::htmlout("https://statmodel.com/usersguide/chap3/ex3.1.html") } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \keyword{internal} diff --git a/man/l_getSavedata_Fileinfo.Rd b/man/l_getSavedata_Fileinfo.Rd index 70162ad..cc104e0 100644 --- a/man/l_getSavedata_Fileinfo.Rd +++ b/man/l_getSavedata_Fileinfo.Rd @@ -19,7 +19,7 @@ A list that includes: \item{fileVarFormats}{A character vector containing the Fortran-style formats of variables in the dataset.} \item{fileVarWidths}{A numeric vector containing the widths of variables in the dataset (which is stored in fixed-width format).} \item{bayesFile}{The name of the BPARAMETERS file containing draws from the posterior distribution created by - the Mplus SAVEDATA BPARAMETERS command.} +the Mplus SAVEDATA BPARAMETERS command.} \item{bayesVarNames}{A character vector containing the names of variables in the BPARAMETERS dataset.} \item{tech3File}{A character vector of the tech 3 output.} \item{tech4File}{A character vector of the tech 4 output.} diff --git a/man/lcademo.Rd b/man/lcademo.Rd index 469deb7..2c760fe 100644 --- a/man/lcademo.Rd +++ b/man/lcademo.Rd @@ -7,17 +7,17 @@ \format{ A list containing 11 elements. \describe{ - \item{Data}{2 Class LCA data simulated using Mplus} - \item{CFA}{Mplus output file for CFA} - \item{LCA2}{Mplus output file for 2 class LCA} - \item{LCA3}{Mplus output file for 3 class LCA} - \item{LCA4}{Mplus output file for 4 class LCA} - \item{LCA5}{Mplus output file for 5 class LCA} - \item{CFAGH5}{GH5 file for CFA} - \item{LCA2GH5}{GH5 file for 2 class LCA} - \item{LCA3GH5}{GH5 file for 3 class LCA} - \item{LCA4GH5}{GH5 file for 4 class LCA} - \item{LCA5GH5}{GH5 file for 5 class LCA} +\item{Data}{2 Class LCA data simulated using Mplus} +\item{CFA}{Mplus output file for CFA} +\item{LCA2}{Mplus output file for 2 class LCA} +\item{LCA3}{Mplus output file for 3 class LCA} +\item{LCA4}{Mplus output file for 4 class LCA} +\item{LCA5}{Mplus output file for 5 class LCA} +\item{CFAGH5}{GH5 file for CFA} +\item{LCA2GH5}{GH5 file for 2 class LCA} +\item{LCA3GH5}{GH5 file for 3 class LCA} +\item{LCA4GH5}{GH5 file for 4 class LCA} +\item{LCA5GH5}{GH5 file for 5 class LCA} } } \usage{ diff --git a/man/mplus.traceplot.Rd b/man/mplus.traceplot.Rd index bc03448..586e691 100644 --- a/man/mplus.traceplot.Rd +++ b/man/mplus.traceplot.Rd @@ -19,7 +19,7 @@ The unstandardized estimates all begin with "Parameter" in the Mplus gh5 output. } \value{ No value is returned by this function. - Called for the side effect of displaying an MCMC chains traceplot. +Called for the side effect of displaying an MCMC chains traceplot. } \description{ Displays a traceplot of the MCMC draws from the poster distribution of each parameter estimate for a Bayesian Mplus model. @@ -33,8 +33,8 @@ in the model. } \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. +element of the mplus.model object. This requires that the posterior draws +be saved using SAVEDATA: BPARAMETERS syntax. See example below. } \examples{ \dontrun{ diff --git a/man/mplusGLM.Rd b/man/mplusGLM.Rd index 994bdc2..061ef9e 100644 --- a/man/mplusGLM.Rd +++ b/man/mplusGLM.Rd @@ -59,5 +59,5 @@ test <- mplusGLM(y ~ x1 + x2 + x3, data = tmpd) } } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } diff --git a/man/mplusModel.Rd b/man/mplusModel.Rd index 2bab45d..c5c168a 100644 --- a/man/mplusModel.Rd +++ b/man/mplusModel.Rd @@ -19,12 +19,12 @@ mplusModel( \item{inp_file}{the location of .inp file for this model} -\item{read}{If TRUE and the .out file already exists, read the contents of the .out file using `readModels`} +\item{read}{If TRUE and the .out file already exists, read the contents of the .out file using \code{readModels}} -\item{Mplus_command}{The location of the Mplus executable to run. If NULL, use `detectMplus()`} +\item{Mplus_command}{The location of the Mplus executable to run. If NULL, use \code{detectMplus()}} } \value{ -a `mplusModel_r6` object containing information about the model +a \code{mplusModel_r6} object containing information about the model } \description{ Create an mplusModel object for a given model diff --git a/man/mplusModel_r6.Rd b/man/mplusModel_r6.Rd index 1c7737a..4f53b0e 100644 --- a/man/mplusModel_r6.Rd +++ b/man/mplusModel_r6.Rd @@ -2,17 +2,17 @@ % Please edit documentation in R/mplusModel.R \name{mplusModel_r6} \alias{mplusModel_r6} -\title{An R6 class for a single Mplus model} +\title{mplusModel R6 class} \description{ -An R6 class for a single Mplus model - An R6 class for a single Mplus model } \details{ -Wrapped by `mplusModel` - Note that this R6 class deliberately uses unlockBinding to populate private fields after the object is instantiated. - This allows the model outputs to be added to the relevant sections of the object while keeping the fields private. +Wrapped by \code{mplusModel} +} +\section{Active bindings (from \code{readModels()})}{ + } + \keyword{internal} \section{Active bindings}{ \if{html}{\out{
}} @@ -31,15 +31,67 @@ Wrapped by `mplusModel` \item{\code{syntax}}{the Mplus syntax for this model as a character vector} -\item{\code{input}}{Parsed Mplus input sections (read-only)} +\item{\code{input}}{Read-only accessor for the \code{input} section returned by \code{readModels()}.} + +\item{\code{warnings}}{Read-only accessor for the \code{warnings} section returned by \code{readModels()}.} + +\item{\code{errors}}{Read-only accessor for the \code{errors} section returned by \code{readModels()}.} + +\item{\code{data_summary}}{Read-only accessor for the \code{data_summary} section returned by \code{readModels()}.} + +\item{\code{sampstat}}{Read-only accessor for the \code{sampstat} section returned by \code{readModels()}.} + +\item{\code{covariance_coverage}}{Read-only accessor for the \code{covariance_coverage} section returned by \code{readModels()}.} + +\item{\code{summaries}}{Read-only accessor for the \code{summaries} section returned by \code{readModels()}.} + +\item{\code{invariance_testing}}{Read-only accessor for the \code{invariance_testing} section returned by \code{readModels()}.} + +\item{\code{parameters}}{Read-only accessor for the \code{parameters} section returned by \code{readModels()}.} + +\item{\code{class_counts}}{Read-only accessor for the \code{class_counts} section returned by \code{readModels()}.} + +\item{\code{indirect}}{Read-only accessor for the \code{indirect} section returned by \code{readModels()}.} + +\item{\code{mod_indices}}{Read-only accessor for the \code{mod_indices} section returned by \code{readModels()}.} + +\item{\code{residuals}}{Read-only accessor for the \code{residuals} section returned by \code{readModels()}.} + +\item{\code{savedata}}{Read-only accessor for the \code{savedata} section returned by \code{readModels()}.} + +\item{\code{savedata_info}}{Read-only accessor for the \code{savedata_info} section returned by \code{readModels()}.} + +\item{\code{bparameters}}{Read-only accessor for the \code{bparameters} section returned by \code{readModels()}.} + +\item{\code{tech1}}{Read-only accessor for the \code{tech1} section returned by \code{readModels()}.} + +\item{\code{tech3}}{Read-only accessor for the \code{tech3} section returned by \code{readModels()}.} + +\item{\code{tech4}}{Read-only accessor for the \code{tech4} section returned by \code{readModels()}.} + +\item{\code{tech7}}{Read-only accessor for the \code{tech7} section returned by \code{readModels()}.} + +\item{\code{tech8}}{Read-only accessor for the \code{tech8} section returned by \code{readModels()}.} + +\item{\code{tech9}}{Read-only accessor for the \code{tech9} section returned by \code{readModels()}.} + +\item{\code{tech10}}{Read-only accessor for the \code{tech10} section returned by \code{readModels()}.} + +\item{\code{tech12}}{Read-only accessor for the \code{tech12} section returned by \code{readModels()}.} + +\item{\code{tech15}}{Read-only accessor for the \code{tech15} section returned by \code{readModels()}.} + +\item{\code{fac_score_stats}}{Read-only accessor for the \code{fac_score_stats} section returned by \code{readModels()}.} + +\item{\code{lcCondMeans}}{Read-only accessor for the \code{lcCondMeans} section returned by \code{readModels()}.} -\item{\code{warnings}}{Mplus warnings (read-only)} +\item{\code{r3step}}{Read-only accessor for the \code{r3step} section returned by \code{readModels()}.} -\item{\code{parameters}}{Parameter estimates (read-only)} +\item{\code{gh5}}{Read-only accessor for the \code{gh5} section returned by \code{readModels()}.} -\item{\code{summaries}}{Model summaries/statistics (read-only)} +\item{\code{h5results}}{Read-only accessor for the \code{h5results} section returned by \code{readModels()}.} -\item{\code{savedata}}{Data produced by SAVEDATA (read-only)} +\item{\code{output}}{Read-only accessor for the \code{output} section returned by \code{readModels()}.} } \if{html}{\out{
}} } @@ -79,9 +131,9 @@ generate an mplusModel_r6 object \item{\code{inp_file}}{the location of .inp file for this model} -\item{\code{read}}{If TRUE and the .out file already exists, read the contents of the .out file using `readModels`} +\item{\code{read}}{If TRUE and the .out file already exists, read the contents of the .out file using \code{readModels}} -\item{\code{Mplus_command}}{N.B.: No need to pass this parameter for most users (has intelligent defaults). Allows the user to +\item{\code{Mplus_command}}{N.B.: No need to pass this parameter for most users (has intelligent defaults). Allows the user to specify the name/path of the Mplus executable to be used for running models. This covers situations where Mplus is not in the system's path, or where one wants to test different versions of the Mplus program.} } @@ -92,7 +144,7 @@ is not in the system's path, or where one wants to test different versions of th \if{html}{\out{}} \if{latex}{\out{\hypertarget{method-mplusModel_r6-read}{}}} \subsection{Method \code{read()}}{ -read the results of an Mplus model from the .out file using `readModels` +read the results of an Mplus model from the .out file using \code{readModels} \subsection{Usage}{ \if{html}{\out{
}}\preformatted{mplusModel_r6$read(force = FALSE)}\if{html}{\out{
}} } @@ -100,7 +152,7 @@ read the results of an Mplus model from the .out file using `readModels` \subsection{Arguments}{ \if{html}{\out{
}} \describe{ -\item{\code{force}}{if `TRUE`, re-read the .out file even if was already previously loaded in to this object} +\item{\code{force}}{if \code{TRUE}, re-read the .out file even if was already previously loaded in to this object} } \if{html}{\out{
}} } @@ -117,11 +169,11 @@ write the .inp and .dat files for this model to the intended location \subsection{Arguments}{ \if{html}{\out{
}} \describe{ -\item{\code{overwrite}}{if `TRUE`, overwrite existing data. Default: `TRUE`.} +\item{\code{overwrite}}{if \code{TRUE}, overwrite existing data. Default: \code{TRUE}.} -\item{\code{quiet}}{if `TRUE`, do not produce messages about the outcome of this command (e.g., a message about overwriting existing data)} +\item{\code{quiet}}{if \code{TRUE}, do not produce messages about the outcome of this command (e.g., a message about overwriting existing data)} -\item{\code{...}}{additional arguments passed to `prepareMplusData`} +\item{\code{...}}{additional arguments passed to \code{prepareMplusData}} } \if{html}{\out{
}} } @@ -138,11 +190,11 @@ write the .inp and .dat files for this model to the intended location \subsection{Arguments}{ \if{html}{\out{
}} \describe{ -\item{\code{overwrite}}{if `TRUE`, overwrite existing data. Default: `TRUE`.} +\item{\code{overwrite}}{if \code{TRUE}, overwrite existing data. Default: \code{TRUE}.} -\item{\code{inp_file}}{The location of the input file to write. If NULL (default), use the `$inp_file` of this object.} +\item{\code{inp_file}}{The location of the input file to write. If NULL (default), use the \verb{$inp_file} of this object.} -\item{\code{quiet}}{if `TRUE`, do not produce messages about the outcome of this command (e.g., a message about overwriting existing data)} +\item{\code{quiet}}{if \code{TRUE}, do not produce messages about the outcome of this command (e.g., a message about overwriting existing data)} } \if{html}{\out{
}} } @@ -151,7 +203,7 @@ write the .inp and .dat files for this model to the intended location \if{html}{\out{}} \if{latex}{\out{\hypertarget{method-mplusModel_r6-submit}{}}} \subsection{Method \code{submit()}}{ -submit this model for estimation on an HPC using `submitModels` +submit this model for estimation on an HPC using \code{submitModels} \subsection{Usage}{ \if{html}{\out{
}}\preformatted{mplusModel_r6$submit(replaceOutfile = "modifiedDate", ...)}\if{html}{\out{
}} } @@ -159,11 +211,11 @@ submit this model for estimation on an HPC using `submitModels` \subsection{Arguments}{ \if{html}{\out{
}} \describe{ -\item{\code{replaceOutfile}}{Currently supports three settings: “always”, which runs all models, regardless of whether an output file for the model exists; +\item{\code{replaceOutfile}}{Currently supports three settings: “always”, which runs all models, regardless of whether an output file for the model exists; “never”, which does not run any model that has an existing output file; and “modifiedDate”, which only runs a model if the modified date for the input file is more recent than the output file modified date (implying there have been updates to the model).} -\item{\code{...}}{additional arguments passed to `submitModels`} +\item{\code{...}}{additional arguments passed to \code{submitModels}} } \if{html}{\out{
}} } @@ -172,7 +224,7 @@ file is more recent than the output file modified date (implying there have been \if{html}{\out{}} \if{latex}{\out{\hypertarget{method-mplusModel_r6-run}{}}} \subsection{Method \code{run()}}{ -run this model locally using `runModels` +run this model locally using \code{runModels} \subsection{Usage}{ \if{html}{\out{
}}\preformatted{mplusModel_r6$run(replaceOutfile = "modifiedDate", ...)}\if{html}{\out{
}} } @@ -180,11 +232,11 @@ run this model locally using `runModels` \subsection{Arguments}{ \if{html}{\out{
}} \describe{ -\item{\code{replaceOutfile}}{Currently supports three settings: “always”, which runs all models, regardless of whether an output file for the model exists; +\item{\code{replaceOutfile}}{Currently supports three settings: “always”, which runs all models, regardless of whether an output file for the model exists; “never”, which does not run any model that has an existing output file; and “modifiedDate”, which only runs a model if the modified date for the input file is more recent than the output file modified date (implying there have been updates to the model).} -\item{\code{...}}{additional arguments passed to `runModels`} +\item{\code{...}}{additional arguments passed to \code{runModels}} } \if{html}{\out{
}} } diff --git a/man/mplusModeler.Rd b/man/mplusModeler.Rd index 62fad4e..e7265f7 100644 --- a/man/mplusModeler.Rd +++ b/man/mplusModeler.Rd @@ -69,13 +69,13 @@ Passed on to control behavior of \code{\link{runModels}}. Defaults to \code{TRUE } \value{ An Mplus model object, with results. - If \code{run = 1}, returns an invisible list of results from the run of - the Mplus model (see \code{\link[MplusAutomation]{readModels}} from the - MplusAutomation package). If \code{run = 0}, the function returns a list - with two elements, \sQuote{model} and \sQuote{boot} that are both \code{NULL}. - if \code{run >= 1},returns a list with two elements, \sQuote{model} and \sQuote{boot} - containing the regular Mplus model output and the boot object, respectively. - In all cases, the Mplus data file and input files are created. +If \code{run = 1}, returns an invisible list of results from the run of +the Mplus model (see \code{\link[MplusAutomation]{readModels}} from the +MplusAutomation package). If \code{run = 0}, the function returns a list +with two elements, \sQuote{model} and \sQuote{boot} that are both \code{NULL}. +if \code{run >= 1},returns a list with two elements, \sQuote{model} and \sQuote{boot} +containing the regular Mplus model output and the boot object, respectively. +In all cases, the Mplus data file and input files are created. } \description{ This is a convenience wrapper to automate many of the @@ -337,5 +337,5 @@ testimp2 <- mplusModeler( \code{\link{runModels}} and \code{\link{readModels}} } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } diff --git a/man/mplusObject.Rd b/man/mplusObject.Rd index 97c1a29..0d4176a 100644 --- a/man/mplusObject.Rd +++ b/man/mplusObject.Rd @@ -159,6 +159,6 @@ rm(example4) \code{\link{mplusModeler}} } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \keyword{interface} diff --git a/man/mplusRcov.Rd b/man/mplusRcov.Rd index 15ac4f4..a2d2483 100644 --- a/man/mplusRcov.Rd +++ b/man/mplusRcov.Rd @@ -33,14 +33,14 @@ Defaults to \code{FALSE}.} } \value{ A named character vector of class \sQuote{MplusRstructure} with four elements: - \item{all}{A character string collapsing all other sections.} - \item{Variances}{A character string containing all of the variances.} - \item{Covariances}{A character string containing all of the - covariances, properly labelled to allow constraints and the - autoregressive residual covariance structure.} - \item{Constraints}{A character string containing the \sQuote{MODEL CONSTRAINT} - section and code needed to parameterize the residual covariance structure - as autoregressive.} +\item{all}{A character string collapsing all other sections.} +\item{Variances}{A character string containing all of the variances.} +\item{Covariances}{A character string containing all of the +covariances, properly labelled to allow constraints and the +autoregressive residual covariance structure.} +\item{Constraints}{A character string containing the \sQuote{MODEL CONSTRAINT} +section and code needed to parameterize the residual covariance structure +as autoregressive.} } \description{ This function makes it easy to write the Mplus syntax for various @@ -52,12 +52,12 @@ the residual variance, \eqn{\sigma^{2}_{e}}{s^2}. 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. \tabular{llllll}{ - \tab t1 \tab t2 \tab t3 \tab \ldots \tab tn \cr - t1 \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \tab \ldots \tab \cr - t2 \tab 0 \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \ldots \tab \cr - t3 \tab 0 \tab 0 \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \ldots \tab \cr - \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \cr - tn \tab 0 \tab 0 \tab 0 \tab \ldots \tab \eqn{\sigma^{2}_{e}}{s^2} \cr +\tab t1 \tab t2 \tab t3 \tab \ldots \tab tn \cr +t1 \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \tab \ldots \tab \cr +t2 \tab 0 \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \ldots \tab \cr +t3 \tab 0 \tab 0 \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \ldots \tab \cr +\ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \cr +tn \tab 0 \tab 0 \tab 0 \tab \ldots \tab \eqn{\sigma^{2}_{e}}{s^2} \cr } The \strong{heterogenous} residual covariance structure estimates @@ -65,12 +65,12 @@ The \strong{heterogenous} residual covariance structure estimates A unique residual variance is estimated for every variable. All covariances are assumed to be zero. The structure is represented in this table. \tabular{llllll}{ - \tab t1 \tab t2 \tab t3 \tab \ldots \tab tn \cr - t1 \tab \eqn{\sigma^{2}_{e1}}{s1^2} \tab \tab \tab \ldots \tab \cr - t2 \tab 0 \tab \eqn{\sigma^{2}_{e2}}{s2^2} \tab \tab \ldots \tab \cr - t3 \tab 0 \tab 0 \tab \eqn{\sigma^{2}_{e3}}{s3^2} \tab \ldots \tab \cr - \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \cr - tn \tab 0 \tab 0 \tab 0 \tab \ldots \tab \eqn{\sigma^{2}_{en}}{sn^2} \cr +\tab t1 \tab t2 \tab t3 \tab \ldots \tab tn \cr +t1 \tab \eqn{\sigma^{2}_{e1}}{s1^2} \tab \tab \tab \ldots \tab \cr +t2 \tab 0 \tab \eqn{\sigma^{2}_{e2}}{s2^2} \tab \tab \ldots \tab \cr +t3 \tab 0 \tab 0 \tab \eqn{\sigma^{2}_{e3}}{s3^2} \tab \ldots \tab \cr +\ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \cr +tn \tab 0 \tab 0 \tab 0 \tab \ldots \tab \eqn{\sigma^{2}_{en}}{sn^2} \cr } The \strong{compound symmetric} residual covariance structure estimates @@ -79,12 +79,12 @@ 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. \tabular{llllll}{ - \tab t1 \tab t2 \tab t3 \tab \ldots \tab tn \cr - t1 \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \tab \ldots \tab \cr - t2 \tab \eqn{\rho}{rho} \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \ldots \tab \cr - t3 \tab \eqn{\rho}{rho} \tab \eqn{\rho}{rho} \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \ldots \tab \cr - \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \cr - tn \tab \eqn{\rho}{rho} \tab \eqn{\rho}{rho} \tab \eqn{\rho}{rho} \tab \ldots \tab \eqn{\sigma^{2}_{e}}{s^2} \cr +\tab t1 \tab t2 \tab t3 \tab \ldots \tab tn \cr +t1 \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \tab \ldots \tab \cr +t2 \tab \eqn{\rho}{rho} \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \ldots \tab \cr +t3 \tab \eqn{\rho}{rho} \tab \eqn{\rho}{rho} \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \ldots \tab \cr +\ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \cr +tn \tab \eqn{\rho}{rho} \tab \eqn{\rho}{rho} \tab \eqn{\rho}{rho} \tab \ldots \tab \eqn{\sigma^{2}_{e}}{s^2} \cr } The \strong{toeplitz} residual covariance structure estimates @@ -94,12 +94,12 @@ 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. \tabular{llllll}{ - \tab t1 \tab t2 \tab t3 \tab \ldots \tab tn \cr - t1 \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \tab \ldots \tab \cr - t2 \tab \eqn{\rho}{rho} \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \ldots \tab \cr - t3 \tab \eqn{\rho_{2}}{rho2} \tab \eqn{\rho}{rho} \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \ldots \tab \cr - \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \cr - tn \tab \eqn{\rho_{n}}{rhon} \tab \eqn{\rho_{n - 1}}{rho(n - 1)} \tab \eqn{\rho_{n - 2}}{rho(n - 2)} \tab \ldots \tab \eqn{\sigma^{2}_{e}}{s^2} \cr +\tab t1 \tab t2 \tab t3 \tab \ldots \tab tn \cr +t1 \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \tab \ldots \tab \cr +t2 \tab \eqn{\rho}{rho} \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \ldots \tab \cr +t3 \tab \eqn{\rho_{2}}{rho2} \tab \eqn{\rho}{rho} \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \ldots \tab \cr +\ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \cr +tn \tab \eqn{\rho_{n}}{rhon} \tab \eqn{\rho_{n - 1}}{rho(n - 1)} \tab \eqn{\rho_{n - 2}}{rho(n - 2)} \tab \ldots \tab \eqn{\sigma^{2}_{e}}{s^2} \cr } The \strong{autoregressive} residual covariance structure has two parameters: @@ -111,12 +111,12 @@ 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 \eqn{\rho^2}{rho^2}. The structure is represented in this table. \tabular{llllll}{ - \tab t1 \tab t2 \tab t3 \tab \ldots \tab tn \cr - t1 \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \tab \ldots \tab \cr - t2 \tab \eqn{\rho}{rho} \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \ldots \tab \cr - t3 \tab \eqn{\rho^2}{rho^2} \tab \eqn{\rho}{rho} \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \ldots \tab \cr - \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \cr - tn \tab \eqn{\rho^{n-1}}{rho^(n-1)} \tab \eqn{\rho^{n-2}}{rho^(n-2)} \tab \eqn{\rho^{n-3}}{rho^(n-3)} \tab \ldots \tab \eqn{\sigma^{2}_{e}}{s^2} \cr +\tab t1 \tab t2 \tab t3 \tab \ldots \tab tn \cr +t1 \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \tab \ldots \tab \cr +t2 \tab \eqn{\rho}{rho} \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \tab \ldots \tab \cr +t3 \tab \eqn{\rho^2}{rho^2} \tab \eqn{\rho}{rho} \tab \eqn{\sigma^{2}_{e}}{s^2} \tab \ldots \tab \cr +\ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \cr +tn \tab \eqn{\rho^{n-1}}{rho^(n-1)} \tab \eqn{\rho^{n-2}}{rho^(n-2)} \tab \eqn{\rho^{n-3}}{rho^(n-3)} \tab \ldots \tab \eqn{\sigma^{2}_{e}}{s^2} \cr } Because structural equation models generally model covariance structures, the autoregressive residual structure must be parameterized in terms of @@ -136,12 +136,12 @@ constraints. However, in most cases, this results in an overparameterized model and is unestimable. The structure is represented in this table. \tabular{llllll}{ - \tab t1 \tab t2 \tab t3 \tab \ldots \tab tn \cr - t1 \tab \eqn{\sigma^{2}_{e1}}{s1^2} \tab \tab \tab \ldots \tab \cr - t2 \tab \eqn{\rho_{1}}{rho1} \tab \eqn{\sigma^{2}_{e2}}{s2^2} \tab \tab \ldots \tab \cr - t3 \tab \eqn{\rho_{2}}{rho2} \tab \eqn{\rho_{3}}{rho3} \tab \eqn{\sigma^{2}_{e3}}{s3^2} \tab \ldots \tab \cr - \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \cr - tn \tab \eqn{\rho_{5}}{rho5} \tab \eqn{\rho_{6}}{rho6} \tab \eqn{\rho_{7}}{rho7} \tab \ldots \tab \eqn{\sigma^{2}_{en}}{sn^2} \cr +\tab t1 \tab t2 \tab t3 \tab \ldots \tab tn \cr +t1 \tab \eqn{\sigma^{2}_{e1}}{s1^2} \tab \tab \tab \ldots \tab \cr +t2 \tab \eqn{\rho_{1}}{rho1} \tab \eqn{\sigma^{2}_{e2}}{s2^2} \tab \tab \ldots \tab \cr +t3 \tab \eqn{\rho_{2}}{rho2} \tab \eqn{\rho_{3}}{rho3} \tab \eqn{\sigma^{2}_{e3}}{s3^2} \tab \ldots \tab \cr +\ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \tab \ldots \cr +tn \tab \eqn{\rho_{5}}{rho5} \tab \eqn{\rho_{6}}{rho6} \tab \eqn{\rho_{7}}{rho7} \tab \ldots \tab \eqn{\sigma^{2}_{en}}{sn^2} \cr } } \examples{ @@ -164,6 +164,6 @@ mplusRcov(letters[1:4], "ar", "rho", "e", FALSE) mplusRcov(letters[1:4], "un", "rho", "e", FALSE) } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \keyword{interface} diff --git a/man/paramExtract.Rd b/man/paramExtract.Rd index f61a0ab..1679f69 100644 --- a/man/paramExtract.Rd +++ b/man/paramExtract.Rd @@ -67,6 +67,6 @@ the results returned from the \code{\link{readModels}} function. \code{\link{readModels}} } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \keyword{utils} diff --git a/man/parseMplus.Rd b/man/parseMplus.Rd index ad3a9c7..7d44758 100644 --- a/man/parseMplus.Rd +++ b/man/parseMplus.Rd @@ -14,7 +14,7 @@ lines that do not have them. Defaults to \code{FALSE}.} } \value{ a character vector containing the input text and - optionally added semicolons. +optionally added semicolons. } \description{ The function parses a character string containing Mplus code @@ -55,6 +55,6 @@ cat(parseMplus(test), file=stdout()) \code{\link{mplusModeler}} } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \keyword{utils} diff --git a/man/parseTags.Rd b/man/parseTags.Rd index d427f7b..a970a7f 100644 --- a/man/parseTags.Rd +++ b/man/parseTags.Rd @@ -15,9 +15,9 @@ parseTags(bodySection, initCollection) A list with three elements, where each list represents the location, start character, end character, tag type, etc. of each tag. \describe{ - \item{initTags}{initMatches} - \item{bodyTags}{bodyMatches} - \item{bodyText}{bodySection} +\item{initTags}{initMatches} +\item{bodyTags}{bodyMatches} +\item{bodyText}{bodySection} } } \description{ diff --git a/man/plot.mplusObject.Rd b/man/plot.mplusObject.Rd index 0309752..db5450d 100644 --- a/man/plot.mplusObject.Rd +++ b/man/plot.mplusObject.Rd @@ -48,6 +48,6 @@ unlink("Mplus Run Models.log") } } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \keyword{interface} diff --git a/man/plotGrowthMixtures.Rd b/man/plotGrowthMixtures.Rd index 9546d64..b556b93 100644 --- a/man/plotGrowthMixtures.Rd +++ b/man/plotGrowthMixtures.Rd @@ -43,7 +43,7 @@ raw data.} (transparancy) for the raw data. Minimum should be 0; lower maximum values of alpha can help reduce overplotting.} -\item{growth_variables}{Character vector. Indicate the names of the latent +\item{growth_variables}{Character vector. Indicate the names of the latent variables for the growth trajectory to plot. If NULL (default), all latent growth variables are used. Use this option to plot one trajectory when a model contains multiple latent growth trajectories.} diff --git a/man/plotLTA.Rd b/man/plotLTA.Rd index 60f419c..6dab2c0 100644 --- a/man/plotLTA.Rd +++ b/man/plotLTA.Rd @@ -17,13 +17,13 @@ plotLTA( function additionally requires the model to be a mixture model with multiple categorical latent variables.} -\item{node_stroke}{Integer. Base stroke thickness for nodes. Set to +\item{node_stroke}{Integer. Base stroke thickness for nodes. Set to \code{NULL} to give each node the same stroke thickness.} \item{max_edge_width}{Integer. Maximum width of edges.} -\item{node_labels}{Character vector, defaults to \code{"variable.class"}, -which labels each node by the name of the variable, and the number of the +\item{node_labels}{Character vector, defaults to \code{"variable.class"}, +which labels each node by the name of the variable, and the number of the class it represents. Set to \code{"class"} to display only class numbers, or provide a named character vector where the names correspond to original class labels, and the values correspond to their substitute values.} @@ -41,7 +41,7 @@ An object of class 'ggplot'. 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 +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. diff --git a/man/plotMixtureDensities.Rd b/man/plotMixtureDensities.Rd index c60ea31..b71ce36 100644 --- a/man/plotMixtureDensities.Rd +++ b/man/plotMixtureDensities.Rd @@ -32,10 +32,10 @@ subdivided amongst the classes).} the transparency of geom_density, so that classes with a small number of cases remain visible.} -\item{facet_labels}{Named character vector, the names of which should +\item{facet_labels}{Named character vector, the names of which should correspond to the facet labels one wishes to rename, and the values of which provide new names for these facets. For example, to rename variables, in the -example with the 'iris' data below, one could specify: +example with the 'iris' data below, one could specify: \code{facet_labels = c("Pet_leng" = "Petal length")}.} } \value{ @@ -52,10 +52,12 @@ posterior probability of being assigned to that class. 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 +\enumerate{ +\item 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. } +} \examples{ \dontrun{ results <- createMixtures(classes = 1:3, filename_stem = "iris", diff --git a/man/plotMixtures.Rd b/man/plotMixtures.Rd index 14a8cbf..35a43c3 100644 --- a/man/plotMixtures.Rd +++ b/man/plotMixtures.Rd @@ -31,7 +31,7 @@ headings included in the output). Defaults to c('Means', 'Intercepts').} \item{ci}{What confidence interval should the errorbars span? Defaults to -a 95\% confidence interval. Set to NULL to remove errorbars.} +a 95\\% confidence interval. Set to NULL to remove errorbars.} \item{bw}{Logical. Should the plot be black and white (for print), or color?} diff --git a/man/prepareMplusData.Rd b/man/prepareMplusData.Rd index ef5ca99..0e75a79 100644 --- a/man/prepareMplusData.Rd +++ b/man/prepareMplusData.Rd @@ -45,7 +45,7 @@ or a logical vector corresponding to the same.} \item{dummyCode}{An optional character vector of column names indicating categorical variables in the dataset that should be converted into dummy codes (using the \code{fastDummies} package). Note that one dummy -code is returned for *each level*, so no reference category is implied. +code is returned for \emph{each level}, so no reference category is implied. Thus, it is up to you to drop one of the dummy codes in the Mplus syntax to denote the reference category and avoid multicollinearity.} @@ -83,8 +83,8 @@ are located in the same folder, as is common for \code{Mplus}. Default: \code{FA } \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. +syntax. Primarily called for its side effect of creating Mplus +data files and optionally input files. } \description{ The \code{prepareMplusData} function converts an R data.frame diff --git a/man/print.MplusRstructure.Rd b/man/print.MplusRstructure.Rd index 91040d0..865f384 100644 --- a/man/print.MplusRstructure.Rd +++ b/man/print.MplusRstructure.Rd @@ -35,7 +35,7 @@ Other Mplus-Formatting: \code{\link{summary.mplusObject}()} } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \concept{Mplus-Formatting} \keyword{interface} diff --git a/man/readModels.Rd b/man/readModels.Rd index 5349b3a..962b2c9 100644 --- a/man/readModels.Rd +++ b/man/readModels.Rd @@ -44,36 +44,36 @@ A list with one mplus.model per file. Each mplus.model object is composed of elements containing major output sections, as detailed below. If \code{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: - \item{input}{Mplus input syntax parsed into a list by major section} - \item{warnings}{Syntax and estimation warnings as a list} - \item{errors}{Syntax and estimation errors as a list} - \item{data_summary}{Output of SUMMARY OF DATA section, including cluster sizes and ICCs} - \item{sampstat}{Sample statistics provided by OUTPUT: SAMPSTAT, if specified} - \item{covariance_coverage}{Covariance coverage matrix for checking missingness patterns} - \item{summaries}{Summary statistics from \code{extractModelSummaries}, having structure as specified by that function} - \item{parameters}{Model parameters from \code{extractModelParameters}, having structure as specified by that function} - \item{class_counts}{Latent class counts and proportions for models that include a categorical latent variable} - \item{indirect}{Output of MODEL INDIRECT if available in output. Contains \code{$overall} and \code{$specific} data.frames for each indirect effect section} - \item{mod_indices}{Model modification indices from \code{extractModIndices}, having structure as specified by that function} - \item{residuals}{a list containing relevant information from OUTPUT: RESIDUALS} - \item{savedata_info}{File information about SAVEDATA files related to this output} - \item{savedata}{SAVEDATA file as an R \code{data.frame}, as described in \code{getSavedata_Data}} - \item{bparameters}{an \code{mcmc.list} object containing the draws from the MCMC chains for a Bayesian model that uses the - SAVEDATA: BPARAMETERS command} - \item{tech1}{a list containing parameter specification and starting values from OUTPUT: TECH1} - \item{tech3}{a list containing parameter covariance and correlation matrices from OUTPUT: TECH3} - \item{tech4}{a list containing means, covariances, and correlations for latent variables from OUTPUT: TECH4} - \item{tech7}{a list containing sample statistics for each latent class from OUTPUT: TECH7} - \item{tech8}{a list containing optimization history of the model. Currently only supports potential scale reduction in BAYES. OUTPUT: TECH8} - \item{tech9}{a list containing warnings/errors from replication runs for MONTECARLO analyses from OUTPUT: TECH9} - \item{tech10}{a list containing model fit information from OUTPUT: TECH10} - \item{tech12}{a list containing observed versus estimated sample statistics for TYPE=MIXTURE analyses from OUTPUT: TECH12} - \item{fac_score_stats}{factor score mean, correlation, and covariance structure from SAMPLE STATISTICS FOR ESTIMATED FACTOR SCORES section} - \item{lcCondMeans}{conditional latent class means and pairwise comparisons, obtained using auxiliary(e) syntax in latent class models} - \item{r3step}{predictors of latent class membership using the 3-step procedure (R3STEP)} - \item{gh5}{a list containing data from the gh5 (graphics) file corresponding to this output. (Requires rhdf5 package)} - \item{h5results}{a list containing data from h5results file produced by Mplus v8.11+. (Requires rhdf5 package)} - \item{output}{The entire, raw output file.} +\item{input}{Mplus input syntax parsed into a list by major section} +\item{warnings}{Syntax and estimation warnings as a list} +\item{errors}{Syntax and estimation errors as a list} +\item{data_summary}{Output of SUMMARY OF DATA section, including cluster sizes and ICCs} +\item{sampstat}{Sample statistics provided by OUTPUT: SAMPSTAT, if specified} +\item{covariance_coverage}{Covariance coverage matrix for checking missingness patterns} +\item{summaries}{Summary statistics from \code{extractModelSummaries}, having structure as specified by that function} +\item{parameters}{Model parameters from \code{extractModelParameters}, having structure as specified by that function} +\item{class_counts}{Latent class counts and proportions for models that include a categorical latent variable} +\item{indirect}{Output of MODEL INDIRECT if available in output. Contains \code{$overall} and \code{$specific} data.frames for each indirect effect section} +\item{mod_indices}{Model modification indices from \code{extractModIndices}, having structure as specified by that function} +\item{residuals}{a list containing relevant information from OUTPUT: RESIDUALS} +\item{savedata_info}{File information about SAVEDATA files related to this output} +\item{savedata}{SAVEDATA file as an R \code{data.frame}, as described in \code{getSavedata_Data}} +\item{bparameters}{an \code{mcmc.list} object containing the draws from the MCMC chains for a Bayesian model that uses the +SAVEDATA: BPARAMETERS command} +\item{tech1}{a list containing parameter specification and starting values from OUTPUT: TECH1} +\item{tech3}{a list containing parameter covariance and correlation matrices from OUTPUT: TECH3} +\item{tech4}{a list containing means, covariances, and correlations for latent variables from OUTPUT: TECH4} +\item{tech7}{a list containing sample statistics for each latent class from OUTPUT: TECH7} +\item{tech8}{a list containing optimization history of the model. Currently only supports potential scale reduction in BAYES. OUTPUT: TECH8} +\item{tech9}{a list containing warnings/errors from replication runs for MONTECARLO analyses from OUTPUT: TECH9} +\item{tech10}{a list containing model fit information from OUTPUT: TECH10} +\item{tech12}{a list containing observed versus estimated sample statistics for TYPE=MIXTURE analyses from OUTPUT: TECH12} +\item{fac_score_stats}{factor score mean, correlation, and covariance structure from SAMPLE STATISTICS FOR ESTIMATED FACTOR SCORES section} +\item{lcCondMeans}{conditional latent class means and pairwise comparisons, obtained using auxiliary(e) syntax in latent class models} +\item{r3step}{predictors of latent class membership using the 3-step procedure (R3STEP)} +\item{gh5}{a list containing data from the gh5 (graphics) file corresponding to this output. (Requires rhdf5 package)} +\item{h5results}{a list containing data from h5results file produced by Mplus v8.11+. (Requires rhdf5 package)} +\item{output}{The entire, raw output file.} } \description{ Extracts information from one or more Mplus output files, including fit statistics and parameters. @@ -86,10 +86,10 @@ reduced set of output sections (especially to speed up the function when reading 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") +"parameters", "class_counts", "indirect", "mod_indices", "residuals", +"savedata", "bparameters", "tech1", "tech3", "tech4", "tech7", "tech8", +"tech9", "tech10", "tech12", "fac_score_stats", "lcCondMeans", "gh5", +"output") } \examples{ \dontrun{ diff --git a/man/rmVarWarnings.Rd b/man/rmVarWarnings.Rd index f64ca5e..6457617 100644 --- a/man/rmVarWarnings.Rd +++ b/man/rmVarWarnings.Rd @@ -13,9 +13,9 @@ for this function to work properly.} } \value{ Usually NULL. Called for the side effect of removing warnings in - Mplus output files. If \code{\link{file.access}} testing for write permissions - returns \code{FALSE}, a character string note that \code{rmVarWarnings} - could not run. +Mplus output files. If \code{\link{file.access}} testing for write permissions +returns \code{FALSE}, a character string note that \code{rmVarWarnings} +could not run. } \description{ This function is designed to remove warnings in Mplus output files @@ -35,6 +35,6 @@ when the \code{varwarnings = FALSE} argument is used. \code{\link{mplusModeler}} } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \keyword{internal} diff --git a/man/runModels.Rd b/man/runModels.Rd index c613131..4cf7348 100644 --- a/man/runModels.Rd +++ b/man/runModels.Rd @@ -18,7 +18,7 @@ runModels( ) } \arguments{ -\item{target}{a character vector where each element is a directory containing Mplus input files +\item{target}{a character vector where each element is a directory containing Mplus input files (.inp) to run OR a single .inp file to be run. Elements may be a full path, relative path, or a filename within the working directory. Defaults to the current working directory. Example: \dQuote{C:/Users/Michael/Mplus Runs}} diff --git a/man/showSummaryTable.Rd b/man/showSummaryTable.Rd index ce0e89c..3bfe9d6 100644 --- a/man/showSummaryTable.Rd +++ b/man/showSummaryTable.Rd @@ -41,8 +41,8 @@ but these are customizable using the \code{keepCols} and \code{dropCols} paramet } \note{ You must choose between \code{keepCols} and \code{dropCols} because - it is not sensible to use these together to include and exclude columns. - The function will error if you include both parameters. +it is not sensible to use these together to include and exclude columns. +The function will error if you include both parameters. } \examples{ # make me!!! diff --git a/man/splitFilePath.Rd b/man/splitFilePath.Rd index d66ce56..275954c 100644 --- a/man/splitFilePath.Rd +++ b/man/splitFilePath.Rd @@ -11,7 +11,7 @@ splitFilePath(filepath, normalize = FALSE) } \value{ A list with elements for the directory, filename, - and absolute path. +and absolute path. } \description{ This is a helper function to split path into path and filename. diff --git a/man/submitModels.Rd b/man/submitModels.Rd index bad0eb5..1f0e247 100644 --- a/man/submitModels.Rd +++ b/man/submitModels.Rd @@ -31,7 +31,7 @@ submitModels( ) } \arguments{ -\item{target}{a character vector where each element is a directory containing Mplus input files +\item{target}{a character vector where each element is a directory containing Mplus input files (.inp) to run OR a single .inp file to be run. Elements may be a full path, relative path, or a filename within the working directory. Defaults to the current working directory. Example: \dQuote{C:/Users/Michael/Mplus Runs}} @@ -57,25 +57,25 @@ or where one wants to test different versions of the Mplus program.} \item{quiet}{optional. If \code{FALSE}, show status messages in the console.} \item{scheduler}{Which scheduler to use for job submission. Options are 'qsub', 'torque', 'sbatch', 'slurm', 'local', or 'sh'. -The terms `'qsub'` and `'torque'` are aliases (where 'torque' submits via the qsub command). Likewise for 'sbatch' -and 'slurm'. If `'local'` or `'sh'` are specified, `submitModels` does not submit to any scheduler at all, +The terms \code{'qsub'} and \code{'torque'} are aliases (where 'torque' submits via the qsub command). Likewise for 'sbatch' +and 'slurm'. If \code{'local'} or \code{'sh'} are specified, \code{submitModels} does not submit to any scheduler at all, but instead executes the command locally via a shell script.} \item{sched_args}{A character vector of arguments to be included in the scheduling command. On TORQUE, these will typically begin with '-l' such as '-l wall_time=10:00:00'. These are added inside the submission script -for each model and are shared across all models. To add model-specific arguments, include `! #SBATCH` or -`! #PBS` lines inside the individual .inp files} +for each model and are shared across all models. To add model-specific arguments, include \verb{! #SBATCH} or +\verb{! #PBS} lines inside the individual .inp files} \item{env_variables}{A named character vector containing environment variables and their values to be passed -to the \code{script} at execution time. This is handled by the `-v` directive on TORQUE clusters and -by `--export` on Slurm clusters. The names of this vector are the environment variable names and +to the \code{script} at execution time. This is handled by the \code{-v} directive on TORQUE clusters and +by \code{--export} on Slurm clusters. The names of this vector are the environment variable names and the values of the vector are the environment variable values to be passed in. If you want to propagate the current value of an environment variable to the compute node at runtime, use NA as the value of the element in \code{env_variables}. See examples.} \item{export_all}{Whether to export all environment variables to the compute node at runtime. Default: FALSE} -\item{cores_per_model}{How many cpus/cores are requested for each model (can be overriden using `! BATCH` directives in .inp files). +\item{cores_per_model}{How many cpus/cores are requested for each model (can be overriden using \code{! BATCH} directives in .inp files). Default: 1.} \item{memgb_per_model}{amount of memory (RAM) requested for each model (in GB). Default: 8.} @@ -105,16 +105,16 @@ a number is provided, we will treat this as the number of minutes.} submission fails. Defaults to TRUE.} } \value{ -A data.frame recording details of the jobs submitted by `submitModels`. This can be passed to the `summary` function - or to `checkSubmission` to see the state of submitted jobs. +A data.frame recording details of the jobs submitted by \code{submitModels}. This can be passed to the \code{summary} function +or to \code{checkSubmission} to see the state of submitted jobs. } \description{ This function submits a group of Mplus models (.inp files) located within a single directory or nested within subdirectories. } \details{ -Note that if `fail_on_error` is `TRUE` and submission of one model fails, the submission loop will stop, rather than - submitting further models. +Note that if \code{fail_on_error} is \code{TRUE} and submission of one model fails, the submission loop will stop, rather than +submitting further models. } \examples{ \dontrun{ diff --git a/man/summary.mplusObject.Rd b/man/summary.mplusObject.Rd index 4d08777..375a225 100644 --- a/man/summary.mplusObject.Rd +++ b/man/summary.mplusObject.Rd @@ -54,7 +54,7 @@ Other Mplus-Formatting: \code{\link{print.MplusRstructure}()} } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \concept{Mplus-Formatting} \keyword{interface} diff --git a/man/torque_job_status.Rd b/man/torque_job_status.Rd index c63df2b..a4eb249 100644 --- a/man/torque_job_status.Rd +++ b/man/torque_job_status.Rd @@ -19,6 +19,6 @@ helper function to get the status of jobs on a TORQUE cluster } \details{ Torque does not keep information about completed jobs available in qstat or qselect. - Thus, we need to log when a job is listed as queued, so that it 'going missing' is evidence of it being completed. +Thus, we need to log when a job is listed as queued, so that it 'going missing' is evidence of it being completed. } \keyword{internal} diff --git a/man/update.mplusObject.Rd b/man/update.mplusObject.Rd index 7a11065..dd80ee9 100644 --- a/man/update.mplusObject.Rd +++ b/man/update.mplusObject.Rd @@ -43,6 +43,6 @@ str(update(example1, ANALYSIS = x, MODEL = ~ . + "wt ON hp*.5;")) rm(example1, x) } \author{ -Joshua F. Wiley +Joshua F. Wiley \href{mailto:jwiley.psych@gmail.com}{jwiley.psych@gmail.com} } \keyword{interface} diff --git a/man/validate_dhms.Rd b/man/validate_dhms.Rd index a0efc19..769ab40 100644 --- a/man/validate_dhms.Rd +++ b/man/validate_dhms.Rd @@ -14,7 +14,7 @@ helper function to validate format of walltime inputs for HPC submission } \details{ this always converts to an hms format, and if days are present, it - converts to dhms. Supported date formats match slurm sbatch: - https://slurm.schedmd.com/sbatch.html +converts to dhms. Supported date formats match slurm sbatch: +https://slurm.schedmd.com/sbatch.html } \keyword{internal} diff --git a/tests/testthat/test-mplusModel.R b/tests/testthat/test-mplusModel.R index 852f8e6..9d511ff 100644 --- a/tests/testthat/test-mplusModel.R +++ b/tests/testthat/test-mplusModel.R @@ -53,3 +53,15 @@ test_that("mplusModel reads existing output", { expect_equal(nrow(m$data), 500) }) +test_that("mplusModel exposes readModels sections", { + tmp <- tempdir() + file.copy(testthat::test_path("submitModels","ex3.1.inp"), tmp, overwrite = TRUE) + file.copy(testthat::test_path("submitModels","ex3.1.dat"), tmp, overwrite = TRUE) + file.copy(testthat::test_path("ex3.1.out"), tmp, overwrite = TRUE) + mplus_fake <- tempfile() + file.create(mplus_fake) + m <- mplusModel(inp_file = file.path(tmp, "ex3.1.inp"), read = TRUE, Mplus_command = mplus_fake) + expect_true(length(m$output) > 0) + expect_true(length(m$errors) == 0L) +}) +