plot_expected_categories: Plot expected categories of ideal adaptor stanfit

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

Plot expected categories of ideal adaptor stanfit

Description

Plot bivariate Gaussian categories expected given the parameters inferred by incremental Bayesian belief- updating (IBBU) for an ideal adaptor. Specifically, the categories are derived by marginalizing over the uncertainty represented by the posterior MCMC samples. Two methods are available (specified by 'type'), which differ in their computational demands and speed.

Plot bivariate Gaussian categories expected given NIW belief(s). One NIW belief describes the uncertainty about the category statistics of all categories. This includes the m (the mean of category means \mu), S (the scattermatrix), kappa (the strength of the belief in m) and nu (the strength of the belief in S).

Plot univariate Gaussian categories expected given NIW belief(s). One NIW belief describes the uncertainty about the category statistics of all categories. This includes the m (the mean of category means \mu), S (the scattermatrix), kappa (the strength of the belief in m) and nu (the strength of the belief in S). For the univariate case, m and S are scalars \insertCite@see @murphy2012 p. 136MVBeliefUpdatr.

Usage

plot_expected_categories(model, ...)

plot_expected_categories_contour(model, ...)

plot_expected_categories_density(model, ...)

plot_expected_categories_contour2D(model, ...)

plot_expected_categories_density1D(model, ...)

plot_expected_categories_density2D(model, ...)

## S3 method for class 'ideal_adaptor_stanfit'
plot_expected_categories(model, type, ...)

## S3 method for class 'ideal_adaptor_stanfit'
plot_expected_categories_contour(model, cues = get_cue_levels(model), ...)

## S3 method for class 'ideal_adaptor_stanfit'
plot_expected_categories_density(model, cues = get_cue_levels(model), ...)

## S3 method for class 'NIW_ideal_adaptor'
plot_expected_categories_contour2D(
  x,
  levels = c(1/2, 2/3, 4/5, 9/10, 19/20),
  data.exposure = NULL,
  data.test = NULL,
  facet_rows_by = NULL,
  facet_cols_by = NULL,
  facet_wrap_by = NULL,
  animate_by = NULL,
  animation_follow = F,
  category.ids = NULL,
  category.labels = NULL,
  category.colors = NULL,
  ...
)

## S3 method for class 'tbl_df'
plot_expected_categories_contour2D(...)

## S3 method for class 'ideal_adaptor_stanfit'
plot_expected_categories_contour2D(
  model,
  categories = get_category_levels(model),
  groups = get_group_levels(model, include_prior = T),
  cues = get_cue_levels(model),
  plot.test = T,
  plot.exposure = F,
  annotate_inferred_category_means = c("rug", "text"),
  untransform_cues = FALSE,
  levels = plogis(seq(-15, qlogis(0.95), length.out = 20)),
  category.colors = get_default_colors("category", categories)
)

## S3 method for class 'NIW_ideal_adaptor'
plot_expected_categories_density1D(
  x,
  data.exposure = NULL,
  data.test = NULL,
  facet_rows_by = NULL,
  facet_cols_by = NULL,
  facet_wrap_by = NULL,
  animate_by = NULL,
  animation_follow = F,
  xlim,
  ylim = NULL,
  x.expand = c(0, 0),
  category.ids = NULL,
  category.labels = NULL,
  category.colors = NULL,
  category.linetypes = NULL,
  ...
)

## S3 method for class 'tbl_df'
plot_expected_categories_density1D(...)

## S3 method for class 'ideal_adaptor_stanfit'
plot_expected_categories_density1D(
  model,
  categories = get_category_levels(model),
  groups = get_group_levels(model, include_prior = T),
  cues = get_cue_levels(model),
  ndraws = NULL,
  plot.test = T,
  plot.exposure = F,
  annotate_inferred_category_means = c("rug", "text"),
  untransform_cues = FALSE,
  category.colors = get_default_colors("category", categories),
  xlim = NULL,
  resolution = 101
)

## S3 method for class 'ideal_adaptor_stanfit'
plot_expected_categories_density2D(
  model,
  categories = get_category_levels(model),
  groups = get_group_levels(model, include_prior = T),
  cues = get_cue_levels(model),
  ndraws = NULL,
  plot.test = T,
  plot.exposure = F,
  annotate_inferred_category_means = c("rug", "text"),
  untransform_cues = FALSE,
  category.colors = get_default_colors("category", categories),
  xlim = NULL,
  ylim = NULL,
  resolution = 25
)

Arguments

model	An ideal adaptor stanfit object.
...	additional arguments to geom_line.
type	Either '"contour"' or '"density"', specifying the type of plot. Note that the contour plot is *much* faster. It simply gets the expected values of mu (based on the NIW parameter m) and Sigma (based on the NIW parameters S and nu) at each MCMC draw, and then averages over all MCMC draws. The plotted categories represent those means of the expected mu and Sigma. The density plot instead calculates the posterior predictive for each MCMC draw (i.e, the multivariate Student-T density based on the NIW parameters m, S, kappa, nu), and then averages those densities. Since this is done for *all* points defined by the data.grid this can be rather computationally expensive and slow.
x	An NIW_belief or NIW_beliefs object.
levels	Levels of the confidence ellipses. (default: .5, .66, .8, .9., and .95)
data.exposure	Optional tibble or data.frame that contains exposure data to be plotted. (default: 'NULL')
data.test	Optional tibble or data.frame that contains test data to be plotted. (default: 'NULL')
facet_rows_by, facet_cols_by, facet_wrap_by, animate_by	Which group variables, if any, should be used for faceting and/or animation? (defaults: 'NULL')
animation_follow	Should the animation follow the data (zoom in and out)? (default: 'FALSE')
category.ids	Vector of category IDs to be plotted or leave 'NULL' to plot all groups. (default: 'NULL')
category.labels	Vector of group labels of same length as 'category.ids' or 'NULL' to use defaults. (default: 'NULL')
category.colors	Vector of colors of same length as category.ids or 'NULL' to use defaults. (default: 'NULL')
categories, groups, cues	Character vector of categories, groups, and cues to be plotted. (default: all categories, groups, and cues in the model will be plotted)
plot.test, plot.exposure	Should the test and/or exposure stimuli be plotted? (default: 'TRUE' for 'plot.test', 'FALSE' for 'plot.exposure') The test items are plotted as black points. The exposure mean is plotted as point, and the .95 interval of cue distributions during exposure are plotted as dashed ellipse in the same color as the expected categories.
annotate_inferred_category_means	Character vector indicating whether the location and value of the mean be indicated through data rugs ('"rug"') and/or text labels ('"text"')? Set to NULL to ignore. (default: 'c("rug", "text")')
untransform_cues	DEPRECATED. Should m_0 and S_0 be transformed back into the original cue space? (default: 'FALSE')
xlim, ylim	Limits for the x- and y-axis.
category.linetypes	Vector of linetypes of same length as category.ids or 'NULL' to use defaults. (default: 'NULL') Currently being ignored.
ndraws	Number of draws from posterior to use for plot, or 'NULL' if all draws are to be returned. (default: 'NULL')
resolution	For density plots. How many steps along x and y should be calculated? Note that computational complexity increases quadratically with resolution. (default: 25)
data.grid.xlim, data.grid.ylim, data.grid.resolution	Used only if 'type' is '"density"'. Limits for x- and y-axis as well as resolution of the data.grid, defining the range over which the posterior predictive (multivariate Student-T density) is calculated. Note that the number of densities to calculate is a *quadratic* function of 'data.grid.resolution'. The default for 'data.grid.resolution' is 10, corresponding to 100 densities to be calculated for each MCMC draw.

Details

Typically, the categories, groups, and cues are automatically added to the fit during the creation of the fit. If necessary, however, it is possible to use recover_types on the stanfit object to add or change these levels later.

It is possible to hand more than one NIW belief to this function, and to facet or animate by variables that uniquely identify the different beliefs. For example, one can plot different priors for different talkers (grouping by talker), or different posteriors for different exposure conditions (grouping by exposure condition), the incremental updating of NIW beliefs (grouping by observations), or any combinations of these.

It is possible to hand more than one NIW belief to this function, and to facet or animate by variables that uniquely identify the different beliefs. For example, one can plot different priors for different talkers (grouping by talker), or different posteriors for different exposure conditions (grouping by exposure condition), the incremental updating of NIW beliefs (grouping by observations), or any combinations of these.

Value

ggplot object.

ggplot object.

ggplot object.

References

\insertRef

murphy2012MVBeliefUpdatr

See Also

TBD

TBD

TBD

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