Visualize the Effect of a Continuous Variable on a Time-To-Event Outcome
contsurvplot-package.RdWhat is this package about?
This package provides different plotting routines to visualize the (causal) effect of a continuous variable on a time-to-event outcome using a previously fit model and g-computation. Unlike simpler alternatives, such as plotting survival curves for some categories, these plots always correspond to the results obtained by the time-to-event model and give an accurate depiction of the causal effect, if all assumptions are met.
What features are included in this package?
The package includes 11 different plot functions, most based on the ggplot2 package. Those 11 plotting routines include value specific survival curves, landmark survival probability plots, survival time quantile plots, survival probability heatmaps, and survival area plots, among others. A description and comparison of these plots can be found in the article associated with this R-package (Denz & Timmesfeld 2022).
What does a typical workflow using this package look like?
All the user has to do is fit a time-to-event model, such as the cox-model, including the continuous variable of interest (and possibly confounders) and plug it into one of the plot functions included in this package. Many different kind of models are supported. See curve_cont for more details.
What type of plot should I use?
There is no general answer to this question, but we would usually suggest using a plot method that is able to visualize the causal survival probability both as a function of time and as a function of the continuous variable. The plot_surv_area, plot_surv_heatmap and plot_surv_contour functions do just that. More discussion about this topic can be found in the vignette and the associated paper.
What is the difference between displaying causal effects and associations?
The plots generated by this package offer different ways to depict the association between a continuous variable and a time-to-event outcome. Under certain causal identifiability assumptions, which are described in detail in our article on this topic (see references), this association can be endowed with a causal interpretation. Under these assumptions, the estimates can be interpreted as the survival probability that would have been observed if all individuals in the target population had received a specific level of the continuous variable. If these assumptions are not met, this interpretation is invalid.
Where can I get more information?
The documentation pages contain a lot of information, relevant examples and literature references. Additional examples can be found in the vignette of this package, which can be accessed using vignette(topic="introduction", package="contsurvplot"). We also published a preprint of the article about this package on arXiv (see references), which contains an in-depth discussion about the plots and how to interpret them.
I want to suggest a new feature / I want to report a bug. Where can I do this?
Bug reports, suggestions and feature requests are highly welcome. Please file an issue on the official github page (<https://github.com/RobinDenz1/contsurvplot>) or contact the author directly using the supplied e-mail address.
References
Robin Denz, Nina Timmesfeld (2023). "Visualizing the (Causal) Effect of a Continuous Variable on a Time-To-Event Outcome". In: Epidemiology 34.5
James Robins. A New Approach to Causal Inference in Mortality Studies with a Sustained Exposure Period: Application to Control of the Healthy Worker Survivor Effect. Mathematical Modelling (1986) 7, pages 1393-1512.