% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/recurrent.marginal.R
\name{tie_breaker}
\alias{tie_breaker}
\title{Break ties in event times for recurrent event data}
\usage{
tie_breaker(
  data,
  stop = "time",
  start = "entry",
  status = "status",
  id = NULL,
  cause = NULL,
  cens.code = 0,
  exit.unique = TRUE,
  ddt = NULL,
  seed = NULL
)
}
\arguments{
\item{data}{A data frame in counting-process format, sorted by subject and
time.}

\item{stop}{Name of the column containing interval exit (stop) times.
Default is \code{"time"}.}

\item{start}{Name of the column containing interval entry (start) times,
used to update the following row when \code{id} is supplied. Default is
\code{"entry"}.}

\item{status}{Name of the column containing event status codes. Default is
\code{"status"}.}

\item{id}{Name of the column containing subject identifiers. If supplied,
the start time of the next interval for the same subject is adjusted to
match the perturbed stop time, preserving interval continuity. Default is
\code{NULL} (no adjustment made).}

\item{cause}{Integer vector of status codes that identify events (non-censored
rows). If \code{NULL} (default), all non-censoring status values are treated
as events.}

\item{cens.code}{Integer code(s) for censoring. Rows with this status are
never perturbed. Default is \code{0}.}

\item{exit.unique}{Logical. If \code{TRUE} (default), an event time is
considered tied whenever it coincides with \emph{any} exit time in the
data (including censored rows). If \code{FALSE}, only ties among event rows
are resolved.}

\item{ddt}{Maximum perturbation size. Tied event times are shifted by a
uniform draw on \eqn{[0, \text{ddt}]}. If \code{NULL} (default), \code{ddt}
is set to half the smallest positive gap between any two consecutive exit
times in the data.}

\item{seed}{Optional integer passed to \code{set.seed()} before drawing the
perturbations, making results reproducible. Default is \code{NULL} (no seed
set).}
}
\value{
The input data frame \code{data} with tied event exit times
  perturbed. If \code{id} is supplied, an additional logical column
  \code{tiebreaker} marks rows whose start time was adjusted as a consequence
  of a perturbation in the preceding row.
}
\description{
Resolves tied event times in a counting-process dataset by adding a small
random perturbation to duplicated exit times of event rows. This is a
preprocessing step required by \code{\link{recurrent_marginal}} and related
functions, which assume unique jump times within each stratum.
}
\details{
A tie is defined as an event exit time (rows where \code{status} is a cause
code) that coincides with another exit time in the dataset. When
\code{exit.unique = TRUE} (default), a tie is flagged whenever an event time
also appears among any other exit times (censored or event). When
\code{exit.unique = FALSE}, only exact ties between two event rows are
resolved.

Tied event times are perturbed by adding \eqn{U \cdot \delta} where
\eqn{U \sim \text{Uniform}(0, 1)} and \eqn{\delta} is \code{ddt} (defaulting
to half the smallest observed positive gap between consecutive exit times).
When subject IDs are provided via \code{id}, the corresponding interval start
time of the immediately following row for the same subject is updated to
maintain a valid counting-process structure, and a logical \code{tiebreaker}
column is added to flag affected rows.
}
\examples{
data(hfactioncpx12)
hf <- hfactioncpx12

## Check for ties in event exit times
ev <- hf[hf$status == 1, ]
any(duplicated(ev$time))

## Resolve ties before fitting the marginal mean model
hf_clean <- tie_breaker(hf, stop = "time", start = "entry",
                         status = "status", id = "id",
                         cause = 1, cens.code = 0)

out <- recurrent_marginal(Event(entry, time, status) ~ cluster(id),
                           data = hf_clean, cause = 1, death.code = 2)
summary(out, times = 1:5)

}
\seealso{
\code{\link{recurrent_marginal}}, \code{\link{test_logrankRecurrent}}
}
\author{
Thomas Scheike
}
