% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/linear_ipcw_analytical.R
\name{linear.power.analytical}
\alias{linear.power.analytical}
\title{Analyze Power for a Linear RMST Model (Analytic)}
\usage{
linear.power.analytical(
  pilot_data,
  time_var,
  status_var,
  arm_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 specifying the name of the time-to-event variable.}

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

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

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

\item{linear_terms}{An optional character vector of other covariate names to include in the model.}

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

\item{alpha}{The significance level for the power calculation (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 the specified sample sizes and their corresponding calculated power.}
\item{results_plot}{A \code{ggplot} object visualizing the power curve.}
\item{results_summary}{A \code{data.frame} summarizing the treatment effect from the pilot data used for the calculation.}
}
\description{
Performs power analysis using a direct formula based on the
asymptotic variance estimator for the linear RMST model.
}
\details{
This function implements the analytic power calculation for the direct linear
regression model of the Restricted Mean Survival Time (RMST) proposed by Tian et al. (2014).
The core of the method is a weighted linear model of the form
\deqn{E[Y_i \mid A_i, \mathbf{Z}_i] = \alpha + \tau A_i + \mathbf{Z}_i^\top \boldsymbol{\gamma}}
where \eqn{Y_i = \min(T_i, L)} is the event time truncated at \eqn{L}, \eqn{A_i} is the
treatment indicator, and \eqn{\tau} is the treatment effect of interest.

To handle right-censoring, the method uses Inverse Probability of Censoring
Weighting (IPCW). The weight for an uncensored individual \code{i} is the inverse
of the probability of remaining uncensored until their event time, \eqn{w_i = \delta_i / \hat{G}(Y_i)},
where \eqn{\hat{G}(t) = P(C > t)} is the Kaplan-Meier estimate of the censoring distribution.

Power is calculated analytically based on the asymptotic properties of the
coefficient estimators. The variance of the treatment effect estimator, \eqn{\hat{\tau}}, is derived from a
robust sandwich variance estimator of the form \eqn{A^{-1}B(A^{-1})'}. In this implementation,
\code{A} is the scaled information matrix \eqn{(X'WX)/n}, and \code{B} is the empirical second moment of the
influence functions, \eqn{(\sum \epsilon_i \epsilon_i')/n}, where \eqn{\epsilon_i} is the influence curve
for observation \code{i}. The resulting variance is used to calculate the standard error for a
given sample size, which in turn is used in the power formula.
}
\examples{
pilot_df <- data.frame(
  time = rexp(100, 0.1),
  status = rbinom(100, 1, 0.7),
  arm = rep(0:1, each = 50),
  age = rnorm(100, 55, 10)
)
power_results <- linear.power.analytical(
  pilot_data = pilot_df,
  time_var = "time",
  status_var = "status",
  arm_var = "arm",
  linear_terms = "age",
  sample_sizes = c(100, 200, 300),
  L = 10
)
print(power_results$results_data)
print(power_results$results_plot)
}
