% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/estimate_grouplevel.R, R/reshape_grouplevel.R
\name{estimate_grouplevel}
\alias{estimate_grouplevel}
\alias{estimate_grouplevel.default}
\alias{estimate_grouplevel.brmsfit}
\alias{reshape_grouplevel}
\alias{reshape_grouplevel.estimate_grouplevel}
\title{Group-specific parameters of mixed models random effects}
\usage{
estimate_grouplevel(model, ...)

\method{estimate_grouplevel}{default}(model, type = "random", ...)

\method{estimate_grouplevel}{brmsfit}(
  model,
  type = "random",
  dispersion = TRUE,
  test = NULL,
  diagnostic = NULL,
  ...
)

reshape_grouplevel(x, ...)

\method{reshape_grouplevel}{estimate_grouplevel}(x, indices = "all", group = NULL, ...)
}
\arguments{
\item{model}{A mixed model with random effects.}

\item{...}{Other arguments passed to \code{\link[parameters:model_parameters]{parameters::model_parameters()}}.}

\item{type}{String, describing the type of estimates that should be returned.
Can be \code{"random"}, \code{"total"}, or \code{"marginal"} (experimental).
\itemize{
\item If \code{"random"} (default), the coefficients correspond to the conditional
estimates of  the random effects (as they are returned by \code{lme4::ranef()}).
They typically correspond to the deviation of each individual group from
their fixed effect (assuming the random effect is also included as a fixed
effect). As such, a coefficient close to 0 means that the participants'
effect is the same as the population-level effect (in other words, it is
"in the norm").
\item If \code{"total"}, it will return the sum of the random effect and its
corresponding fixed effects, which internally relies on the \code{coef()} method
(see \code{?coef.merMod}). Note that \code{type = "total"} yet does not return
uncertainty indices (such as SE and CI) for models from \emph{lme4} or
\emph{glmmTMB}, as the necessary information to compute them is not yet
available. However, for Bayesian models, it is possible to compute them.
\item If \code{"marginal"} (experimental), it returns marginal group-levels
estimates. The random intercepts are computed using marginal means (see
\code{\link[=estimate_means]{estimate_means()}}), and the random slopes using marginal effects (see
\code{\link[=estimate_slopes]{estimate_slopes()}}). This method does not directly extract the parameters
estimated by the model, but recomputes them using model predictions. While
this is more computationally intensive, one of the benefits include
interpretability: the random intercepts correspond to the "mean" value of
the outcome for each group, and the random slopes correspond to the direct
average "effect" of the predictor for each random group. Note that in this
case, the group-level estimates are not technically "intercepts" or model
parameters, but marginal average levels and effects.
}}

\item{dispersion, test, diagnostic}{Arguments passed to
\code{\link[parameters:model_parameters]{parameters::model_parameters()}} for Bayesian models. By default, it won't
return significance or diagnostic indices (as it is not typically very
useful).}

\item{x}{The output of \code{estimate_grouplevel()}.}

\item{indices}{A character vector containing the indices (i.e., which
columns) to extract (e.g., "Coefficient", "Median").}

\item{group}{The name of the random factor to select as string value (e.g.,
\code{"Participant"}, if the model was \code{y ~ x + (1|Participant)}.}
}
\description{
Extract random parameters of each individual group in the context of mixed
models, commonly referred to as BLUPs (Best Linear Unbiased Predictors).
Can be reshaped to be of the same dimensions as the original data,
which can be useful to add the random effects to the original data.
}
\details{
Unlike raw group means, BLUPs apply shrinkage: they are a compromise between
the group estimate and the population estimate. This improves generalizability
and prevents overfitting.
}
\examples{
\dontshow{if (all(insight::check_if_installed(c("see", "lme4"), quietly = TRUE)) && packageVersion("insight") > "1.1.0" && packageVersion("parameters") > "0.24.1") withAutoprint(\{ # examplesIf}
# lme4 model
data(mtcars)
model <- lme4::lmer(mpg ~ hp + (1 | carb), data = mtcars)
random <- estimate_grouplevel(model)

# Show group-specific effects
random

# Visualize random effects
plot(random)

# Reshape to wide data...
reshaped <- reshape_grouplevel(random, group = "carb", indices = c("Coefficient", "SE"))

# ...and can be easily combined with the original data
alldata <- merge(mtcars, reshaped)

# overall coefficients
estimate_grouplevel(model, type = "total")
\dontshow{\}) # examplesIf}
}
