Help for package masc

Title:

Simulate the Multi-Attribute Search and Choice (MASC) Model

Version:

0.1.0

Description:

Simulates the Multi-Attribute Search and Choice (MASC) model of Gluth, Deakin and Rieskamp (2026) <doi:10.1037/rev0000614> for multi-attribute decision-making, including sequential information search, Bayesian belief updating, and choice. Beliefs may be treated as univariate (independent attributes), or multivariate over correlated attributes ('MASC-C'), in which observing one attribute updates beliefs about correlated attributes via a Kalman filter.

License:

MIT + file LICENSE

Imports:

Rcpp, stats

Suggests:

knitr, rmarkdown, testthat (≥ 3.0.0), broom, patchwork, ggplot2, dplyr, tibble, purrr

Config/testthat/edition:

Encoding:

UTF-8

RoxygenNote:

7.3.3

URL:

https://github.com/kiante-fernandez/masc

BugReports:

https://github.com/kiante-fernandez/masc/issues

LinkingTo:

Rcpp, RcppArmadillo

VignetteBuilder:

knitr

Depends:

R (≥ 2.10)

LazyData:

true

NeedsCompilation:

yes

Packaged:

2026-05-20 15:52:30 UTC; kiante

Author:

Kiante Fernandez

[aut, cre, cph]

Maintainer:

Kiante Fernandez <kiantefernan@gmail.com>

Repository:

CRAN

Date/Publication:

2026-05-27 19:50:10 UTC

masc: Multi-Attribute Search and Choice Model

Description

Implementation of the Multi-Attribute Search and Choice (MASC) model for decision making. This model simulates how people make decisions when comparing options with multiple attributes by sequentially sampling information about different attributes until reaching a decision.

Details

The main function provided by this package is:

rMASC: Generate choices using the MASC model

Author(s)

Maintainer: Kiante Fernandez kiantefernan@gmail.com (ORCID) [copyright holder]

References

Gluth, S., Deakin, J., & Rieskamp, J. (2026). A theory of multiattribute search and choice. Psychological Review. doi:10.1037/rev0000614

Myopic Search Rule for MASC Model

Description

Internal function implementing the myopic search rule for the MASC model. Calculates transition probabilities for the next fixation by evaluating how likely each possible sample would lead to a decision.

Usage

MASC_SearchRule_myopic(n, m, w, w2, sp, thresh, alpha, prec, mu)

Arguments

n

Integer. Number of options.

m

Integer. Number of attributes.

w

Numeric vector. Attribute weights.

w2

Numeric vector. Squared attribute weights (pre-computed).

sp

Numeric vector. Sampling precision for each attribute.

thresh

Numeric. Current decision threshold.

alpha

Numeric. Search sensitivity parameter.

prec

Matrix. Current attribute precision (n x m).

mu

Matrix. Current attribute means (n x m).

Value

Numeric vector. Probabilities for each possible fixation location.

Generate Non-dominated Attribute Values

Description

Internal function that generates attribute values for options ensuring no option dominates another (i.e., is better on all attributes).

Usage

generate_attributes(n, m, lambda)

Arguments

n

Integer. Number of options.

m

Integer. Number of attributes per option.

lambda

Numeric. Precision parameter for attribute value generation.

Value

Matrix of attribute values (n x m).

Hotel Choice Experiment Dataset from Gluth et al. (2026)

Description

A dataset from a multi-attribute decision-making experiment examining how people search for and evaluate information when choosing between hotel options.

Usage

hotelgluth2024

Format

`hotelgluth2024`

A data frame with multiple rows per subject, each representing a single trial in a hotel choice experiment with three attributes:

dataset: Identifier for the dataset type, set to "hotel"
subject: Unique identifier for each participant in the experiment
trial: Trial number within each subject's experimental session
opt1_att1: Value of the first attribute for the first hotel option (distance to beach)
opt1_att2: Value of the second attribute for the first hotel option (room size)
opt1_att3: Value of the third attribute for the first hotel option (number of stars)
opt2_att1: Value of the first attribute for the second hotel option (distance to beach)
opt2_att2: Value of the second attribute for the second hotel option (room size)
opt2_att3: Value of the third attribute for the second hotel option (number of stars)
difficulty: Difficulty level of the choice trial, based on the difference in option ratings
choice: Chosen hotel option (1 or 2)
rt: Reaction time for the choice
att_w1: Weight of the first attribute (distance to beach)
att_w2: Weight of the second attribute (room size)
att_w3: Weight of the third attribute (number of stars)
sigma: Model parameter related to sampling noise
alpha: Model parameter related to search rule sensitivity
delta: Model parameter related to choice threshold

Details

This dataset captures individual decision-making processes in a hotel choice experiment. Participants were asked to choose between two hotel options described by three attributes: distance to beach, room size, and number of stars. The dataset includes both the raw choice data and estimated model parameters from the Multi-Attribute Search and Choice (MASC) model.

Source

Gluth, S., Deakin, J., & Rieskamp, J. (2026). A theory of multiattribute search and choice. Psychological Review. doi:10.1037/rev0000614

References

Gluth, S., Deakin, J., & Rieskamp, J. (2026). A theory of multiattribute search and choice. Psychological Review. doi:10.1037/rev0000614

Multi-Attribute Search and Choice (MASC) Model

Description

Implements the MASC model of multi-attribute decision making. This model simulates how people make decisions when comparing options with multiple attributes by sequentially sampling information about different attributes until reaching a decision.

Usage

rMASC(
  data = NULL,
  n = 1,
  n_options = 2,
  n_attributes = 3,
  w = NULL,
  sigma = 1,
  alpha = 3,
  delta = 0.01,
  theta = 0.01,
  lambda = 1,
  max_steps = 100,
  Sigma_true = NULL,
  Sigma_belief = NULL
)

Arguments

data

Optional data frame containing trial-wise attribute values. Each row represents one trial, and columns should be named following the pattern ⁠opt<i>_att<j>⁠ where i is the option number and j is the attribute number. For example, with 2 options and 3 attributes, columns should be: opt1_att1, opt1_att2, opt1_att3, opt2_att1, opt2_att2, opt2_att3. If NULL, generates random values for n trials.

n

Integer. Number of trials to generate when data is NULL (default: 1). Ignored when data is provided.

n_options

Integer. Number of choice options (default: 2).

n_attributes

Integer. Number of attributes per option (default: 3).

w

Numeric vector. Attribute weights summing to 1. If NULL, weights are randomly generated from beta(3/4, 3/4) distribution (default: NULL).

sigma

Numeric. Standard deviation of sampling noise (default: 1).

alpha

Numeric. Controls how strongly fixations follow the myopic search rule. Higher values (>10) make search more deterministic, lower values (near 0) make it more random (default: 3).

delta

Numeric. Amount by which decision threshold increases per fixation (default: 0.01).

theta

Numeric. Initial decision threshold (default: 0.01).

lambda

Numeric. Precision of prior beliefs about attributes (default: 1).

max_steps

Integer. Maximum number of fixations allowed (default: 100).

Sigma_true

Correlation/covariance structure of the generated stimuli (an n_attributes x n_attributes matrix, or a single number giving a uniform off-diagonal correlation). When NULL (default), attributes are independent (identity), reproducing the original MASC behaviour. Ignored when data is supplied (the data are the stimuli).

Sigma_belief

The decision maker's assumed correlation structure between attributes (matrix or single number). This is what enables the multivariate ("MASC-C") belief update: observing one attribute spreads information to correlated attributes via a Kalman update. NULL (default) matches Sigma_true; 0 forces independent (univariate) beliefs. When the resulting matrix is diagonal the model reduces exactly to the original univariate MASC update.

Value

A list containing:

results: Data frame with trial-by-trial results including:
- trial: Trial number
- response: Option chosen by model (1 to n_options)
- best_option: Option with highest weighted value
- correct: Whether response matches best_option
- rt: Number of fixations taken
- prop_fix_opt1, prop_fix_opt2: Proportion of fixations to each option
weights: Vector of attribute weights used
parameters: List of model parameters used (sigma, alpha, delta, theta)
raw: List containing detailed raw data for each trial. Each element corresponds to a trial and includes:
- trial: Trial number
- response: The option chosen by the model (1 to n_options)
- best_option: The option with the highest weighted value
- correct: Boolean indicating if response matches best_option
- rt: Number of fixations taken to reach a decision
- x: Matrix of true attribute values for all options
- opt_values: Vector of computed option values (weighted sums)
- weights: Vector of attribute weights used in this trial
- sigma: Sampling noise parameter used
- alpha: Search sensitivity parameter used
- delta: Threshold increment parameter used
- theta: Initial threshold parameter used
- fix_sequence: Vector showing the sequence of fixations made
- prop_fix_opt: Vector of proportions of fixations to each option
- prop_fix_att: Vector of proportions of fixations to each attribute

References

Gluth, S., Deakin, J., & Rieskamp, J. (2026). A theory of multiattribute search and choice. Psychological Review. doi:10.1037/rev0000614

Examples

# Example 1: Generate 5 random trials
results <- rMASC(n = 5, w = c(0.5, 0.3, 0.2))

# Example 2: Custom attribute values for multiple trials
trial_data <- data.frame(
    # Option 1's attributes across 3 trials
    opt1_att1 = c(4.5, 4.2, 4.8),  # Attribute 1 values
    opt1_att2 = c(3.2, 3.5, 3.1),  # Attribute 2 values
    opt1_att3 = c(2.8, 2.9, 2.7),  # Attribute 3 values
    # Option 2's attributes across 3 trials
    opt2_att1 = c(3.8, 3.9, 3.7),  # Attribute 1 values
    opt2_att2 = c(4.1, 4.0, 4.2),  # Attribute 2 values
    opt2_att3 = c(3.1, 3.3, 3.0)   # Attribute 3 values
)

# Run model with custom weights
results <- rMASC(
    data = trial_data,
    w = c(0.5, 0.3, 0.2)  # weights for attributes
)

# Example 3: Correlated attributes (MASC-C). The decision maker exploits a
# positive correlation structure, so observing one attribute informs beliefs
# about the others ("belief spread").
results <- rMASC(
    n = 20,
    w = c(0.5, 0.3, 0.2),
    Sigma_true = 0.6,    # stimuli are positively correlated
    Sigma_belief = 0.6   # matched beliefs (use 0 for the original MASC model)
)

Package {masc}

masc: Multi-Attribute Search and Choice Model

Description

Details

Author(s)

References

See Also

Myopic Search Rule for MASC Model

Description

Usage

Arguments

Value

Generate Non-dominated Attribute Values

Description

Usage

Arguments

Value

Hotel Choice Experiment Dataset from Gluth et al. (2026)

Description

Usage

Format

`hotelgluth2024`

Details

Source

References

Multi-Attribute Search and Choice (MASC) Model

Description

Usage

Arguments

Value

References

Examples