% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/recurrent.marginal.R
\name{recurrent_marginal}
\alias{recurrent_marginal}
\alias{recurrent_marginalAIPCW}
\alias{recurrentMarginalPhreg}
\alias{iidRecurrent}
\alias{recurrentMarginal}
\title{Marginal mean estimation for recurrent events with a terminal event}
\usage{
recurrent_marginal(formula, data, cause = 1, ..., death.code = 2, test = FALSE)

recurrentMarginal(formula, data, ...)
}
\arguments{
\item{formula}{A formula with an \code{\link{Event}} response on the left-hand
side, specifying entry time, exit time, and event status. The right-hand side
may include \code{cluster()} to identify subjects and \code{strata()} for a
stratified analysis. A \code{cluster()} term is required.}

\item{data}{A data frame containing all variables in \code{formula}.}

\item{cause}{Integer code(s) for the recurrent event of interest. Default is
\code{1}.}

\item{...}{Further arguments passed to \code{\link{phreg}}.}

\item{death.code}{Integer code(s) for the terminal event. Default is \code{2}.}

\item{test}{Logical. If \code{TRUE}, a logrank-type test comparing strata is
computed and stored as an attribute of the result. Default is \code{FALSE}.}
}
\value{
An object of class \code{"recurrent"} with the following components:
  \item{mu}{Estimated marginal mean \eqn{\mu(t)} at each jump time.}
  \item{se.mu}{Robust standard error of \code{mu}.}
  \item{times}{Jump times at which estimates are computed.}
  \item{St}{Marginal survival estimate \eqn{S(t)} at each jump time.}
  \item{cumhaz}{Two-column matrix of \code{(time, mu)}, suitable for plotting.}
  \item{se.cumhaz}{Two-column matrix of \code{(time, se.mu)}.}
  The object carries three attributes: \code{"logrank"} (the test result when
  \code{test = TRUE}, otherwise \code{NULL}), \code{"cause"}, and
  \code{"death.code"}.
}
\description{
Estimates the marginal mean number of recurrent events over time in the
presence of a competing terminal event (e.g. death), using the nonparametric
estimator of Ghosh and Lin (2000). Two proportional hazards models are fitted
internally—one for the recurrent event rate and one for the terminal
event—and combined to form the estimator
\deqn{\mu(t) = \int_0^t S(u-)\,dR(u),}
where \eqn{S(u)} is the marginal survival probability at the baseline covariate
level and \eqn{dR(u)} is the baseline recurrent event rate among survivors.
Robust (sandwich) standard errors are computed via the influence-function
approach of Ghosh and Lin (2000).
}
\details{
Jump times must be unique within each stratum. If ties are present, use
\code{\link{tie_breaker}} to resolve them before calling this function.
}
\examples{
data(hfactioncpx12)
hf <- hfactioncpx12
hf$x <- as.numeric(hf$treatment)

## Fit nonparametric baseline models for recurrent events and death
xr <- phreg(Surv(entry, time, status == 1) ~ cluster(id), data = hf)
dr <- phreg(Surv(entry, time, status == 2) ~ cluster(id), data = hf)

par(mfrow = c(1, 3))
plot(dr, se = TRUE); title(main = "Death")
plot(xr, se = TRUE); title(main = "Recurrent events")

## Compare naive and robust standard errors for the recurrent event rate
rxr <- robust_phreg(xr, fixbeta = 1)
plot(rxr, se = TRUE, robust = TRUE, add = TRUE, col = 4)

## Marginal mean via formula interface
outN <- recurrent_marginal(Event(entry, time, status) ~ cluster(id),
                           data = hf, cause = 1, death.code = 2)
plot(outN, se = TRUE, col = 2, add = TRUE)
summary(outN, times = 1:5)

## Stratified analysis with logrank test
out <- recurrent_marginal(Event(entry, time, status) ~ strata(treatment) + cluster(id),
                          data = hf, cause = 1, death.code = 2, test = TRUE)
plot(out, se = TRUE, ylab = "Marginal mean", col = 1:2)
attr(out, "logrank")
summary(out, times = 1:5)

## Influence-function (iid) decomposition at a fixed time point
head(iid(outN, time = 3))

}
\references{
Cook, R. J. and Lawless, J. F. (1997). Marginal analysis of recurrent events
and a terminating event. \emph{Statistics in Medicine}, 16, 911--924.

Ghosh, D. and Lin, D. Y. (2000). Nonparametric analysis of recurrent events
and death. \emph{Biometrics}, 56, 554--562.
}
\seealso{
\code{\link{test_logrankRecurrent}}, \code{\link{tie_breaker}},
  \code{\link{prob_exceed_recurrent}}
}
\author{
Thomas Scheike
}
