% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/datagen-interface.R
\name{rmst.sim}
\alias{rmst.sim}
\title{Simulate survival data for RMST analysis}
\usage{
rmst.sim(
  n,
  model = "aft_lognormal",
  baseline,
  treat_effect = 0,
  covariates = list(),
  target_censoring = 0.25,
  allocation = "1:1",
  L = NULL,
  seed = NULL
)
}
\arguments{
\item{n}{Total sample size (split by \code{allocation} ratio).}

\item{model}{Event-time model. One of:
\code{"aft_lognormal"} (default), \code{"aft_weibull"},
\code{"aft_loglogistic"}, \code{"ph_exponential"}, \code{"ph_weibull"},
\code{"ph_gompertz"}, \code{"cox_pwexp"}.}

\item{baseline}{Named list of baseline parameters (model-specific; see
\code{\link{recipe_quick_aft}} and \code{\link{recipe_quick_ph}}).}

\item{treat_effect}{Numeric treatment coefficient. Log-time scale for AFT
models; log-hazard ratio for PH models. Default \code{0}.}

\item{covariates}{List of covariate definitions. Elements can be created with
\code{\link{covar_continuous}}, \code{\link{covar_binary}}, or
\code{\link{covar_categorical}}, or supplied as raw named lists in the
existing recipe format. Default \code{list()} (no covariates).}

\item{target_censoring}{Target overall censoring fraction (0-1). Default \code{0.25}.}

\item{allocation}{Treatment allocation ratio string, e.g. \code{"1:1"} (default).}

\item{L}{Optional numeric truncation time. Stored as an attribute on the
returned object for downstream use by \code{\link{rmst.power}} /
\code{\link{rmst.ss}}. Does not affect data generation.}

\item{seed}{Optional seed retained as recipe/provenance metadata. It does not
set the random-number generator; call \code{set.seed()} before \code{rmst.sim()}
for reproducible simulation.}
}
\value{
A \code{data.frame} of class \code{c("rmst_simdata", "data.frame")}
with columns \code{time}, \code{status}, \code{arm} (when treatment is
present), and one column per covariate. Attributes:
\describe{
\item{recipe}{The validated recipe list used for generation.}
\item{L}{The truncation time if supplied, else \code{NULL}.}
\item{achieved_censoring}{Actual censoring fraction achieved.}
}
}
\description{
A unified, single-call wrapper for generating survival data suitable for use
as reference/pilot data in \code{\link{rmst.power}} and \code{\link{rmst.ss}}.
Supports all seven built-in event-time models (AFT and PH families).
}
\details{
Internally routes to \code{\link{recipe_quick_aft}} for AFT models and
\code{\link{recipe_quick_ph}} for PH models, then calls
\code{\link{simulate_from_recipe}}.
}
\examples{
df <- rmst.sim(
  n            = 150,
  model        = "aft_lognormal",
  baseline     = list(mu = 2.2, sigma = 0.5),
  treat_effect = -0.3,
  covariates   = list(covar_continuous("age"), covar_binary("female")),
  L            = 12,
  seed         = 42
)
print(df)
s <- summary(df)

}
\seealso{
\code{\link{rmst.power}}, \code{\link{rmst.ss}},
\code{\link{recipe_quick_ph}}, \code{\link{recipe_quick_aft}},
\code{\link{covar_continuous}}
}
