% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/linear_ipcw_boot.R
\name{linear.power.boot}
\alias{linear.power.boot}
\title{Analyze Power for a Linear RMST Model via Simulation}
\usage{
linear.power.boot(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  sample_sizes,
  linear_terms = NULL,
  L,
  n_sim = 1000,
  alpha = 0.05,
  verbose = FALSE
)
}
\arguments{
\item{pilot_data}{A \code{data.frame} with 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.}

\item{arm_var}{A character string for the treatment arm variable.}

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

\item{linear_terms}{Optional character vector of other covariates for the linear model.}

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

\item{n_sim}{The number of bootstrap simulations to run for each sample size.}

\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} of sample sizes and corresponding estimated power.}
\item{results_plot}{A \code{ggplot} object visualizing the power curve.}
\item{results_summary}{A \code{data.frame} with summary statistics for the estimated treatment effect from the largest sample size simulation.}
}
\description{
Performs a power analysis for given sample sizes based on the direct
linear regression model for RMST, using a bootstrap simulation approach.
}
\details{
This function estimates power by generating a number of bootstrap
samples (\code{n_sim}) from the provided pilot data by resampling with replacement.
For each bootstrap sample, it performs the following steps:
\enumerate{
\item Estimates the censoring distribution using the Kaplan-Meier method (\code{survival::survfit}).
\item Calculates Inverse Probability of Censoring Weights (IPCW) for each observation.
\item Fits a weighted linear model (\code{stats::lm}) to the RMST of the uncensored subjects.
\item Extracts the p-value for the treatment \code{arm_var} coefficient.
}

The final power for a given sample size is the proportion of the \code{n_sim} simulations
where this p-value is less than the significance level \code{alpha}. This simulation-based
approach can be useful when analytic approximations are less reliable, but it can
be computationally intensive.
}
\note{
\code{status_var} should be \code{1} for an event, \code{0} for censored. \code{arm_var}
should be \code{1} for treatment, \code{0} for control.
}
\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, 60, 8)
)
# Introduce a treatment effect for a more interesting example
pilot_df$time[pilot_df$arm == 1] <- pilot_df$time[pilot_df$arm == 1] * 1.5

power_results <- linear.power.boot(
  pilot_data = pilot_df,
  time_var = "time",
  status_var = "status",
  arm_var = "arm",
  linear_terms = "age",
  sample_sizes = c(100, 150, 200),
  L = 10,
  n_sim = 200 # Use more simulations in practice (e.g., 1000)
)
print(power_results$results_data)
print(power_results$results_plot)
}
