bmm (version 1.2.0)

m3: The Multinomial / Memory Measurement Model

Description

The Multinomial / Memory Measurement Model (M3) is a measurement model that was originally introduced for working memory tasks with categorical responses. It assumes that each candidate in each response category is activated by a combination of sources of activation. The probability of choosing a response category is determined by the activation of the candidates. The model can be used for any n-AFC categorical decision task.

Usage

m3(resp_cats, num_options, choice_rule = "softmax", version = "custom", ...)

Value

An object of class bmmodel

Arguments

resp_cats

The variable names that contain the number of responses for each of the response categories used for the M3.

num_options

Either an integer vector of the same length as resp_cats if the number of candidates in the respective response categories are constant across all conditions in the experiment. Or a vector specifying the variable names that contain the number of candidates in each response category. The order of these variables should be in the same order as the names of the response categories passed to resp_cats

choice_rule

The choice rule that should be used for the M3. The options are "softmax" or "simple". The "softmax" option implements the softmax normalization of activation into probabilities for choosing the different response categories. The "simple" option implements a simple normalization of the absolute activations over the sum of all activations. For details on the differences of these choice rules please see the appendix of Oberauer & Lewandowsky (2019) "Simple measurement models for complex working memory tasks" published in Psychological Review.

version

Character. The version of the M3 model to use. Can be one of ss, cs, or custom. The default is custom.

...

used internally for testing, ignore it

Details

• Domain: Working Memory (categorical), Categorical Decision Making

• Task: n-AFC retrieval

• Name: The Multinomial / Memory Measurement Model

• Citation:

  • Oberauer, K., & Lewandowsky, S. (2019). Simple measurement models for complex working-memory tasks. Psychological Review, 126.

Version: ss

• Requirements:

  • Provide names for variables specifying the number of responses in a set of response categories.

  • Specify activation sources for each response categories

  • Include at least an activation source "b" for all response categories

  • Predict the specified activation at least by a fixed intercept and any additional predictors from your data

• Parameters:

  • b: Background activation. Added to each response category. Fixed for scaling, necessary in all models.

  • c: Context activation. Added to the item cued to be recalled, that is the correct item.

  • a: General activation. Added to all items that were presented during the current trial.

• Fixed parameters:

  • b = 0

• Default parameter links:

  • c = identity; a = identity

• Default priors:

  • a:

    • main: normal(2,1)

    • effects: normal(0,0.5)

  • c:

    • main: normal(3,1)

    • effects: normal(0,2)

Version: cs

• Requirements:

  • Provide names for variables specifying the number of responses in a set of response categories.

  • Specify activation sources for each response categories

  • Include at least an activation source "b" for all response categories

  • Predict the specified activation at least by a fixed intercept and any additional predictors from your data

• Parameters:

  • b: Background activation. Added to each response category. Fixed for scaling, necessary in all models.

  • c: Context activation. Added to the item cued to be recalled, that is the correct item.

  • a: General activation. Added to all items that were presented during the current trial.

  • f: Filtering. This parameter captures the extent to which distractors remained in working memory.

• Fixed parameters:

  • b = 0

• Default parameter links:

  • c = identity; a = identity; f = logit

• Default priors:

  • a:

    • main: normal(3,1)

    • effects: normal(0,0.5)

  • c:

    • main: normal(3,1)

    • effects: normal(0,2)

  • f:

    • main: logistic(0,1)

    • effects: normal(0,1)

Version: custom

• Requirements:

  • Provide names for variables specifying the number of responses in a set of response categories.

  • Specify activation sources for each response categories

  • Include at least an activation source "b" for all response categories

  • Predict the specified activation at least by a fixed intercept and any additional predictors from your data

• Parameters:

  • b: Background activation. Added to each response category. Fixed for scaling, necessary in all models.

• Fixed parameters:

  • b = 0

• Default parameter links:

  • =

• Default priors:

Examples

if (FALSE) { # isTRUE(Sys.getenv("BMM_EXAMPLES"))
data <- oberauer_lewandowsky_2019_e1

# initiate the model object
m3_model <- m3(
  resp_cats = c("corr", "other", "dist", "npl"),
  num_options = c("n_corr", "n_other", "n_dist", "n_npl"),
  choice_rule = "simple"
)

# specify the model formula including the activation formulas for each response category
m3_formula <- bmf(
  corr ~ b + a + c,
  other ~ b + a,
  dist ~ b + d,
  npl ~ b,
  c ~ 1 + cond + (1 + cond | ID),
  a ~ 1 + cond + (1 + cond | ID),
  d ~ 1 + (1 | ID)
)

# specify links for the model parameters
m3_model$links <- list(
  c = "log",
  a = "log",
  d = "log"
)

# check if the default priors are applied correctly
default_prior(m3_formula, data = data, model = m3_model)

# fit the model
m3_fit <- bmm(
  formula = m3_formula,
  data = data,
  model = m3_model,
  cores = 4
)

# print summary of the model
summary(m3_fit)
}