% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/multiplicative_stratified_analytical.R
\name{MS.ss.analytical}
\alias{MS.ss.analytical}
\title{Find Sample Size for a Multiplicative Stratified RMST Model (Analytic)}
\usage{
MS.ss.analytical(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  strata_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 for the time-to-event variable.}

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

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

\item{strata_var}{A character string for the stratification variable.}

\item{target_power}{A single numeric value for the desired power.}

\item{linear_terms}{An optional character vector of other covariate names.}

\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 stratum} 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 stratum} 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 required sample size.}
\item{results_plot}{A \code{ggplot} object visualizing the search path.}
\item{results_summary}{A \code{data.frame} summarizing the estimated log(RMST Ratio).}
}
\description{
Calculates the required sample size for a target power using the analytic
(approximate) method from Wang et al. (2019).
}
\details{
This function estimates the log-RMST ratio and its asymptotic variance once
from the pilot data, then increases the per-stratum sample size until the
target power is reached or the search limit is hit. It uses the same
log-linear approximation as \code{MS.power.analytical}.
}
\examples{
set.seed(456)
pilot_df_strat_effect <- data.frame(
 time = c(rexp(60, 0.15), rexp(60, 0.08)), # Effect
 status = rbinom(120, 1, 0.7),
 arm = rep(0:1, each = 60),
 region = factor(rep(c("A", "B"), each = 60))
)

ss_results <- MS.ss.analytical(
 pilot_data = pilot_df_strat_effect,
 time_var = "time", status_var = "status", arm_var = "arm", strata_var = "region",
 target_power = 0.80, L = 10,
 n_start = 100, n_step = 50
)
print(ss_results$results_data)
}
