% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/recurrent.marginal.R
\name{test_logrankRecurrent}
\alias{test_logrankRecurrent}
\alias{logrankRecurrentBase}
\title{Logrank-type test for comparing recurrent event marginal means between groups}
\usage{
test_logrankRecurrent(
  recurrent,
  death,
  weight = c("I", "II", "III"),
  km = TRUE,
  start = 0,
  stop = NULL,
  at.risk = 5,
  cluster.id = NULL,
  ...
)
}
\arguments{
\item{recurrent}{Either a \code{"recurrent"} object returned by
\code{\link{recurrent_marginal}}, or a \code{"phreg"} object for the
recurrent event model (in which case \code{death} must also be supplied).}

\item{death}{A \code{"phreg"} object for the terminal event model. Required
when \code{recurrent} is a \code{"phreg"} object; ignored otherwise.}

\item{weight}{Character string specifying the weight scheme: \code{"I"},
\code{"II"}, or \code{"III"}. Default is \code{"I"}. For competing risks \code{"III"} 
 gives Gray's test with robust standard errors.}

\item{km}{Logical. If \code{TRUE} (default), the Kaplan-Meier estimator is
used for the survival probability \eqn{S(t)}; otherwise the Nelson-Aalen
estimator is used.}

\item{start}{Left truncation time for the integration. Default is \code{0}.}

\item{stop}{Right truncation time for the integration. Defaults to the last
observed jump time.}

\item{at.risk}{Minimum combined risk-set size below which the weight is set
to zero. Default is \code{5}.}

\item{cluster.id}{Optional vector of cluster identifiers for aggregating
influence functions across clusters before forming the test statistic.}

\item{...}{Currently unused.}
}
\value{
An object of class \code{"estimate"} (from the \pkg{lava} package)
  with the following components:
  \item{coef}{The weighted difference in marginal means between groups.}
  \item{se}{Robust standard error of the test statistic.}
  \item{lower, upper}{95\% confidence interval bounds.}
  \item{p.value}{Two-sided p-value for the null hypothesis of no difference.}
  The object also carries an \code{iid} attribute containing the
  subject-level influence function decomposition of the test statistic,
  which can be used for further inference or combination with other estimators.
}
\description{
Tests whether the marginal mean number of recurrent events differs across
groups (strata), extending the classical logrank test to the setting of
recurrent events with a competing terminal event. The test statistic is
\deqn{z = \int_0^\tau w(s)\bigl[d\hat\mu_1(s) - d\hat\mu_2(s)\bigr],}
where \eqn{w(s)} is a weight function and \eqn{\hat\mu_j(s)} is the estimated
marginal mean for group \eqn{j}. Variance is estimated robustly via the
influence functions of Ghosh and Lin (2000).
}
\details{
Three weight schemes are available:
\describe{
  \item{\code{"I"}}{(Default) \eqn{w(t) = R_1(t) R_2(t) / (R_1(t) + R_2(t))},
    where \eqn{R_j(t) = Y_j(t) / \hat S_j(t-)}. Analogous to the standard
    logrank weight.}
  \item{\code{"II"}}{\eqn{w(t) = Y_j(t)}, the raw risk-set size. Equivalent
    to using observed counts without survival adjustment.}
  \item{\code{"III"}}{A modified weight incorporating the cumulative incidence,
    analogous to Gray's test for competing risks.}
}
}
\examples{
data(hfactioncpx12)
hf <- hfactioncpx12

## Test using two separate phreg models
xr <- phreg(Surv(entry, time, status == 1) ~ strata(treatment) + cluster(id), data = hf)
dr <- phreg(Surv(entry, time, status == 2) ~ strata(treatment) + cluster(id), data = hf)
out <- test_logrankRecurrent(xr, dr, stop = 5)
summary(out)

## Equivalently, using a recurrent_marginal object directly
outN <- recurrent_marginal(Event(entry, time, status) ~ strata(treatment) + cluster(id),
                           data = hf, cause = 1, death.code = 2)
test_logrankRecurrent(outN)

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