% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/additive_stratified_analytical.R
\name{additive.power.analytical}
\alias{additive.power.analytical}
\title{Analyze Power for a Stratified Additive RMST Model (Analytic)}
\usage{
additive.power.analytical(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  strata_var,
  sample_sizes,
  linear_terms = NULL,
  L,
  alpha = 0.05,
  verbose = FALSE
)
}
\arguments{
\item{pilot_data}{A \code{data.frame} containing pilot study data.}

\item{time_var}{A character string for the time-to-event variable.}

\item{status_var}{A character string for the event status variable (1=event, 0=censored).}

\item{arm_var}{A character string for the treatment arm variable (1=treatment, 0=control).}

\item{strata_var}{A character string for the stratification variable.}

\item{sample_sizes}{A numeric vector of sample sizes \emph{per stratum} to calculate power for.}

\item{linear_terms}{An optional character vector of other covariate names.}

\item{L}{The numeric value for the RMST truncation time.}

\item{alpha}{The significance level (Type I error rate).}

\item{verbose}{Logical; if \code{TRUE}, emit progress messages. Default \code{FALSE}.}
}
\value{
A \code{list} containing:
\item{results_data}{A \code{data.frame} with specified sample sizes and corresponding powers.}
\item{results_plot}{A \code{ggplot} object visualizing the power curve.}
}
\description{
Performs power analysis for a stratified, additive RMST model using the
analytic variance estimator based on the method of Zhang & Schaubel (2024).
}
\details{
This function computes power for the semiparametric additive RMST model
\eqn{\mu_{ij} = \mu_{0j} + \beta'Z_i}, where \code{i} indexes subjects and \code{j}
indexes strata.

The method uses Inverse Probability of Censoring Weighting (IPCW), with
weights derived from a stratified Cox model for the censoring times. The
regression coefficient \eqn{\hat{\beta}} is estimated by centering the
covariates and RMST values within each stratum and then solving the
resulting estimating equations in closed form.

Power is obtained from the asymptotic sandwich variance of \eqn{\hat{\beta}}.
This implementation uses the robust variance estimator
\eqn{A_n^{-1} B_n (A_n^{-1})'}, where \eqn{A_n} and \eqn{B_n} are empirical
estimates of the variance components.
}
\examples{
set.seed(123)
pilot_df_strat <- data.frame(
 time = rexp(150, 0.1),
 status = rbinom(150, 1, 0.8),
 arm = rep(0:1, each = 75),
 region = factor(rep(c("A", "B", "C"), each = 50)),
 age = rnorm(150, 60, 10)
)
# Introduce an additive treatment effect
pilot_df_strat$time[pilot_df_strat$arm == 1] <-
  pilot_df_strat$time[pilot_df_strat$arm == 1] + 1.5

power_results <- additive.power.analytical(
  pilot_data = pilot_df_strat,
  time_var = "time", status_var = "status", arm_var = "arm", strata_var = "region",
  sample_sizes = c(100, 150, 200),
  linear_terms = "age",
  L = 12
)
print(power_results$results_data)
print(power_results$results_plot)

}
