% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/recurrent.marginal.R
\name{sim_recurrentTS}
\alias{sim_recurrentTS}
\title{Simulate recurrent events from a two-stage model with structured gamma frailties}
\usage{
sim_recurrentTS(
  n,
  cumhaz,
  cumhaz2,
  death.cumhaz = NULL,
  nu = rep(1, 3),
  share1 = 0.3,
  vargamD = 2,
  vargam12 = 0.5,
  gap.time = FALSE,
  max.recurrent = 100,
  cens = NULL,
  ...
)
}
\arguments{
\item{n}{Number of subjects to simulate.}

\item{cumhaz}{Two-column matrix \code{(time, cumhaz)} giving the target
marginal cumulative rate of the first recurrent event type.}

\item{cumhaz2}{Two-column matrix \code{(time, cumhaz)} giving the target
marginal cumulative rate of the second recurrent event type.}

\item{death.cumhaz}{Two-column matrix \code{(time, cumhaz)} giving the
cumulative hazard of the terminal event.}

\item{nu}{Numeric vector of length 3: the powers \eqn{(\nu_1, \nu_2, \nu_3)}
applied to the frailty components (see Details). Must satisfy
\eqn{\nu_j > -1/\text{shape}}. Default is \code{rep(1, 3)}.}

\item{share1}{Proportion of the total death frailty variance assigned to the
first component \eqn{Z_{d1}}. The remainder goes to \eqn{Z_{d2}}. Must be
in \eqn{(0, 1)}. Default is \code{0.3}.}

\item{vargamD}{Total variance of the death frailty \eqn{Z_\text{death}}.
Default is \code{2}.}

\item{vargam12}{Variance of the shared recurrent-event frailty \eqn{Z_{12}}.
Default is \code{0.5}.}

\item{gap.time}{Logical. If \code{TRUE}, event times are drawn as gap times
rather than calendar times. Default is \code{FALSE}.}

\item{max.recurrent}{Maximum number of recurrent events per subject. Default
is \code{100}.}

\item{cens}{Rate of exponential censoring. If \code{NULL} (default), no
administrative censoring is applied.}

\item{...}{Further arguments passed to lower-level simulation functions.}
}
\value{
A data frame in counting-process format (one row per event interval
  per subject) with columns \code{id}, \code{start}, \code{stop},
  \code{entry}, \code{time}, \code{status}, and \code{death}. Attributes
  store the (possibly adjusted) cumulative hazards used in simulation and
  the frailty parameters.
}
\description{
Simulates recurrent event data with two event types and a terminal event,
using a parametric two-stage frailty model. The construction ensures that the
marginal rates are approximately correct: conditional on survival,
\eqn{E(dN_j \mid D > t) \approx} \code{cumhazj}, and the hazard of death
equals \code{death.cumhaz}.
}
\details{
The frailty structure uses three gamma random variables \eqn{Z_{d1}},
\eqn{Z_{d2}}, \eqn{Z_{12}} to induce dependence:
\deqn{Z_\text{death} = Z_{d1} + Z_{d2}, \quad
      Z_1 = Z_{d1}^{\nu_1} Z_{12}, \quad
      Z_2 = Z_{d2}^{\nu_2} Z_{12}^{\nu_3}.}
The parameters \code{share1} and \code{vargamD} control how the death frailty
splits between the two components, and \code{vargam12} controls the shared
recurrent-event frailty. Setting \eqn{\nu = (1,1,1)} with \code{share1 = 0.5}
gives a symmetric structure; varying \eqn{\nu} allows asymmetric dependence.
}
\examples{
data(CPH_HPN_CRBSI)
dr    <- CPH_HPN_CRBSI$terminal
base1 <- CPH_HPN_CRBSI$crbsi
base4 <- CPH_HPN_CRBSI$mechanical

rr <- sim_recurrentTS(1000, base1, base4, death.cumhaz = dr)
dtable(rr, ~death + status)
mets:::showfitsim(causes = 2, rr, dr, base1, base4)

}
\seealso{
\code{\link{sim_recurrentII}}, \code{\link{sim_recurrent_ts}}
}
\author{
Thomas Scheike
}
