% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mean_confidence_draws.R
\name{mean_confidence_draws}
\alias{mean_confidence_draws}
\alias{add_mean_confidence_draws}
\alias{mean_confidence_rvars}
\alias{add_mean_confidence_rvars}
\title{Obtain posterior draws of mean confidence}
\usage{
mean_confidence_draws(
  object,
  newdata,
  ...,
  by_stimulus = TRUE,
  by_response = TRUE,
  by_correct = FALSE
)

add_mean_confidence_draws(newdata, object, ...)

mean_confidence_rvars(
  object,
  newdata,
  ...,
  by_stimulus = TRUE,
  by_response = TRUE,
  by_correct = FALSE
)

add_mean_confidence_rvars(newdata, object, ...)
}
\arguments{
\item{object}{The \code{brms} model with the \code{metad} family}

\item{newdata}{A data frame from which to generate posterior predictions}

\item{...}{Additional arguments to \link[tidybayes:epred_draws]{tidybayes::epred_draws} or
\link[tidybayes:epred_rvars]{tidybayes::epred_rvars}}

\item{by_stimulus}{If TRUE, predict mean confidence separately by stimulus.
Otherwise, predict mean confidence averaging over stimuli. Ignored if
\code{by_correct==TRUE}.}

\item{by_response}{If TRUE, predict mean confidence separately by response
Otherwise, predict mean confidence averaging over responses. Ignored if
\code{by_correct==TRUE}.}

\item{by_correct}{If TRUE, predict mean confidence separately for correct and
incorrect responses.}
}
\value{
a tibble containing posterior draws of mean confidence with the
following columns:
\itemize{
\item \code{.row}: the row of \code{newdata}
\item \code{.chain}, \code{.iteration}, \code{.draw}: for \code{mean_confidence_draws} and \code{add_mean_confidence_draws}, identifiers for the posterior sample
\item \code{stimulus}: indicator for stimulus presence (if \code{by_stimulus==TRUE & by_correct==FALSE})
\item \code{response}: indicator for type 1 response (if \code{by_response==TRUE & by_correct==FALSE})
\item \code{correct}: indicator for the accuracy of the type 1 response (if \code{by_correct==TRUE})
\item \code{.epred}: the predicted mean confidence
}
}
\description{
Computes posterior mean confidence conditional on stimulus and
response (\eqn{\mathbb{E}[C \;\vert\; S=s,R=r]}), stimulus (averaging over
responses, \eqn{\mathbb{E}[C \;\vert\; S=s]}), response (averaging over
stimuli, \eqn{\mathbb{E}[C \;\vert\; R=r]}), neither (averaging over
stimuli and responses, \eqn{\mathbb{E}[C]}), or accuracy (\eqn{\mathbb{E}[C
  \;\vert\; A=(r=s)]}). For \code{mean_confidence_draws} and
\code{add_mean_confidence_draws}, estimates are returned in a tidy tibble with
one row per posterior draw, stimulus, and response. For
\code{mean_confidence_rvars} and \code{add_mean_confidence_rvars}, estimates are
returned as \link[posterior:rvar]{posterior::rvar}s, with one row per row in \code{newdata}.

\code{add_mean_confidence_draws} is an alias of \code{mean_confidence_draws} with
argument order swapped.
}
\examples{
\donttest{
newdata <- tidyr::tibble(.row = 1)

# compute mean confidence by stimulus and response
# equivalent to `add_mean_confidence_draws(newdata, example_model())`
mean_confidence_draws(example_model(), newdata)

# compute mean confidence by stimulus
# equivalent to `add_mean_confidence_draws(newdata, example_model(), by_response = FALSE)`
mean_confidence_draws(example_model(), newdata, by_response = FALSE)

# compute mean confidence by response
# equivalent to `add_mean_confidence_draws(newdata, example_model(), by_stimulus = FALSE)`
mean_confidence_draws(example_model(), newdata, by_stimulus = FALSE)

# compute mean confidence by accuracy
# equivalent to `add_mean_confidence_draws(newdata, example_model(), by_correct = TRUE)`
mean_confidence_draws(example_model(), newdata, by_correct = TRUE)

# compute mean confidence averaging over stimuli and responses
# equivalent to `add_mean_confidence_draws(newdata, example_model(), ...)`
mean_confidence_draws(example_model(), newdata, by_stimulus = FALSE, by_response = FALSE)

# use `posterior::rvar` for increased efficiency
# equivalent to `add_mean_confidence_rvars(newdata, example_model())`
mean_confidence_rvars(example_model(), newdata)
}
}
\seealso{
\code{\link[tidybayes:epred_draws]{tidybayes::epred_draws()}}, \code{\link[tidybayes:epred_rvars]{tidybayes::epred_rvars()}}
}
