Nothing
contTimeCausal - Continuous Time Causal Models
In contTimeCausal: Continuous Time Causal Models
knitr::opts_chunk$set(echo = TRUE)
opt <- options()
options(continue=" ", width=70, prompt=" ")
on.exit(options(opt))
library(contTimeCausal, quietly=TRUE)
Introduction
\textbf{contTimeCausal} is an \textbf{R} package for evaluating the effect of
time-varying treatments on a survival outcome. Currently, the package includes
a structural failure time model (SFTM) and a Cox marginal structural model (MSM)
that respect the continuous time nature of the underlying data processes in
practice (i.e., the variables and processes are measured at irregularly spaced
time points, which are not necessarily the same for all subjects).
The SFTM model assumes that the potential failure time, $U$, had the individual
never received treatment and the observed failure time, $T$, follow
$$U \thicksim \int_0^T e^{\psi\times A_u}d u, $$
where $\thicksim$ means ``has the same distribution as" and $A_u$ is the
treatment indicator at time $u$.
The Cox MSM model assumes that the potential failure time, $T^{\overline{a}}$,
under the treatment regime $\overline{a}$ (a hypothetical treatment regime
from baseline to the event time) follows a proportional hazards model with the
hazard function at $u$ as
$$\lambda_0(u)e^{\psi\times a_u}.$$
It is assumed that individuals continuously received treatment until time
$V$. The observed failure time can be censored. We assume an ignorable
censoring mechanism in the sense that the censoring time is independent of the
failure time given the treatment and covariate history.
The implemented methods can accommodate an arbitrary number of baseline and/or
time-dependent covariates. If only time-independent covariates are included,
the data required for analysis must contain the following information:
\begin{itemize}
\item{\textbf{id}:} A unique participant identifier.
\item{\textbf{U}:} The time to the clinical event or censoring.
\item{\textbf{deltaU}:} The clinical event indicator (1 if U is the event time;
0 otherwise).
\item{\textbf{V}:} The time to optional treatment discontinuation, a clinical
event, censoring, or a treatment-terminating event.
\item{\textbf{deltaV}:} The indicator of optional treatment discontinuation
(1 if treatment discontinuation was optional; 0 if
treatment discontinuation was due to a clinical event,
censoring or a treatment-terminating event).
\end{itemize}
If time-dependent covariates are to be included, the data must be
a time-dependent dataset as described by package \textbf{survival}. Specifically,
the time-dependent data must be specified for an interval (lower,upper]
and the data must include the following additional information:
\begin{itemize}
\item{\textbf{start}:} The lower boundary of the time interval to which the
data pertain.
\item{\textbf{stop}:} The upper boundary of the time interval to which the
data pertain.
\end{itemize}
\vspace{.15in}
The SFTM and CoxMSM are implemented through functions \textit{ctSFTM()} and
\textit{ctCoxMSM()}, respectively. Both functions estimate the
effect of the treatment regime (in terms of time to treatment discontinuation)
for a survival outcome with time-varying treatment and confounding in the
presence of dependent censoring. Function \textit{ctSFTM()} estimates the effect
under a continuous time SFTM, and \textit{ctCoxMSM} estimates the effect under a
Cox proportional hazards model. The functions return the estimated model
parameter, $\psi$.
Functions
\textit{ctSFTM()}
This function estimates the effect of time-varying treatments on a survival
outcome under the SFTM. The value object returned is a continuous-time g-estimator
of $\psi$.
\vspace{.15in}
The function call takes the following form:
ctSFTM(data, base = NULL, td = NULL)
where
\begin{itemize}
\item \texttt{data} is a data.frame object containing all required data
as previously described. If only time-independent covariates are included
in the model, the data.frame must use the following column headers:
id',U', deltaU',V', and deltaV', which are defined above. If time-dependent covariates are to be included, the
data.frame must be a time-dependent dataset as described by package \textbf{survival}. Specifically, the time-dependent data must be specified for an interval
(start,stop] and the data must include two additional columns headers:start' and `stop'.
\item \texttt{base} is a character or numeric vector object or \texttt{NULL}. If
baseline covariates are included in the model, \texttt{base} must be a vector
containing the column headers or the column numbers of \texttt{data} that pertain to the
time-independent covariates. If \texttt{NULL}, time-independent covariates are
excluded from the model.
\item \texttt{td} is a character or numeric vector object or \texttt{NULL} If
time-dependent covariates are included in the model, \texttt{td} must be a vector
containing the column headers or the column numbers of data that pertain to the
time-dependent covariates. If \texttt{NULL}, time-dependent covariates are
excluded from the model. Note that this vector should \underline{not} include required
columns start' andstop'.
\end{itemize}
Note that only one of \texttt{base} and \texttt{td} can be specified as \texttt{NULL}.
\vspace{.15in}
The value object returned by \textit{ctSFTM()} an S3 object of class \textbf{ctc},
containing \$psi, the estimated model parameter, and \$coxPH, the
Cox regression for V.
\vspace{.15in}
\textit{ctCoxMSM()}
This function estimates the effect of time-varying treatments on a survival
outcome under the Cox proportional hazards model. The value object returned is an inverse probability of treatment weighting estimator of $\psi$.
\vspace{.15in}
The function call takes the following form:
ctCoxMSM(data, base = NULL, td = NULL)
where the inputs are as defined above for \textit{ctSFTM()} and their descriptions are not
repeated here.
The value object returned by \textit{ctCoxMSM()} is also an S3 object of
class \textbf{ctc},
containing \$psi, the estimated model parameter, and \$coxPH, the
Cox regression for V.
\vspace{.15in}
\textit{print()}
A convenience function for displaying the primary results of the analysis.
The function call takes the following form:
print(x, ...)
where \texttt{x} is the \textbf{ctc} object returned by \textit{ctSFTM()} or
\textit{ctCoxMSM()}.
\vspace{.15in}
Examples
To illustrate the call structure and results of \textit{ctSFTM()} and \textit{ctCoxMSM()}, we use the
dataset provided with the package, \texttt{ctcData}. This dataset was generated only
for the purposes of illustrating the package and should not be interpreted
as representing a real-world dataset. The dataset contains the following
observations for 1,000 participants:
\begin{itemize}
\item{id} A unique participant identifier.
\item{start} The left side of the time interval for time-dependent covariate xt.
\item{stop} The right side of the time interval for time-dependent covariate xt.
\item{xt} A continuous time-dependent covariate.
\item{x} A continuous baseline covariate.
\item{deltaU} A binary indicator of the clinical event. If the
clinical event occurred, takes value 1; otherwise 0.
\item{deltaV} A binary indicator of treatment discontinuation. If
treatment discontinuation was optional, takes value 1.
If treatment discontinuation was due to the clinical
event, censoring, or a treatment-terminating event, takes
value 0.
\item{U} The time to the clinical event or censoring.
\item{V} The time to optimal treatment discontinuation, the clinical
event, censoring, or a treatment-terminating event.
\end{itemize}
\vspace{.15in}
The data can be loaded in the usual way
data(ctcData)
head(ctcData)
\vspace{.15in}
Before considering the summary statistics of the dataset, we break the set into
time-independent and time-dependent components. The time-independent data can
be extracted as follows
ti <- ctcData[,c(5L:9L)]
ti <- ti %>% distinct()
where we have eliminated duplicate rows using \textbf{dplyr}'s \textit{distinct()} function.
The time-dependent component is trivially extracted
td <- ctcData[,2L:4L]
The summary statistics for the time-independent data
summary(object = ti)
show that the binary baseline covariate x is approximately evenly
distributed across the participants; that $\sim 87\%$ of the participants
experienced a clinical event; and that for $\sim 30\%$ of the participants treatment
was optionally discontinued. The maximum time to a clinical event or
censoring is 28.95. Considering only those participants that optionally
discontinued treatment
summary(object = ti$V[ti$deltaV==1L])
we see that the $0.01 \le V \le 13.67$.
From the summary of the time-dependent data, we see that xt is a continuous
variable in the range $-7.027 \le xt \le 2.736$. Measurements were taken at time points
{0, 5, 10}.
summary(object = td)
\vspace{.25in}
In the first example, we estimate the parameter of the continuous time SFTM
using all of the available data as follows
res <- ctSFTM(data = ctcData, base = "x", td = "xt")
\vspace{.15in}
The value object returned is an S3 object containing the estimated parameter
and the Cox regression for $V$. As a precaution, we encourage users to verify
that the parameters included in the Cox regression are as expected from the input.
Here, we see that both $x$ and $xt$ were included.
res
To include only the baseline covariates in the
model, we do not change input \texttt{td} from its default setting of \texttt{NULL}.
ctSFTM(data = ctcData, base = "x")
Note that only $x$ was included in the Cox regression.
\hspace{.25in}
Similarly, to include only the time-dependent covariates, we do not provide input
\texttt{base}.
ctSFTM(data = ctcData, td = "xt")
\vspace{0.25in}
Next we estimate $\psi$ under the continuous time Cox MSM
using all of the available data
res <- ctCoxMSM(data = ctcData, base = "x", td = "xt")
\vspace{.15in}
The value object returned is an S3 object containing the estimated parameter
and the Cox regression for $V$. Notice that the regression results are the
same as those obtained above for the full SFTM analysis. The estimated
parameter, $\psi$, is
similar to that obtained under the SFTM with both time-dependent and
time-independent covariates.
res
\hspace{.25in}
As for the \texttt{ctSFTM()}, we can also consider only the time-independent
covariates
ctCoxMSM(data = ctcData, base = "x")
\hspace{.25in}
Or, to include only the time-dependent covariates
ctCoxMSM(data = ctcData, td = "xt")
\hspace{.25in}
\noindent \textbf{References}
Yang, S., A. A. Tsiatis, and M. Blazing (2018).
Modeling survival distribution as a function of time to treatment discontinuation: A dynamic treatment regime approach,
\textit{Biometrics}, 74, 900–909.
Yang, S., K. Pieper, and F. Cools (2020).
Semiparametric estimation of structural failure time model in continuous-time processes.
\textit{Biometrika}, 107, 123–136.
Try the contTimeCausal package in your browser
Any scripts or data that you put into this service are public.
contTimeCausal documentation built on June 7, 2022, 1:05 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
knitr::opts_chunk$set(echo = TRUE) opt <- options() options(continue=" ", width=70, prompt=" ") on.exit(options(opt)) library(contTimeCausal, quietly=TRUE)
Introduction
\textbf{contTimeCausal} is an \textbf{R} package for evaluating the effect of time-varying treatments on a survival outcome. Currently, the package includes a structural failure time model (SFTM) and a Cox marginal structural model (MSM) that respect the continuous time nature of the underlying data processes in practice (i.e., the variables and processes are measured at irregularly spaced time points, which are not necessarily the same for all subjects).
The SFTM model assumes that the potential failure time, $U$, had the individual never received treatment and the observed failure time, $T$, follow
$$U \thicksim \int_0^T e^{\psi\times A_u}d u, $$
where $\thicksim$ means ``has the same distribution as" and $A_u$ is the treatment indicator at time $u$.
The Cox MSM model assumes that the potential failure time, $T^{\overline{a}}$, under the treatment regime $\overline{a}$ (a hypothetical treatment regime from baseline to the event time) follows a proportional hazards model with the hazard function at $u$ as
$$\lambda_0(u)e^{\psi\times a_u}.$$
It is assumed that individuals continuously received treatment until time $V$. The observed failure time can be censored. We assume an ignorable censoring mechanism in the sense that the censoring time is independent of the failure time given the treatment and covariate history.
The implemented methods can accommodate an arbitrary number of baseline and/or time-dependent covariates. If only time-independent covariates are included, the data required for analysis must contain the following information: \begin{itemize} \item{\textbf{id}:} A unique participant identifier. \item{\textbf{U}:} The time to the clinical event or censoring. \item{\textbf{deltaU}:} The clinical event indicator (1 if U is the event time; 0 otherwise). \item{\textbf{V}:} The time to optional treatment discontinuation, a clinical event, censoring, or a treatment-terminating event. \item{\textbf{deltaV}:} The indicator of optional treatment discontinuation (1 if treatment discontinuation was optional; 0 if treatment discontinuation was due to a clinical event, censoring or a treatment-terminating event). \end{itemize}
If time-dependent covariates are to be included, the data must be a time-dependent dataset as described by package \textbf{survival}. Specifically, the time-dependent data must be specified for an interval (lower,upper] and the data must include the following additional information: \begin{itemize} \item{\textbf{start}:} The lower boundary of the time interval to which the data pertain. \item{\textbf{stop}:} The upper boundary of the time interval to which the data pertain. \end{itemize}
\vspace{.15in}
The SFTM and CoxMSM are implemented through functions \textit{ctSFTM()} and \textit{ctCoxMSM()}, respectively. Both functions estimate the effect of the treatment regime (in terms of time to treatment discontinuation) for a survival outcome with time-varying treatment and confounding in the presence of dependent censoring. Function \textit{ctSFTM()} estimates the effect under a continuous time SFTM, and \textit{ctCoxMSM} estimates the effect under a Cox proportional hazards model. The functions return the estimated model parameter, $\psi$.
Functions
\textit{ctSFTM()}
This function estimates the effect of time-varying treatments on a survival outcome under the SFTM. The value object returned is a continuous-time g-estimator of $\psi$.
\vspace{.15in}
The function call takes the following form:
ctSFTM(data, base = NULL, td = NULL)
where
\begin{itemize}
\item \texttt{data} is a data.frame object containing all required data
as previously described. If only time-independent covariates are included
in the model, the data.frame must use the following column headers:
id',U', deltaU',V', and deltaV', which are defined above. If time-dependent covariates are to be included, the
data.frame must be a time-dependent dataset as described by package \textbf{survival}. Specifically, the time-dependent data must be specified for an interval
(start,stop] and the data must include two additional columns headers:start' and `stop'.
\item \texttt{base} is a character or numeric vector object or \texttt{NULL}. If baseline covariates are included in the model, \texttt{base} must be a vector containing the column headers or the column numbers of \texttt{data} that pertain to the time-independent covariates. If \texttt{NULL}, time-independent covariates are excluded from the model.
\item \texttt{td} is a character or numeric vector object or \texttt{NULL} If
time-dependent covariates are included in the model, \texttt{td} must be a vector
containing the column headers or the column numbers of data that pertain to the
time-dependent covariates. If \texttt{NULL}, time-dependent covariates are
excluded from the model. Note that this vector should \underline{not} include required
columns start' andstop'.
\end{itemize}
Note that only one of \texttt{base} and \texttt{td} can be specified as \texttt{NULL}.
\vspace{.15in}
The value object returned by \textit{ctSFTM()} an S3 object of class \textbf{ctc}, containing \$psi, the estimated model parameter, and \$coxPH, the Cox regression for V.
\vspace{.15in}
\textit{ctCoxMSM()}
This function estimates the effect of time-varying treatments on a survival outcome under the Cox proportional hazards model. The value object returned is an inverse probability of treatment weighting estimator of $\psi$.
\vspace{.15in}
The function call takes the following form:
ctCoxMSM(data, base = NULL, td = NULL)
where the inputs are as defined above for \textit{ctSFTM()} and their descriptions are not repeated here.
The value object returned by \textit{ctCoxMSM()} is also an S3 object of class \textbf{ctc}, containing \$psi, the estimated model parameter, and \$coxPH, the Cox regression for V.
\vspace{.15in}
\textit{print()}
A convenience function for displaying the primary results of the analysis.
The function call takes the following form:
print(x, ...)
where \texttt{x} is the \textbf{ctc} object returned by \textit{ctSFTM()} or \textit{ctCoxMSM()}.
\vspace{.15in}
Examples
To illustrate the call structure and results of \textit{ctSFTM()} and \textit{ctCoxMSM()}, we use the dataset provided with the package, \texttt{ctcData}. This dataset was generated only for the purposes of illustrating the package and should not be interpreted as representing a real-world dataset. The dataset contains the following observations for 1,000 participants:
\begin{itemize} \item{id} A unique participant identifier. \item{start} The left side of the time interval for time-dependent covariate xt. \item{stop} The right side of the time interval for time-dependent covariate xt. \item{xt} A continuous time-dependent covariate. \item{x} A continuous baseline covariate. \item{deltaU} A binary indicator of the clinical event. If the clinical event occurred, takes value 1; otherwise 0. \item{deltaV} A binary indicator of treatment discontinuation. If treatment discontinuation was optional, takes value 1. If treatment discontinuation was due to the clinical event, censoring, or a treatment-terminating event, takes value 0. \item{U} The time to the clinical event or censoring. \item{V} The time to optimal treatment discontinuation, the clinical event, censoring, or a treatment-terminating event. \end{itemize}
\vspace{.15in}
The data can be loaded in the usual way
data(ctcData)
head(ctcData)
\vspace{.15in}
Before considering the summary statistics of the dataset, we break the set into time-independent and time-dependent components. The time-independent data can be extracted as follows
ti <- ctcData[,c(5L:9L)] ti <- ti %>% distinct()
where we have eliminated duplicate rows using \textbf{dplyr}'s \textit{distinct()} function. The time-dependent component is trivially extracted
td <- ctcData[,2L:4L]
The summary statistics for the time-independent data
summary(object = ti)
show that the binary baseline covariate x is approximately evenly distributed across the participants; that $\sim 87\%$ of the participants experienced a clinical event; and that for $\sim 30\%$ of the participants treatment was optionally discontinued. The maximum time to a clinical event or censoring is 28.95. Considering only those participants that optionally discontinued treatment
summary(object = ti$V[ti$deltaV==1L])
we see that the $0.01 \le V \le 13.67$.
From the summary of the time-dependent data, we see that xt is a continuous variable in the range $-7.027 \le xt \le 2.736$. Measurements were taken at time points {0, 5, 10}.
summary(object = td)
\vspace{.25in}
In the first example, we estimate the parameter of the continuous time SFTM using all of the available data as follows
res <- ctSFTM(data = ctcData, base = "x", td = "xt")
\vspace{.15in}
The value object returned is an S3 object containing the estimated parameter and the Cox regression for $V$. As a precaution, we encourage users to verify that the parameters included in the Cox regression are as expected from the input. Here, we see that both $x$ and $xt$ were included.
res
To include only the baseline covariates in the model, we do not change input \texttt{td} from its default setting of \texttt{NULL}.
ctSFTM(data = ctcData, base = "x")
Note that only $x$ was included in the Cox regression.
\hspace{.25in}
Similarly, to include only the time-dependent covariates, we do not provide input \texttt{base}.
ctSFTM(data = ctcData, td = "xt")
\vspace{0.25in}
Next we estimate $\psi$ under the continuous time Cox MSM using all of the available data
res <- ctCoxMSM(data = ctcData, base = "x", td = "xt")
\vspace{.15in}
The value object returned is an S3 object containing the estimated parameter and the Cox regression for $V$. Notice that the regression results are the same as those obtained above for the full SFTM analysis. The estimated parameter, $\psi$, is similar to that obtained under the SFTM with both time-dependent and time-independent covariates.
res
\hspace{.25in}
As for the \texttt{ctSFTM()}, we can also consider only the time-independent covariates
ctCoxMSM(data = ctcData, base = "x")
\hspace{.25in}
Or, to include only the time-dependent covariates
ctCoxMSM(data = ctcData, td = "xt")
\hspace{.25in}
\noindent \textbf{References}
Yang, S., A. A. Tsiatis, and M. Blazing (2018). Modeling survival distribution as a function of time to treatment discontinuation: A dynamic treatment regime approach, \textit{Biometrics}, 74, 900–909.
Yang, S., K. Pieper, and F. Cools (2020). Semiparametric estimation of structural failure time model in continuous-time processes. \textit{Biometrika}, 107, 123–136.
Try the contTimeCausal package in your browser
Any scripts or data that you put into this service are public.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.