make.mpt.cf: Functions to transform MPT models.
In MPTinR: Analyze Multinomial Processing Tree Models

Description Usage Arguments Details Value Note Author(s) References See Also Examples

(Helper) functions that takes an MPT model file and transforms it into a representation in the context-free language of MPT models L-BMPT (Purdy & Batchelder, 2009) or takes the representation in LBMPT and returns the model equations.

make.mpt.cf(model.filename, restrictions.filename = NULL, 
            model.type = c("easy", "eqn"), treewise = FALSE)

lbmpt.to.mpt(model.list, outfile = NULL, category.names= TRUE)

`model.filename`	A character `vector` specifying the location and name of the model file.
`restrictions.filename`	`NULL` or a character `vector` or a `list` of characters. The default is `NULL` which corresponds to no restrictions. A character `vector` specifies the location or name of the restrictions file. A `list` of characters contains the restrictions directly. Inequality/order restrictions are silently ignored.
`model.type`	Character vector specifying whether the model file is formatted in the `easy` format (`"easy"`; i.e., each line represents all branches corresponding to a response categories) or the traditional EQN syntax (`"eqn"` or `"eqn2"`). See Details in `fit.mpt`.
`treewise`	logical. Should the model be concatenated to one tree before transforming to LBMPT? Default is `FALSE`.
`model.list`	A list of character `vector`s representing a model in LBMPT. Each element of the vector corresponds to either a parameter or category. Each list element corresponds to one tree. Can be returned from `make.mpt.cf`.
`outfile`	Name of the file the model equation should be saved in (in easy format). If `NULL` (the default) prints it to the console instead (`stdout()`).
`category.names`	logical. Should category names (e.g., "category 1") be printed at the end of each line?

Purdy and Batchelder (2009) provide a new way of how binary multinomial processing tree (MPT) models can be represented, a context free language called L-BMPT. This function takes a model file that consists of the equations defining a model (e.g., http://www.psychologie.uni-freiburg.de/Members/singmann/R/mptinr/modelfile) and returns a character vector representing this model in L-BMPT.

There are three important things to know about this function:

1. L-BMPT distinguishes between observable categories (C) and parameters (theta). As MPTinR allows parameters to have any name that is legal for a variable in R (with the only restriction that parameters should NOT start with hank) the L-BMPT representation of the model's parameters can also consist of any name that is a legal variable name in R. To distinguish parameters from categories, categories are represented as integers (i.e., numbers) (a number is not a legal variable name in R). Furthermore, as legal variable names may end with a number, concatenating parameters and categories into one string could lead to an ambiguous representation of the model. Therefore, the returned representation in L-BMPT is a character vector with each element representing either a parameter (any legal variable name in R) or a category (an integer).
Theta: Names that are legal variable names in R.
C: Integers.

2. If a model consists of more than n > 1 trees, this function per default concatenates the trees into a single binary MPT model by adding n-1 parameters (named hank.join.x with x be a integer starting at 1; see Wu, Myung & Batchelder, 2010). This can be turned off, by setting treewise to TRUE.

3. It is absolutely necessary that the representation of the model via equations in the model file exactly maps on the structure of the binary tree. In other words, equations in the model file can NOT be simplified in any way. The equations in the model file may only consist of the parameters and their negations (e.g. d and (1-d)). Simplifications and aggregations in the model file (e.g., from u * (1-u) + u * (1-u) to 2*u*(1-u) will lead to erroneous results! Similarly, reparameterizations for inequality constraints (which can be done by fit.mpt) can not be represented in L-BMPT.

make.mpt.cf: A character vector with each element representing either a parameter or a category (categories are represented by integer numbers). In case of multiple trees and treewise = TRUE, a list of such vectors.

lbmpt.to.mpt: Either prints the model to the screen or returns nothing and saves the model equations in the specified file.

It is absolutely necessary that the model file exactly maps on the structure of the binary tree. See Details.

Henrik Singmann (make.mpt.cf)

Quentin Gronau and Franz Dietrich (lbmpt.to.mpt, using a function from Akhil S Bhel, LinearizeNestedList)

Purdy, B. P., & Batchelder, W. H. (2009). A context-free language for binary multinomial processing tree models. Journal of Mathematical Psychology, 53, 547-561.

Riefer, D. M., & Batchelder, W. H. (1988). Multinomial modeling and the measurement of cognitive processes. Psychological Review, 95, 318-339.

Wu, H., Myung, J., I., & Batchelder, William, H. (2010). Minimum description length model selection of multinomial processing tree models. Psychonomic Bulletin & Review, 17, 275-286.

get.mpt.fia and link{bmpt.fia} for functions calling make.mpt.cf to obtain the FIA of a MPT model.

See fit.mpt for the main function of MPTinR which also calls make.mpt.cf for obtaining the FIA.

prepare.mpt.fia will provide the code needed for obtaining the Minimum Description Length of a MPT model using Matlab (Wu, Myung & Batchelder, 2010) and calls make.mpt.cf for obtaining the L-BMPT representation.

model2 <- system.file("extdata", "rb.fig2.model", package = "MPTinR")

make.mpt.cf(model2)

make.mpt.cf(model2, treewise = TRUE)
  
lbmpt.to.mpt(make.mpt.cf(model2, treewise = TRUE))