MPT article, ppp(), mpt_data_reshape() and mpt() API changes (MPT 6/6, #255)

NEWS.md

@@ -7,18 +7,20 @@
 * Add **Confidence Rating Signal Detection Theory** (`sdt_rating`) for old/new recognition and detection tasks with ordered confidence ratings, aggregated to counts per rating category. It estimates sensitivity (`d`), the criterion (as `criterion` or `bias`, as in `sdt_yn()`) and the confidence thresholds, and optionally the unequal-variance ratio (`sdratio`); `threshold_type` chooses how the thresholds are parameterized. Also adds `dsdt_rating()` and `rsdt_rating()`. See `?sdt_rating` for the parameters, the threshold types, the default priors and how `d` relates to the sensitivity `sdt_yn()` reports. Thanks to @GidonFrischkorn
 * Add two versions of `sdt_rating()`, selected with `version`: `"dpsdt"`, the dual-process model (Yonelinas, 1994) with recollection of old items (`Ro`) and recall-to-reject of new items (`Rn`; as in Yonelinas, 2024), and `"metad"`, the meta-d' model, which estimates metacognitive efficiency as the log M-ratio `logmratio` (Maniscalco & Lau, 2012). Both reduce to the standard model while their extra parameters are off. Also adds `mratio()`, `dsdt_dpsdt()`, `rsdt_dpsdt()`, `dsdt_metad()` and `rsdt_metad()`. See `?sdt_rating`. Thanks to @GidonFrischkorn
 * Add **Continuous Dual-Process Signal Detection Theory** (`sdt_cdp`) for old/new recognition with Remember/Know judgments (Wixted & Mickes, 2010). It estimates familiarity (`dfam`) and recollection (`drec`) sensitivity, the old/new `criterion`, the confidence thresholds and the Remember criterion (`rcrit`) from aggregated response counts; the recollection SD (`sigmar`), the familiarity-recollection correlation (`rho`) and a Know/Guess criterion (`kcrit`) can be freed through the formula. Also adds `aggregate_sdt_cdp_data()`, `dsdt_cdp()` and `rsdt_cdp()`. See `?sdt_cdp` for the parameters, the response format and how `drec` relates to the sensitivity `sdt_yn()` reports. Thanks to @GidonFrischkorn
-* Add **Multinomial Processing Tree models** (`mpt`) for tasks with categorical responses that come from discrete processing states, such as the two-high-threshold model of recognition. You write each tree's branch probabilities with `mpt_tree()`, give a parameter the same name in every tree that shares it, and fit the model to response counts; `tree_id` names the data column that says which tree a row belongs to. Parameters take a logit or probit link and can be fixed in the formula (`bmf(g = 0.5)`) or given non-linear formulas. Also adds `dmpt()` and `rmpt()`. See `?mpt` (#255). Thanks to @GidonFrischkorn
-* `mpt()` gains `restrictions`, which equates parameters or fixes them to constants in the syntax of MPTinR and TreeBUGS (`c("Dn = Do", "g = 0.5")`), and `simplex`, which declares groups of parameters that sum to 1, such as guessing rates across response options. Blank and `#` comment lines in the restrictions are skipped, so `readLines()` of an MPTinR restrictions file of equalities and constants works. Printing a model lists its restrictions and simplex groups. See `?mpt` (#255). Thanks to @GidonFrischkorn
-* By default, a `simplex` group gets a uniform prior over all ways of splitting the probability among its members, so each of K members has prior mean 1/K whatever the order they are listed in. Printing the model states this prior. `?mpt` shows how to get the per-branch uniform priors of TreeBUGS instead, under which the first-listed member has prior mean 0.5 (#255).
-* `mpt()` gains `covariates`, for data columns used in branch expressions, such as guessing rates fixed by the design; `bmm()` stops when the branches of a row do not sum to 1 with that row's values. `mpt_tree()` gains `impossible`, for response categories a tree cannot produce, such as distractor responses on trials without distractors. `dmpt()` and `rmpt()` take covariate values too. See `?mpt` and `?mpt_tree` (#255). Thanks to @GidonFrischkorn
-* New functions `mpt_from_string()` and `mpt_from_eqn()` build an `mpt()` model from MPTinR-style model text (a string or `readLines()` output) or from an EQN file. Both take `impossible` for response categories a tree cannot produce. `mpt_from_eqn()` renames names `mpt()` cannot use, such as `D_o`, reports the renaming, takes restrictions in the file's names, and maps numeric tree labels through `tree_names`. MPTinR and TreeBUGS skip the first line of an EQN file; bmm reads it unless it is the equation count, so delete a title line or start it with `#`. See `?mpt_from_eqn` (#255). Thanks to @GidonFrischkorn
-* `plot()` draws the processing-tree diagram of an `mpt_tree()`, or of every tree of an `mpt()` model, from the branch expressions. See `?plot.mpt_tree` (#255). Thanks to @GidonFrischkorn
+* Add **Multinomial Processing Tree models** (`mpt`) for categorical responses from discrete processing states, such as the two-high-threshold model of recognition. Write each tree's branches with `mpt_tree()`, as formulas or as a named list of strings, name a shared parameter alike in every tree, and fit the model to response counts, one row per participant and tree, with `tree_id` naming each row's tree. `links` sets a logit or probit link for all or single parameters; parameters can be fixed in the formula (`bmf(g = 0.5)`) or given non-linear formulas. Also adds `dmpt()` and `rmpt()`. See `?mpt` (#255). Thanks to @GidonFrischkorn
+* `mpt()` takes `restrictions` that equate parameters or fix them to constants, in MPTinR and TreeBUGS syntax (`c("Dn = Do", "g = 0.5")`, or `readLines()` of such a restrictions file), and `simplex` for parameters that sum to 1, such as guessing rates. A simplex group's default uniform prior gives each of K members prior mean 1/K whatever their order; `?mpt` shows how to get the per-branch uniform priors of TreeBUGS, which give the first member prior mean 0.5. Printing the model lists the restrictions, the simplex groups with their prior and an identifiability check (#255). Thanks to @GidonFrischkorn
+* Branch expressions can use data columns declared in `covariates`, for probabilities the design fixes, such as guessing rates that depend on the number of response options; `bmm()` stops when a row's values make the branches of a tree not sum to 1. Response categories a tree cannot produce, such as distractor responses on trials without distractors, are declared with `impossible` in `mpt_tree()` and in the importers. `dmpt()` and `rmpt()` take covariate values too. See `?mpt_tree` (#255). Thanks to @GidonFrischkorn
+* New functions `mpt_from_string()` and `mpt_from_eqn()` build an `mpt()` model from MPTinR-style model text (a string or `readLines()` output) or from an EQN file (multiTree, MPTinR, TreeBUGS); both take `restrictions` as their second argument. `mpt_from_eqn()` renames and reports names `mpt()` cannot use, such as `D_o`; it takes restrictions in the file's names, maps per-tree category labels onto shared categories with `categories`, and numeric tree labels with `tree_names`. Unlike MPTinR and TreeBUGS, bmm reads an EQN file's first line unless it is the equation count, so start a title line with `#` or delete it. See `?mpt_from_eqn` (#255). Thanks to @GidonFrischkorn
+* New function `mpt_data_reshape()` reshapes the wide frequency tables of MPTinR and TreeBUGS, one row per participant and one column per category, into the one-row-per-participant-and-tree layout `bmm()` expects, with 0 for the categories a tree cannot produce. Columns that are no counts, such as a group factor, are carried to every row; `columns = "mptinr"` reads the unnamed, sorted columns of MPTinR data. See `?mpt_data_reshape`. Thanks to @GidonFrischkorn
+* `plot()` draws the processing-tree diagram of an `mpt_tree()`, or of every tree of an `mpt()` model, from the branch expressions, and marks restricted parameters on their edges. See `?plot.mpt_tree` (#255). Thanks to @GidonFrischkorn
+* New article *Multinomial Processing Tree (MPT) models* walks through specifying, fitting and interpreting `mpt()` models, constraining parameters, design-fixed covariates, a fit to real data, non-linear parameters, importing model files and migrating from MPTinR or TreeBUGS (#255). Thanks to @GidonFrischkorn
 
 ### New datasets
 * Add **`broeder_schuetz_2009_e3`**, binary old/new recognition data from Broeder & Schuetz (2009, Exp. 3), with five base-rate conditions from 40 subjects. See `?broeder_schuetz_2009_e3`.
 * Add **`meyer_grant_jakob_2025`**, ranking data from Meyer-Grant & Jakob (2025): 60 subjects ranking 3, 4 or 5 faces, aggregated to the target's rank counts per subject and set size. See `?meyer_grant_jakob_2025`.
 
 ### New features
+* New function `ppp()` computes the goodness-of-fit statistics T1 (category frequencies) and T2 (their covariances across participants) of Klauer (2010) with their posterior predictive p-values, the checks TreeBUGS' `PPP()` reports, for `mpt()`, `m3()` and the SDT count models. `level = "participant"` gives one T1 per participant. See `?ppp` (#497).
 * `m3()` accepts `choice_rule = "gaussian"`, a Thurstonian rule: every candidate gets independent normal noise and the strongest one is chosen (`"softmax"` is the same with Gumbel noise). Activation estimates are on a smaller scale than under `"softmax"`, and conclusions about `c` against `a`, or about conditions that change the number of candidates such as set size, can differ between the rules. Fits take much longer than with `"softmax"`. The Gaussian rule requires whole numbers of options. See `choice_rule` in `?m3`. Thanks to @GidonFrischkorn
 * New function `bmm_setup()` checks whether your machine can fit models: the C++ toolchain, `cmdstanr` with CmdStan, `rstan`, and the backend `bmm()` will use. It then compiles and samples a small test model and gives one fix for every check that failed. When `bmm()` fails because the compiler or the Stan backend is missing or broken, the error now points to `bmm_setup()` (#431).
 * New post-processing functions for the signal detection models: `roc_sdt()`, `roc_observed()` and `auc_sdt()` return the model-implied and observed ROC and the area under it for `sdt_yn` and `sdt_rating`; `latent_sdt()` the latent evidence distributions of all four models; `sdt_thresholds()` the confidence thresholds of `sdt_rating`; and `sdt_sensitivity()` the sensitivity on the noise, signal or root-mean-square SD scale. All but `roc_observed()` print a summary; `plot()` draws the ROC with the observed points, the AUC and the latent distributions; `summary()` says when `d` is *d_a*. The new article *Signal Detection Theory models* walks through all four models and these functions (#370). Thanks to @GidonFrischkorn

R/bmmformula.R

@@ -251,11 +251,24 @@ bmf2bf.default <- function(model, formula) {
   NULL
 }
 
+# The parameters whose formulas a model's check_formula method generates, so
+# that no user formula is expected for them. Their placeholders are still added
+# below, because the generating method overwrites them by name.
+generated_parameters <- function(model) {
+  UseMethod("generated_parameters")
+}
+
+#' @exportS3Method
+generated_parameters.default <- function(model) {
+  character(0)
+}
+
 add_missing_parameters <- function(model, formula = bmmformula()) {
   formula_pars <- names(formula)
   model_pars <- setdiff(names(model$parameters),
                         unused_alternative_parameters(model, formula))
   fixed_pars <- names(model$fixed_parameters)
+  generated_pars <- generated_parameters(model)
 
   estimable_formula_pars <- setdiff(formula_pars, fixed_pars)
   missing_pars <- setdiff(model_pars, estimable_formula_pars)
@@ -264,7 +277,7 @@ add_missing_parameters <- function(model, formula = bmmformula()) {
     add <- stats::as.formula(paste(mpar, "~ 1"))
     if (mpar %in% fixed_pars) {
       attr(add, "constant") <- TRUE
-    } else {
+    } else if (!mpar %in% generated_pars) {
       message2("No formula for parameter {mpar} provided. Only a fixed intercept will be estimated.")
     }
     formula[mpar] <- add

R/distributions.R

@@ -846,7 +846,11 @@ rm3 <- function(n, size, pars, m3_model, act_funs = NULL, unpack = FALSE,
 #'   categories, giving the number of observed responses per category. If
 #'   `x` is a named vector, its names are matched to the response categories
 #'   and the vector is reordered accordingly; an unnamed vector is read in
-#'   the order of the branch names of the selected tree.
+#'   the order of the model's response categories,
+#'   `mpt_model$resp_vars$resp_cats`, which is the order of the first tree
+#'   given to [mpt()] ([mpt()] stores the branches of every tree in that
+#'   order, whatever order they were written in). `rmpt()` returns its
+#'   columns in the same order.
 #' @param n Integer. Number of observations to generate data for.
 #' @param size The total number of observations across all response categories.
 #' @param pars A named vector or list with the values of at least the latent
@@ -884,23 +888,23 @@ rm3 <- function(n, size, pars, m3_model, act_funs = NULL, unpack = FALSE,
 #'   and `rmpt` generates random response counts for the response categories.
 #'
 #' @examples
-#' tree_old <- mpt_tree("old", list(
+#' tree_target <- mpt_tree("target", list(
 #'   old = "D + (1 - D) * g",
 #'   new = "(1 - D) * (1 - g)"
 #' ))
-#' tree_new <- mpt_tree("new", list(
+#' tree_lure <- mpt_tree("lure", list(
 #'   old = "(1 - D) * g",
 #'   new = "D + (1 - D) * (1 - g)"
 #' ))
-#' model <- mpt(list(tree_old, tree_new), tree_id = "item_type")
+#' model <- mpt(list(tree_target, tree_lure), tree_id = "item_type")
 #'
 #' dmpt(
 #'   x = c(35, 15), pars = c(D = 0.7, g = 0.5),
-#'   mpt_model = model, tree = "old"
+#'   mpt_model = model, tree = "target"
 #' )
 #' rmpt(
 #'   n = 10, size = 50, pars = c(D = 0.7, g = 0.5),
-#'   mpt_model = model, tree = "new"
+#'   mpt_model = model, tree = "lure"
 #' )
 #' @export
 dmpt <- function(x, pars, mpt_model, tree = NULL, log = TRUE,

R/helpers-model.R

@@ -486,6 +486,7 @@ print.bmmodel <- function(x, ...) {
 #'
 #' @return Called for its printed output; returns `NULL` invisibly
 #' @keywords internal developer
+#' @export
 print_model_details <- function(model, ...) {
   UseMethod("print_model_details")
 }