% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ild_heterogeneity.R
\name{ild_heterogeneity}
\alias{ild_heterogeneity}
\alias{ild_heterogeneity.lmerMod}
\alias{ild_heterogeneity.lme}
\alias{ild_heterogeneity_stratified}
\alias{ild_tidy.ild_heterogeneity}
\alias{ild_autoplot.ild_heterogeneity}
\alias{ild_heterogeneity.brmsfit}
\title{Heterogeneity and person-specific effects from mixed models}
\usage{
ild_heterogeneity(fit, ...)

\method{ild_heterogeneity}{lmerMod}(
  fit,
  term = NULL,
  group = NULL,
  threshold = NULL,
  scale = c("raw", "sd_x", "sd_y"),
  conf_level = 0.95,
  ...
)

\method{ild_heterogeneity}{lme}(
  fit,
  term = NULL,
  group = NULL,
  threshold = NULL,
  scale = c("raw", "sd_x", "sd_y"),
  conf_level = 0.95,
  ...
)

ild_heterogeneity_stratified(formula, data, subgroup, min_n_id = 5L, ...)

\method{ild_tidy}{ild_heterogeneity}(x, ...)

\method{ild_autoplot}{ild_heterogeneity}(x, type = c("caterpillar", "histogram"), term = NULL, ...)

\method{ild_heterogeneity}{brmsfit}(
  fit,
  term = NULL,
  group = NULL,
  threshold = NULL,
  scale = c("raw", "sd_x", "sd_y"),
  n_draws = 500L,
  ...
)
}
\arguments{
\item{fit}{A fitted \code{lmerMod}, \code{lme}, or \code{brmsfit} (from [ild_brms()]).}

\item{...}{Passed to [ild_lme()].}

\item{term}{Which random-effect term to plot (required if multiple).}

\item{group}{Name of the grouping factor in \code{ranef(fit)} to use (default first).}

\item{threshold}{Optional numeric; with \code{scale}, proportion of person-specific
**total** coefficients exceeding this threshold is reported in \code{summary}.}

\item{scale}{If \code{threshold} is set: \code{"raw"} (default), \code{"sd_x"} (multiply
threshold by residual SD of a focal predictor from model frame), or \code{"sd_y"}
(multiply by SD of response). Only used when a single numeric predictor is found
for \code{sd_x} / \code{sd_y} heuristics.}

\item{conf_level}{For \code{lmerMod}, Wald interval level for conditional modes (normal approx.).}

\item{formula, data}{Passed to [ild_lme()] within each subgroup.}

\item{subgroup}{Character name of a column in \code{data} defining subgroups.}

\item{min_n_id}{Minimum number of distinct persons required in a subgroup.}

\item{x}{An \code{ild_heterogeneity} object.}

\item{type}{\code{"caterpillar"} (default) or \code{"histogram"}.}

\item{n_draws}{For \code{brmsfit}, number of posterior draws for summaries (capped).}
}
\value{
An object of class \code{ild_heterogeneity}: a list with \code{meta}, \code{random_effects}
  (long tibble), \code{varcorr} (tibble), \code{summary} (per-term metrics), and \code{fit}.

A tibble with one row per successful subgroup fit, including key columns from
  \code{ild_heterogeneity()$summary} flattened (\code{subgroup_level}, \code{term}, etc.).
  This is a **descriptive** comparison across refits, not a formal test of variance heterogeneity.
}
\description{
Summarizes **conditional modes** (empirical Bayes / BLUP deviations) and
**person-specific coefficients** (\code{fixef + ranef}) for hierarchical models
fit with [ild_lme()] or [ild_brms()]. Outputs are labeled as **partial-pooling**
estimates; they are not the same as no-pooling separate regressions (see
[ild_person_model()]) or population-average fixed effects alone.
}
\section{Methods (by generic)}{
\itemize{
\item \code{ild_tidy(ild_heterogeneity)}: Tidy long table of person-level random effects (for \code{ild_heterogeneity} objects).

\item \code{ild_autoplot(ild_heterogeneity)}: Caterpillar or histogram of person-specific effects.

}}
\seealso{
[ild_tidy.ild_heterogeneity()], [ild_autoplot.ild_heterogeneity()],
  [ild_heterogeneity_stratified()], [ild_person_model()]
}
