% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hmetad.R
\name{fit_metad}
\alias{fit_metad}
\title{Fit the meta-d' model using \code{brms} package}
\usage{
fit_metad(
  formula,
  data,
  ...,
  aggregate = TRUE,
  .stimulus = "stimulus",
  .response = "response",
  .confidence = "confidence",
  .joint_response = "joint_response",
  K = NULL,
  distribution = "normal",
  metac_absolute = TRUE,
  stanvars = NULL,
  categorical = FALSE,
  logit = TRUE
)
}
\arguments{
\item{formula}{A model formula for some or all parameters of the \code{metad} brms
family. To display all parameter names for a model with \code{K} confidence
levels, use \code{metad(K)}.}

\item{data}{A tibble containing the data to fit the model.
\itemize{
\item If \code{aggregate}==TRUE, \code{data} should have one row per observation with
columns \code{stimulus}, \code{response}, \code{confidence}, and any other variables in
\code{formula}
\item If \code{aggregate}==FALSE, it should be aggregated to have one row per cell of
the design matrix, with joint type 1/type 2 response counts in a matrix
column (see \code{\link[=aggregate_metad]{aggregate_metad()}}).
}}

\item{...}{Additional parameters passed to the \code{brm} function.}

\item{aggregate}{If \code{TRUE}, automatically aggregate \code{data} by the variables
included in \code{formula} using \code{\link[=aggregate_metad]{aggregate_metad()}}. Otherwise, \code{data} should
already be aggregated.}

\item{.stimulus}{The name of "stimulus" column}

\item{.response}{The name of "response" column}

\item{.confidence}{The name of "confidence" column}

\item{.joint_response}{The name of "joint_response" column}

\item{K}{The number of confidence levels in \code{data}. If \code{NULL}, this is
estimated from \code{data} using the maximum level of either the confidence
column or joint response column.}

\item{distribution}{The noise distribution to use for the signal detection
model. By default, uses a normal distribution with a mean parameterized by
\code{dprime}.}

\item{metac_absolute}{If \code{TRUE}, fix the type 2 criterion to be equal to the
type 1 criterion. Otherwise, equate the criteria relatively such that
metac/metadprime = c/dprime.}

\item{stanvars}{Additional \code{stanvars} to pass to the model code, for example
to define an alternative distribution or a custom model prior (see
\code{\link[brms:stanvar]{brms::stanvar()}}).}

\item{categorical}{If \code{FALSE} (default), use the multinomial likelihood over
aggregated data. If \code{TRUE}, use the categorical likelihood over individual
trials.}

\item{logit}{If \code{TRUE} (default), use the logit parameterization of the
likelihood over the log joint response probabilities. If \code{FALSE}, use the
standard parameterization of the likelihood over the actual joint response
probabilities. In most cases, the logit parameterization should provide
more stable numerical computations, but the standard parameterization might
be preferable in some settings.}
}
\value{
A \code{brmsfit} object containing the fitted model
}
\description{
This function is a wrapper around \code{\link[brms:brm]{brms::brm()}} using a custom family for the
meta-d' model.
}
\details{
\code{fit_metad(formula, data, ...)} is approximately the same as
\code{brm(formula, data=aggregate_metad(data, ...), family=metad(...), stanvars=stanvars_metad(...), ...)}. For some models, it may often be
easier to use the more explicit version than using \code{fit_metad}.
}
\examples{
# check which parameters the model has
metad(3)

# fit a basic model on simulated data
# (use `empty=true` to bypass fitting, *do not use in real analysis*)
fit_metad(N ~ 1, sim_metad(), empty = TRUE)
\donttest{
# fit a basic model on simulated data
fit_metad(N ~ 1, sim_metad())

# fit a model with condition-level effects
fit_metad(
  bf(
    N ~ condition,
    dprime + c + metac2zero1diff + metac2zero2diff +
      metac2one1diff + metac2one1diff ~ condition
  ),
  data = sim_metad_condition()
)
}
}
