% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ild_power.R
\name{ild_power}
\alias{ild_power}
\title{Simulation-based power analysis for a fixed effect in ILD models}
\usage{
ild_power(
  formula,
  n_sim = 500L,
  n_id,
  n_obs_per,
  effect_size,
  test_term = NULL,
  alpha = 0.05,
  ar1 = FALSE,
  seed = 42L,
  return_sims = FALSE,
  verbose = TRUE,
  ...
)
}
\arguments{
\item{formula}{Fixed-effects formula including the predictor to power for
and random effects, e.g. \code{y ~ x + (1 | id)}. For \code{ar1 = TRUE},
use a fixed-only formula (random passed internally).}

\item{n_sim}{Integer. Number of simulation replications (default 500).}

\item{n_id}{Integer. Number of persons per replication.}

\item{n_obs_per}{Integer. Observations per person per replication.}

\item{effect_size}{Numeric. True coefficient for \code{test_term} in the DGP.}

\item{test_term}{Character or \code{NULL}. Which fixed-effect term to test.
If \code{NULL}, taken as the first non-intercept fixed-effect term from
the model (inferred from the formula).}

\item{alpha}{Numeric. Significance level for rejection (default 0.05).}

\item{ar1}{Logical. If \code{TRUE}, fit with nlme and residual AR1/CAR1
(default \code{FALSE}).}

\item{seed}{Integer. Base random seed; replication \code{i} uses \code{seed + i}.}

\item{return_sims}{Logical. If \code{TRUE}, include a tibble of per-run
estimate, std_error, p_value, rejected in the result (default \code{FALSE}).}

\item{verbose}{Logical. If \code{TRUE}, message progress (default \code{TRUE}).}

\item{...}{Passed to [ild_simulate()] (e.g. \code{irregular}, \code{wp_effect},
\code{bp_effect}) and to [ild_lme()].}
}
\value{
A list: \code{power} (proportion of converged runs with p < alpha),
  \code{n_sim}, \code{n_reject}, \code{n_converged}, \code{n_failed},
  \code{alpha}, \code{test_term}. If \code{return_sims = TRUE}, also
  \code{sim_results} (tibble of per-run results).
}
\description{
Estimates empirical power by repeatedly simulating data with a known effect
(via [ild_simulate()] plus one added predictor), fitting with [ild_lme()],
and counting the proportion of runs where the target term is significant
(Wald p < alpha). The workflow (simulate, fit, reject/retain) mirrors
simulation-based power in packages like mixpower; \code{ild_power()} is
focused on ILD and \code{ild_lme()}. For multi-parameter grids, LRT, or
general LMMs, consider mixpower.
}
\details{
The data-generating process adds one predictor (name from \code{test_term})
as standard normal and adds \code{effect_size * predictor} to the outcome
on top of the base [ild_simulate()] DGP (id, time, y). No change to
\code{ild_simulate()} is required.

For \code{ar1 = FALSE} (lmer), the lme4 backend does not report p-values;
inference for the test term uses a Wald z-approximation (estimate / SE)
so that power is still computed. For \code{ar1 = TRUE} (nlme), p-values
come from the model summary.
}
\examples{
set.seed(42)
res <- ild_power(
  formula = y ~ x + (1 | id),
  n_sim = 25L,
  n_id = 15L,
  n_obs_per = 10L,
  effect_size = 0.3,
  seed = 42L,
  verbose = FALSE
)
res$power
res$n_reject
}
\seealso{
[ild_recovery_metrics()] to summarize bias, RMSE, and coverage from
  \code{return_sims}. \href{../doc/benchmark-simulation-recovery.html}{\code{vignette("benchmark-simulation-recovery", package = "tidyILD")}}
  (worked example).
}
