% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/multiplicative_stratified_boot.R
\name{MS.power.boot}
\alias{MS.power.boot}
\title{Analyze Power for a Multiplicative Stratified RMST Model via Simulation}
\usage{
MS.power.boot(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  strata_var,
  sample_sizes,
  linear_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}{A character string for the stratification variable.}

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

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

\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 powers.}
\item{results_plot}{A \code{ggplot} object visualizing the power curve.}
\item{results_summary}{A \code{data.frame} with the estimated treatment effect (RMST Ratio).}
}
\description{
Performs power analysis based on a multiplicative model for RMST
for stratified trials, using a bootstrap simulation approach.
}
\details{
This function estimates power through bootstrap simulation, resampling
within each stratum defined by \code{strata_var}. In each of the \code{n_sim} iterations:
\enumerate{
\item Jackknife pseudo-observations for the RMST are calculated.
\item A log-linear model (\code{stats::lm}) is fitted to the \code{log(pseudo_obs)}.
This models the multiplicative relationship on the original RMST scale,
i.e., \eqn{\mu_{ij} = \mu_{0j} \exp\{\beta'Z_i\}}. The model formula
includes stratum-specific intercepts and interactions with the treatment arm.
\item The p-value for the treatment effect is extracted from the model summary.
}

Power is determined as the proportion of simulations where the p-value is
less than \code{alpha}.
}
\note{
\code{status_var} should be \code{1}/\code{0}. \code{arm_var} should be \code{1}/\code{0}. \code{strata_var}
is a mandatory argument.
}
\examples{
\donttest{
pilot_df_strat <- data.frame(
 time = rexp(120, 0.15),
 status = rbinom(120, 1, 0.6),
 arm = rep(0:1, each = 60),
 region = factor(rep(c("A", "B", "C"), each = 40))
)
pilot_df_strat$time[pilot_df_strat$arm == 1] <- pilot_df_strat$time[pilot_df_strat$arm == 1] * 1.4

power_results <- MS.power.boot(
 pilot_data = pilot_df_strat,
 time_var = "time", status_var = "status", arm_var = "arm", strata_var = "region",
 sample_sizes = c(50, 75),
 L = 10,
 n_sim = 100 # Low n_sim for example
)
print(power_results$results_data)
}
}
