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

\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 (Type I error rate).}

\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 required sample size per arm.}
\item{results_plot}{A \code{ggplot} object visualizing the sample size search path.}
\item{results_summary}{A \code{data.frame} summarizing the treatment effect from the pilot data used for the calculation.}
}
\description{
Calculates the required sample size for a target power using an
analytic formula based on the methods of Tian et al. (2014).
}
\details{
This function performs an iterative search to find the sample size needed to
achieve a specified \code{target_power}. It uses the same underlying theory as
\code{linear.power.analytical}. First, it estimates the treatment effect size and its
asymptotic variance from the pilot data. Then, it iteratively calculates the
power for increasing sample sizes using the analytic formula until the
target power is achieved.
}
\examples{
pilot_df <- data.frame(
  time = c(rexp(50, 0.1), rexp(50, 0.07)), # Introduce an effect
  status = rbinom(100, 1, 0.8),
  arm = rep(0:1, each = 50),
  age = rnorm(100, 55, 10)
)
ss_results <- linear.ss.analytical(
  pilot_data = pilot_df,
  time_var = "time",
  status_var = "status",
  arm_var = "arm",
  target_power = 0.80,
  L = 10
)
print(ss_results$results_data)
print(ss_results$results_plot)
}
