% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/multiplicative_stratified_analytical.R
\name{MS.power.analytical}
\alias{MS.power.analytical}
\title{Analyze Power for a Multiplicative Stratified RMST Model (Analytic)}
\usage{
MS.power.analytical(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  strata_var,
  sample_sizes,
  linear_terms = NULL,
  L,
  alpha = 0.05,
  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 (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{sample_sizes}{A numeric vector of sample sizes \emph{per stratum} to calculate power for.}

\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{verbose}{Logical; if \code{TRUE}, emit progress messages. Default \code{FALSE}.}
}
\value{
A \code{list} containing:
\item{results_data}{A \code{data.frame} with sample sizes and corresponding powers.}
\item{results_plot}{A \code{ggplot} object visualizing the power curve.}
}
\description{
Performs power analysis for a multiplicative, stratified RMST model using an
analytic method based on the work of Wang et al. (2019).
}
\details{
This function is based on the method for evaluating center (stratum) effects
using a multiplicative model for RMST: \eqn{\mu_{ij} = \mu_{0j} \exp\{\beta'Z_i\}}.
The method uses IPCW with a stratified Cox model for the censoring distribution.

Formal estimation of \eqn{\beta} requires an iterative solver for the estimating
equation given in Equation (8) of Wang et al. (2019). Because this is computationally
intensive, this implementation uses a log-linear working model fitted by weighted
least squares to pseudo-observations (\code{lm(log(Y_rmst) ~ ...)}) as a tractable
approximation. The approximation is consistent when the log-linear mean structure
is well-specified but may differ from the formal estimator under strong misspecification.

The power calculation relies on the asymptotic variance of the log-RMST ratio
estimator, \eqn{\hat{\tau}}. The variance is derived from the robust variance-covariance
matrix of the \code{lm} fit, which serves as a proxy for the formal sandwich estimator
\eqn{A^{-1}B(A^{-1})'} described in Theorem 1 of Wang et al. (2019).
}
\examples{
set.seed(123)
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.5

power_results <- MS.power.analytical(
 pilot_data = pilot_df_strat,
 time_var = "time", status_var = "status", arm_var = "arm", strata_var = "region",
 sample_sizes = c(50, 75, 100),
 L = 10, alpha = 0.05
)
print(power_results$results_data)
}
