% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/linear_ipcw_boot.R
\name{linear.ss.boot}
\alias{linear.ss.boot}
\title{Find Sample Size for a Linear RMST Model via Simulation}
\usage{
linear.ss.boot(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  target_power,
  linear_terms = NULL,
  L,
  n_sim = 1000,
  alpha = 0.05,
  patience = 5,
  n_start = 50,
  n_step = 25,
  max_n_per_arm = 2000,
  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{target_power}{A single numeric value for the target power (e.g., 0.80).}

\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 per search step.}

\item{alpha}{The significance level.}

\item{patience}{The number of consecutive non-improving steps in the search before terminating.}

\item{n_start}{The starting sample size \emph{per arm} for the search.}

\item{n_step}{The increment in sample size at each step of the search.}

\item{max_n_per_arm}{The maximum sample size \emph{per arm} to search up to.}

\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 target power and the final required sample size per arm.}
\item{results_plot}{A \code{ggplot} object showing the search path.}
\item{results_summary}{A \code{data.frame} with summary statistics for the estimated treatment effect from the final simulation.}
}
\description{
Performs an iterative sample size search to achieve a target power
based on the direct linear regression model for RMST, using bootstrap simulation.
}
\details{
This function iteratively searches for the required sample size to achieve
a specified \code{target_power}. At each step of the search, it runs a full bootstrap
simulation (\code{n_sim} iterations), as described in \code{linear.power.boot}, to
estimate the power for the current sample size. The search stops when the
target power is achieved or other stopping criteria (e.g., \code{patience}) are met.
Due to the nested simulation structure, this function can be very time-consuming.
}
\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_effect <- data.frame(
  time = c(rexp(50, 0.1), rexp(50, 0.05)), # Effect present
  status = rbinom(100, 1, 0.8),
  arm = rep(0:1, each = 50)
)
ss_results <- linear.ss.boot(
  pilot_data = pilot_df_effect,
  time_var = "time",
  status_var = "status",
  arm_var = "arm",
  target_power = 0.80,
  L = 10,
  n_sim = 200, # Low n_sim for example
  patience = 2,
  n_start = 100,
  n_step = 50,
  max_n_per_arm = 500
)
print(ss_results$results_data)
print(ss_results$results_plot)
}
