infer_NIW_ideal_adaptor: Infer NIW ideal adaptor

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

Infer NIW ideal adaptor

Description

Infers a posterior distribution of NIW_ideal _adaptors from the input data using rstan/stan. The function can take two types of inputs: an input list, as prepared by compose_data_to_infer_NIW_ideal_adaptor, or the exposure and test data, the names of the cues, category, and response columns (and optionally group and/or block columns).

Usage

infer_NIW_ideal_adaptor(
  exposure = NULL,
  test = NULL,
  cues = NULL,
  category = NULL,
  response = NULL,
  group = NULL,
  group.unique = NULL,
  center.observations = TRUE,
  scale.observations = TRUE,
  pca.observations = FALSE,
  pca.cutoff = 1,
  lapse_rate = NULL,
  mu_0 = NULL,
  Sigma_0 = NULL,
  tau_scale = 0,
  L_omega_scale = 0,
  untransform_fit = TRUE,
  input = NULL,
  sample = TRUE,
  file = NULL,
  model = NULL,
  use_univariate_updating = FALSE,
  verbose = FALSE,
  ...
)

infer_prior_beliefs(
  exposure = NULL,
  test = NULL,
  cues = NULL,
  category = NULL,
  response = NULL,
  group = NULL,
  group.unique = NULL,
  center.observations = TRUE,
  scale.observations = TRUE,
  pca.observations = FALSE,
  pca.cutoff = 1,
  lapse_rate = NULL,
  mu_0 = NULL,
  Sigma_0 = NULL,
  tau_scale = 0,
  L_omega_scale = 0,
  untransform_fit = TRUE,
  input = NULL,
  sample = TRUE,
  file = NULL,
  model = NULL,
  use_univariate_updating = FALSE,
  verbose = FALSE,
  ...
)

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)
center.observations	Should the data be centered based on cues' means during exposure? Note that the cues' means used for centering are calculated after aggregating the data to all unique combinations specified by group.unique. These means are only expected to be the same as the standard deviations over the entire exposure data if the exposure data are perfectly balanced with regard to group.unique. Centering will not affect the inferred correlation or covariance matrices but it will affect the absolute position of the inferred means. The relative position of the inferred means remains unaffected. If TRUE and mu_0 is specified, mu_0 will also be centered (Sigma_0 is not affected by centering and thus not changed). (default: TRUE)
scale.observations	Should the data be standardized based on cues' standard deviation during exposure? Note that the cues' standard deviations used for scaling are calculated after aggregating the data to all unique combinations specified by group.unique. These standard deviations are only expected to be the same as the standard deviations over the entire exposure data if the exposure data are perfectly balanced with regard to group.unique. Scaling will not affect the inferred correlation matrix, but it will affect the inferred covariance matrix because it affects the inferred standard deviations. It will also affect the absolute position of the inferred means. The relative position of the inferred means remains unaffected. If TRUE and mu_0 and Sigma_0 are specified, mu_0 and Sigma_0 will also be scaled. (default: 'TRUE')
pca.observations	Should the data be transformed into orthogonal principal components? (default: FALSE)
pca.cutoff	Determines which principal components are handed to the MVBeliefUpdatr Stan program: all components necessary to explain at least the pca.cutoff of the total variance. (default: .95) Ignored if pca.observation = FALSE. (default: 1)
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.
untransform_fit	Logical flag indicating whether the samples of the model should be transformed back into the original cue space by applying the untransform function. (default: TRUE)
input	A list of the type that would be returned by compose_data_to_infer_NIW_ideal_adaptor. This list can be provided *instead* of the arguments required by compose_data_to_infer_NIW_ideal_adaptor.
sample	Should the model be fit and sampled from?
file	Either NULL or a character string. In the latter case, the fitted model object is saved via saveRDS in a file named after the string supplied in file. The .rds extension is added automatically. If the file already exists, the model from that file will be loaded and returned instead of refitting the model. As existing files won't be overwritten, you have to manually remove the file in order to refit and save the model under an existing file name. The file name is stored in the NIW_ideal_adaptor_stanfit object for later use. (default: NULL)
model	Name of stanmodel that should be used. Overrides any default selection.
use_univariate_updating	Should legacy univariate updating be used? Will throw an error if used in conjunction with multiple cues. (default: FALSE)
...	Additional parameters are passed to sampling

Value

NIW_ideal_adaptor_stanfit object with the fitted stan model. In interpreting the inferred parameters, it should be kept in mind that the inferred scatter matrix S_0 includes variability from internal perceptual and/or external environmental noise, in addition to the motor noise that is reflected in production data. This also implies that, if Sigma_0 is provided by the user it should be convolved with perceptual noise. This is particularly important if the data you're fitting contains test phases without exposure (e.g., pre-exposure tests). Make sure to read the notes about the Sigma_0 argument in the help page on compose_data_to_infer_NIW_ideal_adaptor.

See Also

is.NIW_ideal_adaptor_stanfit for information about NIW_ideal_adaptor_stanfit objects, add_ibbu_stanfit_draws to draw samples from the stanfit.

hlplab/MVBeliefUpdatr documentation built on March 29, 2025, 10:42 p.m.