Merge pull request #224 from michaelhallquist/codex/update-documentation-to-use-markdown-syntax

refactor: convert roxygen docs to markdown

Author: michaelhallquist

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}}.
 #'

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.

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

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

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

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.
 
-}
+}

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