% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Survdt.R
\name{time_split}
\alias{time_split}
\title{Split rows in a data frame into multiple observations at specified time
intervals}
\usage{
time_split(
  data,
  cut,
  stop_name,
  start_name = "start",
  event_name = "event",
  id_name = NULL,
  origin = 0
)
}
\arguments{
\item{data}{A data frame to be split.}

\item{cut}{A numeric vector of cut times.}

\item{stop_name}{The name of the existing event time or stop time column in
\code{data}.}

\item{start_name}{The name for the start time column to be created in the split
data. If it matches a column in \code{data} (meaning the data was previously split)
then \code{event_name} must also match a column in \code{data}.}

\item{event_name}{The name for the event indicator column to be created in the
split data. See \code{start_name} for special requirements.}

\item{id_name}{An optional name to create an id column in the split data. If
this column already exists in \code{data} its values will be used as ids.
If the data is already in (start, stop] format, do not use this argument.}

\item{origin}{The time that the follow up starts at. Defaults to zero.}
}
\value{
A split data frame with (start, stop] records.
The new column names are taken from the input arguments of \code{time_split()}.
}
\description{
Splits each record in the data frame into a series of observation windows
based on the supplied cut times.
Can be used to reshape data with time-varying covariates to the appropriate
format for \code{\link[=Survdt2]{Survdt2()}}.
The main workhorse is a modified call to \code{\link[survival:survSplit]{survival::survSplit()}}.
}
\details{
A basic use case of \code{\link[=time_split]{time_split()}} is to take a data frame with one row per
subject and transform it into a data frame with multiple rows per subject,
each corresponding to a specific observation time window.
The event time information observed in each window is encoded by four
potentially new variables:
\itemize{
\item \code{start}: the starting time for the observation window.
\item \code{stop}: the end time for the observation window.
\item \code{event}: equal to one when the subject's event occurred at \code{stop}, and zero
otherwise.
\item \code{id}: the label that identifies which subject the data corresponds to.
}

In this use case, the name of the event time column in \code{data} should always be
provided, as well as the name for the new \code{id} column if one does not already
exist.
After \code{cut} is sorted, the \eqn{i}th subject's observation windows will be
\eqn{(}\code{origin}, \code{cut[1]}\eqn{]}, \eqn{(}\code{cut[1]}, \code{cut[2]}\eqn{]}, \eqn{\ldots},
\eqn{(}\code{cut[j]}, \eqn{T_i}\eqn{]} for some
\code{j}\eqn{\leq}\code{length(cut)}.

Another use case of \code{\link[=time_split]{time_split()}} is to introduce additional splits in a
previously split data frame.
The names for the existing \code{start}, \code{stop}, and \code{event} columns should be
provided to \code{\link[=time_split]{time_split()}} in this case.
Requesting a new \code{id} variable for previously cut data will return an error,
since the new ids would not respect the prior groupings.
}
\examples{
splitdat1 <- time_split(aids, cut = c(20, 40),
                        stop_name = "incu",
                        id_name = "id",
                        origin = -1)
tail(splitdat1)

splitdat2 <- time_split(splitdat1, cut = c(10, 30),
                        start_name = "start",
                        stop_name = "incu",
                        event_name = "event",
                        id_name = "id",
                        origin = -1)
tail(splitdat2)
}
\seealso{
\itemize{
\item \code{\link[=Survdt2]{Survdt2()}}: create survival objects with split data.
\item \code{\link[=coxph_indtrunc]{coxph_indtrunc()}}: Cox regression with time-varying covariates.
\item \code{\link[=survdt2to1]{survdt2to1()}}: collapse data back to one row per subject.
}
}
