% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/additive_gam_boot.R
\name{GAM.power.boot}
\alias{GAM.power.boot}
\title{Calculate Power for a Semiparametric Additive RMST Model via Simulation}
\usage{
GAM.power.boot(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  strata_var = NULL,
  sample_sizes,
  linear_terms = NULL,
  smooth_terms = NULL,
  L,
  n_sim = 1000,
  alpha = 0.05,
  parallel.cores = 1,
  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{strata_var}{An optional character string for a stratification variable.}

\item{sample_sizes}{A numeric vector of sample sizes per arm/stratum.}

\item{linear_terms}{Optional character vector of covariates with a linear effect.}

\item{smooth_terms}{Optional character vector of covariates with a non-linear effect.}

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

\item{n_sim}{Number of bootstrap simulations.}

\item{alpha}{The significance level.}

\item{parallel.cores}{Number of cores for parallel processing.}

\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 a summary of the estimated treatment effect.}
}
\description{
Performs a power analysis for given sample sizes using a flexible,
semiparametric additive model for the RMST based on pseudo-observations.
}
\details{
This function estimates power by bootstrap resampling the pilot data,
computing RMST pseudo-observations, fitting a semiparametric additive model,
and recording whether the treatment effect is significant. If \code{strata_var}
is supplied, resampling is carried out within strata. The model formula can
include linear terms, non-linear smooth terms (\code{s()}), and interactions.

Power is estimated as the proportion of simulations with a treatment-effect
p-value below \code{alpha}. This pseudo-observation approach models RMST directly
without using the IPCW estimating equations used elsewhere in the package.
}
\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{
\donttest{
pilot_df <- data.frame(
  time = rexp(100, 0.08),
  status = rbinom(100, 1, 0.7),
  arm = rep(0:1, each = 50),
  age = rnorm(100, 60, 10)
)
# Add a treatment effect
pilot_df$time[pilot_df$arm == 1] <- pilot_df$time[pilot_df$arm == 1] * 1.3

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