make_staninput: Prepare data to fit ideal_adaptor_stanfit via rstan

In hlplab/MVBeliefUpdatr: Fitting, Summarizing, and Visualizing of Gaussian Ideal Observers and Adaptors

Prepare data to fit ideal_adaptor_stanfit via rstan

Description

Take exposure and test data as input, and prepare the data for input into an MVBeliefUpdatr Stan program.

Usage

make_staninput(
  exposure,
  test,
  cues,
  category = "category",
  response = "response",
  group = "group",
  group.unique = NULL,
  lapse_rate = NULL,
  mu_0 = NULL,
  Sigma_0 = NULL,
  control = control_staninput(),
  stanmodel = "NIW_ideal_adaptor",
  verbose = F
)

Arguments

exposure	'tibble' or 'data.frame' with the exposure data. Each row should be an observation of a category, and contain information about the category label, the cue values of the observation, and optionally grouping variables.
test	'tibble' or 'data.frame' with the test data. Each row should be an observation, and contain information about the cue values of the test stimulus and the participant's response.
cues	Names of columns with cue values. Must exist in both exposure and test data.
category	Name of column in exposure data that contains the category label. Can be NULL for unsupervised updating (not yet implemented). (default: "category")
response	Name of column in test data that contains participants' responses. (default: "response")
group	Name of column that contains information about which observations form a group. Typically, this is a variable identifying subjects/participants. Must exist in both exposure and test data. (default: "group")
group.unique	Name of column that uniquely identifies each group with identical exposure. This could be a variable indicating the different conditions in an experiment. Using group.unique is optional, but can be substantially more efficient if many groups share the same exposure. To ignore, set to NULL. (default: NULL)
lapse_rate, mu_0, Sigma_0	Optionally, lapse rate, prior expected category means (mu_0) and/or prior expected category covariance matrices (Sigma_0) for all categories. Lapse rate should be a number between 0 and 1. For mu_0 and Sigma_0, each should be a list, with each element being the expected mean/covariance matrix for a specific category prior to updating. Elements of mu_0 and Sigma_0 should be ordered in the same order as the levels of the category variable in exposure and test. These prior expected means and covariance matrices could be estimated, for example, from phonetically annotated speech recordings (see make_MVG_from_data for a convenient way to do so). Internally, m_0 is then set to mu_0 (so that the expected value of the prior distribution of means is mu_0) and S_0 is set so that the expected value of the inverse-Wishart is Sigma_0 given nu_0. Importantly, Sigma_0 should be convolved with perceptual noise (i.e., add perceptual noise covariance matrix to the category variability covariance matrices when you specify Sigma_0) since the stancode for the inference of the NIW ideal adaptor does not infer category and noise variability separately.
control	A list of control parameters that only experienced users should change since it can change the fitting and interpretation of the model. See control_staninput for details.

Details

It is important to use group to identify individuals that had a specific exposure (or no exposure at all) and specific test trials. You should not use group to identify exposure conditions. Setting group to an exposure condition results in an exposure that concatenates the exposure observations from all subjects in that condition. Typically, this is not what users intend, as it models exposure to the combination of exposure tokens across all subjects, rather than exposure to one set of those exposure tokens. To achieve this intended outcome, use group.unique to identify groups with identical exposure. This will correctly use only one unique instance of the observations that any level of group receives during exposure.

Value

A list consisting of:

• 'data': A data.frame with the exposure and test data after exclusion of NAs and other checks.

• 'staninput': A named list of variables and values to be handed to Stan.

• 'transform_information': A list with information about the transformation that was applied to the data.

See Also

is.ideal_adaptor_staninput

hlplab/MVBeliefUpdatr documentation built on July 5, 2025, 6:42 a.m.