% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/seqem.R
\name{seqem}
\alias{seqem}
\title{Sequential trial emulation for time-dependent treatment data}
\usage{
seqem(data, start, stop, event, tvtrt, id, covs = NULL, coarsen = c("none",
  "floor", "ceiling"), cbin_width = NULL)
}
\arguments{
\item{data}{a \code{data.frame} in start-stop long format with potentially
multiple rows per individual. Typically a dataset produced by
\link[survival:tmerge]{tmerge}.}

\item{start}{a string name of the interval start time variable.}

\item{stop}{a string name of the stop time variable.}

\item{event}{a string name of the event indicator (1: event).}

\item{tvtrt}{a string name of the time-varying \strong{treatment} variable. Currently this
must be binary and monotone in the sense assumed by the sequential
trials framework (remain 1 once become 1). A trial-specific baseline
version of \code{tvtrt} is always created as \code{tvtrt.base}.}

\item{id}{a string name of the unique individual identifier.}

\item{covs}{optional. a string vector of covariate names in \code{data} for
which trial-specific baseline versions should be created. Both
\emph{time-constant} and \emph{time-varying} covariates are supported. For each \code{X}
in \code{covs}, \code{seqem()} creates \code{X.base}, representing the value of \code{X}
at the start of each emulated trial for each individual.}

\item{coarsen}{one of \code{"none"}, \code{"floor"}, or \code{"ceiling"}.
\code{"none"} leaves the original timeline unchanged. \code{"floor"} and
\code{"ceiling"} discretize row start times to the coarsening grid and thus
affect both treatment and time-varying covariate histories.}

\item{cbin_width}{a positive numeric bin width used when
\code{coarsen = "floor"} or \code{"ceiling"}.}
}
\value{
A \code{seqem} object with components:
\itemize{
\item \code{data_seqorig} : stacked emulated trials \strong{before} artificial
censoring, with columns:
\code{id}, \code{trial}, \code{trial_time}, \code{rownum}, \code{visit},
original \code{start}, \code{stop}, \code{event}, \code{tvtrt}, covariates, and
triap-specific follow-up intervals \code{start.new}, \code{stop.new},
\code{event}, trial-specific baseline treatment and covariates
\verb{\{tvtrt\}.base}, \verb{\{covs\}.base} for covariates in \code{covs}.
\item \code{data_seqem} : stacked emulated trials \strong{after} artificial
censoring, obtained by restricting to rows by forcing
\verb{\{tvtrt\} == \{tvtrt\}.base}. This is the dataset typically used for
downstream \code{seqcox()} or \code{coxiv_seq()} with sequential trials
emulation framework.
\item \code{summary} : a character string describing the \code{seqem} object,
used by \code{print.seqem()}.
\item \code{trial_summary} : a per-trial summary \code{data.frame} with one row
per emulated trial and columns:
\code{trial} (trial index), \code{t0} (trial start time),
\code{n} (unique individuals), \code{rows} (person-time rows),
\code{treated} (unique baseline-treated individuals), and \code{events}
(terminal events) in that trial.
}
}
\description{
Constructs a stacked sequence of emulated trials from
longitudinal survival data in start-stop form, following the
sequential trials framework of Gran et al. and Keogh et al.
}
\details{
Trial start times are determined only by the earliest observed cohort
entry time and by times at which at least one individual newly initiates
treatment (0 -> 1). Changes in time-varying covariates listed in
\code{covs} do \strong{not} themselves create new trial start times. However,
\code{seqem()} still carries those covariates forward correctly into each
emulated trial by creating trial-specific baseline versions with suffix
\code{.base}.

When \code{coarsen != "none"}, the observed timeline is discretized/coarsened onto a
grid of time width \code{cbin_width}. This coarsening is applied to \strong{all} row
start times, not only to treatment changes, so that updates in
time-varying covariates are also mapped onto the coarsened scale.
With \code{coarsen = "floor"}, updates are mapped down to the beginning of
the containing interval; with \code{coarsen = "ceiling"}, they are mapped up
to the end of the containing interval. After coarsening, emulated trial
start times remain tied only to treatment initiation times on the
coarsened scale.

The function algorithmic workflow:
\enumerate{
\item Identifies trial start times: the earliest cohort start time plus
all times at which any individual initiates treatment (\verb{tvtrt =} 0 -> 1).
\item Augments each individual's trajectory by splitting intervals at
these trial start times so that each at-risk subject has an
explicit row starting at each trial time.
\item For each trial, includes individuals who are under observation at
the trial start and have not yet started treatment, and constructs
trial-specific baseline versions of treatment and covariates
(with suffix \code{.base}), new follow-up times \code{start.new}, \code{stop.new}, \code{event}.
\item Implements artificial censoring by restricting to rows where the
current treatment equals the baseline treatment in that trial.
}
}
\examples{
if (requireNamespace("survival", quietly = TRUE)) {
  data("heart", package = "survival")

  fit_seqem <- seqem(data = heart, start = "start", stop = "stop",
    event = "event", tvtrt = "transplant", id = "id",
    covs = c("age", "surgery"), coarsen = "floor", cbin_width = 7)

  print(fit_seqem)
}

}
\references{
\enumerate{
\item Gran JM, Roysland K, Wolbers M, Didelez V, Sterne JA, Ledergerber B, Furrer H, von Wyl V, Aalen OO. A sequential Cox approach for estimating the causal effect of treatment in the presence of time-dependent confounding applied to data from the Swiss HIV Cohort Study. \emph{Statistics in Medicine}. 2010 Nov 20;29(26):2757-68.
\item Keogh RH, Gran JM, Seaman SR, Davies G, Vansteelandt S. Causal inference in survival analysis using longitudinal observational data: Sequential trials and marginal structural models. \emph{Statistics in Medicine}. 2023 Jun 15;42(13):2191-2225.
}
}
