m3: The Multinomial / Memory Measurement Model

In bmm: Easy and Accessible Bayesian Measurement Models Using 'brms'

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 = c("custom", "ss", "cs"),
  ...
)

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. Numbers named after the response categories, e.g. c(corr = 1, other = 4), are matched to the categories by name. Numbers without names, or with other names, are taken in the order of resp_cats, and other names become the names of the columns bmm adds to the data. Column names given category names, e.g. c(other = "n_other", corr = "n_corr"), are matched by name as well, in any order. Custom activation formulas can use numbers by these column names; numbers without names or named after the categories are called ⁠n_opt_<category>⁠.
choice_rule	The choice rule that should be used for the M3. The options are "softmax", "simple", or "gaussian". 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. The "gaussian" option adds independent standard normal noise to the activation of every candidate and chooses the candidate with the largest value (a Thurstonian rule: the choice is the maximum of noisy activations); "softmax" is the same with Gumbel noise. Activations under "gaussian" are on a smaller scale, and the difference is not one constant factor: a shrinks more than c, so a comparison of c with a, and effects of conditions that change the number of candidates (such as set size), can differ between the two rules. Sampling under "gaussian" costs about 40 times as much per iteration as under "softmax", because each probability is a 40-node numerical integral: a 40-subject, three-condition model with random intercepts took 15 seconds under "softmax" and about 4 minutes under "gaussian" end to end (4 chains, 1000 + 1000 iterations, Stan compilation included), 2.5 minutes with threads = threading(2). In versions ss and cs, c and a have normal(3, 1) main priors under "softmax" and normal(2, 1) under "gaussian"; under "simple" c has normal(3, 1) and a has normal(0, 1), on the log scale.
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(6), 880-932. https://doi.org/10.1037/rev0000159

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(3,1)

    • effects: normal(0,0.5)

    • sd: exponential(1)

  • c:

    • main: normal(3,1)

    • effects: normal(0,0.5)

    • sd: exponential(1)

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)

    • sd: exponential(1)

  • c:

    • main: normal(3,1)

    • effects: normal(0,0.5)

    • sd: exponential(1)

  • f:

    • main: logistic(0,1)

    • effects: normal(0,1)

    • sd: exponential(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:

Missing values and reserved names

A missing response count (NA) is counted as 0. If the category has options in that row, bmm() warns and says how many counts were replaced; if it has none (num_options is 0 in that row), the 0 is true and there is no warning, as for dist in oberauer_lewandowsky_2019_e1. A missing value in a column named in num_options is an error: enter 0 where there were no options. Data columns named Y, nTrials or ⁠Idx_<category>⁠ are refused because bmm() creates columns with these names; response categories may be called Y or nTrials.

Value

An object of class bmmodel

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)

bmm documentation built on Oct. 16, 2026, 9:08 a.m.