Functions making Mplus syntaxes and corrections to documentation.

tzoltak · Feb 6, 2023 · cd9ea83 · cd9ea83
1 parent 10c6b70
commit cd9ea83
Show file tree

Hide file tree

Showing 46 changed files with 1,597 additions and 347 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,7 +1,7 @@
 Package: rstyles
 Type: Package
 Title: Generating Simulated Data Mimicking Response Styles to Survey Questions
-Version: 0.6.0
+Version: 0.7.0
 Authors@R: c(person("Tomasz", "Zoltak",
                     email = "[email protected]",
                     role = c("aut", "cre"),
@@ -36,8 +36,9 @@ Suggests:
     covr,
     mnormt,
     mirt,
-    truncnorm
+    truncnorm,
+    MplusAutomation
 Encoding: UTF-8
 Language: en-US
-RoxygenNote: 7.1.2
+RoxygenNote: 7.2.3
 Config/testthat/edition: 3
diff --git a/NAMESPACE b/NAMESPACE
@@ -5,6 +5,7 @@ S3method(compute_item_expected_scores,rstylesTest)
 S3method(intercepts2thresholds,data.frame)
 S3method(intercepts2thresholds,default)
 S3method(intercepts2thresholds,matrix)
+S3method(print,MplusSyntaxElements)
 S3method(thresholds2intercepts,data.frame)
 S3method(thresholds2intercepts,default)
 S3method(thresholds2intercepts,matrix)
@@ -18,6 +19,8 @@ export(intercepts2thresholds)
 export(lnorm_mean)
 export(lnorm_sd)
 export(make_item)
+export(make_mplus_gpcm_model_syntax)
+export(make_mplus_irtree_model_syntax)
 export(make_scoring_matrix_aem)
 export(make_scoring_matrix_rt)
 export(make_scoring_matrix_stz)
@@ -28,3 +31,6 @@ export(score_on_last_answer_previous)
 export(score_on_last_answer_straight)
 export(score_on_previous_answers_bounce)
 export(thresholds2intercepts)
+importFrom(stats,na.omit)
+importFrom(stats,setNames)
+importFrom(utils,head)
diff --git a/NEWS.md b/NEWS.md
@@ -1,22 +1,36 @@
+# rstyles 0.7.0 (6.02.2023)
+
+## New features
+
+- New functions `make_mplus_irtree_model_syntax()` and `make_mplus_gpcm_model_syntax()` enabling convenient preparing Mplus syntax specifying response-style models.
+
+## Bug fixes
+
+- `expand_responses()` deals with data with responses being a *tibble*.
+
+## Other changes
+
+- Considering remarks of Plieninger (2020) regarding the interpretation of IRTree models the distinction between *sequential* and *simultaneous* response processes was (almost completely) removed from the package parameter names and descriptions in documentation in favor of labeling them as *IRTree* and *GPCM*.
+
 # rstyles 0.6.0 (23.12.2021)
 
 ## New features
 
-- New functions `make_scoring_matrix_rt()` and `make_scoring_matrix_stz()` enabling convienient construction of scoring matrices using *random thresholds* and *sum to zero* approaches.
+- New functions `make_scoring_matrix_rt()` and `make_scoring_matrix_stz()` enabling convenient construction of scoring matrices using *random thresholds* and *sum to zero* approaches.
 
 # rstyles 0.5.0 (20.12.2021)
 
 ## New features
 
 - New function `generate_item_expected_scores()` that allows to generate (by numerical integration) expected probabilities of responses (response categories) given an item object or test object and covariance matrix of latent traits.
   - Dependency from the package *mvtnorm* was added to be able to compute weights for quadrature points.
-- New utility functions `thresholds2intercepts()` and `intercepts2thresholds()` allowing conversion between *thresholds* and *intercepts* parametrisations of *simultaneous* GPCM items.
+- New utility functions `thresholds2intercepts()` and `intercepts2thresholds()` allowing conversion between *thresholds* and *intercepts* parameterizations of GPCM items.
 
 ## Bug fixes
 
 - `expand_responses()` do not take into account missing values in the data while performing assertion that all values in the data are members of the set of values defined by rownames of the `scoringMatrix`.
-- `generate_intercepts()` correctly transforms parameters generated in a parametrisation involving item difficulty and thresholds relative to his difficulty into parametrisation of intercepts in case of *simultaneous* items (i.e. it cumulatively sums up thresholds and subtracts difficulty instead of adding difficulty to thresholds).
-  - Documentation was corrected to explain, that in case of *simultaneous* mode arguments define how values of *thresholds* should be generated but that function returns accordingly computed *intercepts*.
+- `generate_intercepts()` correctly transforms parameters generated in a parameterization involving item difficulty and thresholds relative to his difficulty into parametrization of intercepts in case of GPCM items (i.e. it cumulatively sums up thresholds and subtracts difficulty instead of adding difficulty to thresholds).
+  - Documentation was corrected to explain, that in case of GPCM mode arguments define how values of *thresholds* should be generated but that function returns accordingly computed *intercepts*.
 
 ## Other changes
 
@@ -32,7 +46,7 @@
 
 - `make_test()` assigns names to the created items by default and provides additional `names` argument if user wants to provide names himself/herself.
 - `generate_test_responses()` uses items' names (if there are any) to name columns of the returned matrix.
-- `generate_test_responses()` converts matrix it returns to numeric one (if only this is possible without loss of information); it also provides additional argument `tryConvertToNumeric` that allows to bring back its former behaviour (i.e. returning a character matrix).
+- `generate_test_responses()` converts matrix it returns to numeric one (if only this is possible without loss of information); it also provides additional argument `tryConvertToNumeric` that allows to bring back its former behavior (i.e. returning a character matrix).
 - `generate_intercepts_sml()`, and consequently `generate_intercepts()` when called with `FUNt` argument, returns intercepts matrix with additional first columns of zeros to make it compatible with the format that uses function `simdata()` from *mirt* package (`generate_test_responses()` was, and still is, able to deal with providing it intercepts either with or without such additional zeros).
 
 ## Documentation

diff --git a/R/compute_item_expected_scores.R b/R/compute_item_expected_scores.R
@@ -3,16 +3,16 @@
 #' item object constructed using \code{\link{make_item}} or test (i.e. list of
 #' items) object constructed using \code{\link{make_test}} and covariance matrix
 #' of latent traits, assuming multivariate-normal distribution of latent traits.
-#' @param x object of class \emph{rstylesItem} or \emph{rstylesTest}
-#' @param vcov covariance matrix of latent traits (in line with item's scoring
+#' @param x an object of class \emph{rstylesItem} or \emph{rstylesTest}
+#' @param vcov a covariance matrix of latent traits (in line with item's scoring
 #' matrix); if not provided uncorrelated standard normal is used
-#' @returns table
+#' @return A table
 #' @seealso \code{\link{make_item}}
 #' @examples
-#' itemGPCM <- make_item(scoringMatrix = make_scoring_matrix_aem(1:5, "simultaneous")[, -4],
+#' itemGPCM <- make_item(scoringMatrix = make_scoring_matrix_aem(1:5, "gpcm")[, -4],
 #'                       slopes = c(i = 1, m = 2, e = 3),
 #'                       intercepts = cumsum(c(0, seq(-0.5, 0.5, length.out = 4))),
-#'                       mode = "simultaneous")
+#'                       mode = "gpcm")
 #' vcov <- matrix(c( 1,    0.5, -0.5,
 #'                   0.5,  1,   -0.25,
 #'                  -0.5, -0.25, 1),
@@ -23,13 +23,13 @@
 #' itemIRTree <- make_item(scoringMatrix = make_scoring_matrix_aem(1:5, "mae"),
 #'                         slopes = c(m = 1, a = 1, e = 1),
 #'                         intercepts = c(m1 = 0, a1 = 0, e1 = 0),
-#'                         mode = "sequential")
+#'                         mode = "irtree")
 #' vcovIRTree <- vcov
 #' colnames(vcovIRTree) <- rownames(vcovIRTree) <- c("a", "m", "e")
 #' compute_item_expected_scores(itemIRTree) # orthogonal, standard-normal latent traits
 #' compute_item_expected_scores(itemIRTree, vcovIRTree)
 #'
-#' sM <- make_scoring_matrix_aem(1:5, "simultaneous")[, -4]
+#' sM <- make_scoring_matrix_aem(1:5, "gpcm")[, -4]
 #' test <- make_test(sM,
 #'                   generate_slopes(11, sM, c(1, 2, 3)),
 #'                   generate_intercepts(11, sM,
@@ -39,7 +39,7 @@
 #'                                       FUNt = seq,
 #'                                       argst = list(from = -1.5, to = 1.5,
 #'                                       length.out = 4)),
-#'                   "simultaneous")
+#'                   "gpcm")
 #' sapply(compute_item_expected_scores(test, vcov), identity)
 #' @name compute_item_expected_scores
 #' @export
@@ -100,15 +100,15 @@ compute_item_expected_scores.rstylesItem <- function(x,
   w <- mvtnorm::dmvnorm(theta, sigma = vcov)
   w <- w / sum(w)
 
-  if (x$mode == "simultaneous") {
+  if (x$mode == "gpcm") {
     x$slopes <- x$slopes[sapply(colnames(x$scoringMatrix), match,
                                 table = names(x$slopes)), drop = FALSE]
     probs <- compute_item_expected_scores_gpcm(
       theta,
       x$scoringMatrix * rep(x$slopes,
                             each = nrow(x$scoringMatrix)),
       x$intercepts)
-  } else if (x$mode == "sequential") {
+  } else if (x$mode == "irtree") {
     nodes <- vector(mode = "list", length = ncol(x$scoringMatrix))
     names(nodes) <- colnames(x$scoringMatrix)
     for (i in 1L:length(nodes)) {
@@ -119,7 +119,7 @@ compute_item_expected_scores.rstylesItem <- function(x,
         x$slopes[which(names(x$slopes) == names(nodes)[i])],
         x$intercepts[grep(paste0("^", names(nodes)[i],
                                  "_?[[:digit:]]+"), names(x$intercepts))],
-        "simultaneous")
+        "gpcm")
       nodes[[i]] <- compute_item_expected_scores_gpcm(
         theta[, names(nodes)[i], drop = FALSE],
         nodes[[i]]$scoringMatrix * rep(nodes[[i]]$slopes,

diff --git a/R/expand_responses.R b/R/expand_responses.R
@@ -2,10 +2,10 @@
 #' @description Using scoring matrix provided as its second argument function
 #' \emph{expands} (recodes) responses to each item (column) in a provided matrix
 #' of responses into a set of variables that may be put into model estimation.
-#' @param responses matrix of responses with items in columns and observations
+#' @param responses a matrix of responses with items in columns and observations
 #' in rows
-#' @param scoringMatrix matrix describing scoring patterns on each latent trait
-#' @return matrix (of integers)
+#' @param scoringMatrix a matrix describing scoring patterns on each latent trait
+#' @return A matrix (of integers)
 #' @examples
 #' sM <- make_scoring_matrix_aem(5, "mae")
 #' responses <- matrix(sample(1L:5L, 20, replace = TRUE), ncol = 4,
@@ -26,7 +26,8 @@ expand_responses <- function(responses, scoringMatrix) {
             all(setdiff(unique(unlist(sapply(responses, unique))), NA) %in%
                   rownames(scoringMatrix)))
 
-  respWide <- matrix(NA, nrow = nrow(responses),
+  responses <- as.matrix(responses)
+  respWide <- matrix(NA_real_, nrow = nrow(responses),
                      ncol = ncol(scoringMatrix) * ncol(responses),
                      dimnames = list(NULL,
                                      paste0(rep(colnames(scoringMatrix),