adjustedCurves (version 0.11.3)

plot_curve_diff: Plot the Difference Between or the Ratio of Two Adjusted Survival Curves or CIFs

Description

A function to graphically display the difference or ratio between two confounder-adjusted survival curves which where previously estimated using the adjustedsurv function or between two confounder-adjusted CIFs which where previously estimated using the adjustedcif function. The user can customize the plot using a variety of options. Internally it uses the ggplot2 package, so additional not implemented features can be added using the standard ggplot2 syntax.

Usage

plot_curve_diff(x, group_1=NULL, group_2=NULL,
                conf_int=FALSE, conf_level=0.95, type="steps",
                times=NULL, max_t=Inf, use_boot=FALSE,
                size=0.7, color="black", linetype="solid",
                alpha=1, conf_int_alpha=0.4,
                points_ci_size=NULL, points_ci_width=NULL,
                xlab="Time", ylab=NULL, title=NULL,
                subtitle=NULL, gg_theme=ggplot2::theme_classic(),
                line_at_ref=TRUE, line_at_ref_size=0.7,
                line_at_ref_color="grey", line_at_ref_linetype="dashed",
                line_at_ref_alpha=1,
                loess_smoother=FALSE, loess_span=0.75,
                loess_color=color, loess_size=size,
                loess_linetype="dashed", loess_alpha=alpha,
                test=NULL, integral_from=0, integral_to=NULL,
                p_value=FALSE, integral=FALSE,
                interval=FALSE, text_pos_x="left",
                text_pos_y="bottom", text_size=3.5,
                text_family="serif", text_fontface="italic",
                text_color="black", text_alpha=1,
                text_digits=3, text_format_p=TRUE,
                fill_area=FALSE, area_color="blue", area_alpha=0.4,
                fill_only_interval=TRUE,
                ...)
plot_curve_ratio(x, group_1=NULL, group_2=NULL, conf_int=FALSE,
                 conf_level=0.95, type="steps", times=NULL,
                 max_t=Inf, use_boot=FALSE, size=0.7, color="black",
                 linetype="solid", alpha=1,
                 conf_int_alpha=0.4, xlab="Time", ylab=NULL,
                 title=NULL, subtitle=NULL,
                 gg_theme=ggplot2::theme_classic(),
                 line_at_ref=TRUE, line_at_ref_size=0.7,
                 line_at_ref_color="grey",
                 line_at_ref_linetype="dashed",
                 line_at_ref_alpha=1, ...)

Value

Returns a ggplot2 object.

Arguments

x

An adjustedsurv object created using the adjustedsurv function or an adjustedcif object created using the adjustedcif function.

group_1

A single character string specifying one of the levels of the variable used in the original adjustedsurv or adjustedcif function call. This group will be subtracted from. For example if group_1="A" and group_2="B" the plotted curve will correspond to the survival probability (or CIF) of A minus the survival probability (or CIF) of B over time. If NULL, this will default to the first level of variable. Similarly if one plots ratios instead, the ratio would be calculated as A / B.

group_2

Also a single character string specifying one of the levels of variable. This corresponds to the right side of the difference equation. See argument group_2. If NULL, this will default to the second level of variable.

conf_int

A logical variable indicating whether the confidence intervals should be drawn. This only works when conf_int=TRUE or bootstrap=TRUE was used in the original adjustedsurv or adjustedcif function call.

conf_level

The confidence level that should be used when calculating the confidence intervals. Ignored if conf_int=FALSE.

type

Must be one of "steps" (drawing the difference/ratio as a step function), "lines" (drawing the difference/ratio using linear interpolation), "points" (drawing points only) or "none" (drawing nothing, useful when only the smoothed difference is of interest). It defaults to "steps". For ratios, only the "steps" and "lines" options are available.

times

An optional numeric vector of points in time at which the difference or ratio should be estimated. If NULL (default) the differences / ratios are estimated for the whole curve. This only affects the plot and has no effect on the integral or p_value if those are also specified.

max_t

A number indicating the latest time to which the curve should be extended to.

use_boot

Whether to use the bootstrapped estimates to calculate the confidence intervals or not. Can only be used if bootstrap=TRUE was used in the original adjustedsurv or adjustedcif function call. Ignored if conf_int=FALSE.

size

A number controlling the thickness of the curve.

color

A string specifying the color of the curve.

linetype

A string specifying the linetype of the curve.

alpha

A number controlling the transparency level of the curves.

conf_int_alpha

A number indicating the level of transparency that should be used when drawing the confidence regions.

points_ci_size

Only used when type="points". Controls the size of the error bars.

points_ci_width

Only used when type="points". Controls the width of the error bars.

xlab

A character string to be used as the X-Axis label of the plot. Defaults to "Time".

ylab

A character string to be used as the Y-Axis label of the plot. By default (NULL) uses the equation used to calculate the differences / ratios, based on the names supplied in group_1 and group_2.

title

A character string to be used as the title of the plot. Set to NULL if no title should be used.

subtitle

A character string to be used as the subtitle of the plot. Set to NULL if no subtitle should be used.

gg_theme

A ggplot2 theme object which will be used for the plot.

line_at_ref

Whether to draw a horizontal line at y = 0 for differences or at y = 1 for ratios or not.

line_at_ref_size

The size of the line drawn at the reference value. Ignored if line_at_ref=FALSE.

line_at_ref_color

The color of the line drawn at the reference value. Ignored if line_at_ref=FALSE.

line_at_ref_linetype

The linetype of the line drawn at the reference value. Ignored if line_at_ref=FALSE.

line_at_ref_alpha

The transparency level of the line drawn at the reference value. Ignored if line_at_ref=FALSE.

loess_smoother

Whether to draw a LOESS smoother through the difference curves.

loess_span

The span of the LOESS smoother. Ignored if loess_smoother=FALSE. See stat_smooth in the ggplot2 package, method="loess" for more details.

loess_color

The color of the LOESS smoother line. Ignored if loess_smoother=FALSE.

loess_size

The size of the LOESS smoother line. Ignored if loess_smoother=FALSE.

loess_linetype

The linetype of the LOESS smoother line. Ignored if loess_smoother=FALSE.

loess_alpha

The transparency level of the LOESS smoother line. Ignored if loess_smoother=FALSE.

test

An optional curve_test object created using the adjusted_curve_test function. If supplied it can be used to add a p-value and the integral statistic to the plot. Alternatively, the needed arguments below can be specified to obtain the values needed for the test. See below. Set to NULL (default) to ignore this.

integral_from

A number specifying the left limit of the integral. When p_value=TRUE and test=NULL, this argument will be passed to the from argument in the adjusted_curve_test function to perform the test.

integral_to

A number specifying the right limit of the integral. When p_value=TRUE and test=NULL, this argument will be passed to the to argument in the adjusted_curve_test function to perform the test.

p_value

Whether to add a p-value to the plot or not. This requires either that the user supplies a previously created curve_test object to the test argument, or that the required arguments to call this function are supplied (at least integral_to). Either way it only works if bootstrap=TRUE was used in the original adjustedsurv or adjustedcif function call.

integral

Whether to add the integral of the difference in the interval [from, to] to the plot or not. This requires either that the user supplies a previously created curve_test object to the test argument, or that the required arguments to call this function are supplied (at least integral_to).

interval

Whether to add the interval in which the integral was calculated to the plot as well.

text_pos_x

X position of the text. Can be either "left" (default), "middle", "right" or a number specifying the exact position.

text_pos_y

Y position of the text. Can be either "bottom" (default), "middle", "top" or a number specifying the exact position.

text_digits

The number of digits to which the p-value and the integral of the difference should be rounded to.

text_size

The size of the text.

text_family

The family of the text. Defaults to "serif".

text_fontface

The fontface of the text. Defaults to "italic".

text_color

The color of the text. Defaults to "black".

text_alpha

The transparency level of the text.

text_format_p

Whether to format p-values smaller than 0.01 to < 0.01.

fill_area

Whether to add color to the area between 0 and the difference.

area_color

The color used to fill in the area between 0 and the difference when using fill_area=TRUE. Ignored otherwise.

area_alpha

The transparency level used to fill in the area between 0 and the difference when using fill_area=TRUE. Ignored otherwise.

fill_only_interval

Whether only the area corresponding to the interval defined by integral_from and integral_to should be filled. Only used when fill_area=TRUE.

...

Currently not used.

Author

Robin Denz

Details

This function allows the easy creation of difference / ratio curves. The syntax is exactly the same for both adjusted survival curves and adjusted CIFs. Similarly, the syntax is the same for ratios and for difference curves, although not all options of the difference curve function are available for the ratio curve function. By default it calculates the estimates up to the last point where estimates for both the group_1 curve and the group_2 curve are available.

It currently does not support plotting multiple curves at once, which could be useful when there are more than two treatment groups in variable. If the user is interested in this, we recommend calling this function multiple times with the desired comparisons and concatenating the individual plots into one plot afterwards using a suitable function such as par or ggarrange.

More information on how the differences or ratios and their confidence intervals are calculated can be found in the documentation of the adjusted_curve_diff function. More information on how the overall p-value and the integral are calculated for differences can be found in the adjusted_curve_test function.

References

Michael Coory, Karen E. Lamb, and Michael Sorich (2014). "Risk-Difference Curves can be used to Communicate Time-Dependent Effects of Adjuvant Therapies for Early Stage Cancer". In: Journal of Clinical Epidemiology 67, pp. 966-972

Lihui Zhao, Lu Tian, Hajime Uno, Scott D. Solomon, Marc A. Pfeffer, Jerald S. Schindler, and L. J. Wei (2012). "Utilizing the Integrated Difference of Two Survival Functions to Quantify the Treatment Contrast for Designing, Monitoring and Analyzing a Comparative Clinical Study". In: Clinical Trials 9.5, pp. 570-577

See Also

adjusted_curve_diff, adjusted_curve_test, adjustedsurv, adjustedcif, ggplot, geom_stepribbon

Examples

library(adjustedCurves)
library(survival)

if (requireNamespace("ggplot2") & requireNamespace("riskRegression")) {

library(ggplot2)

set.seed(42)

# simulate some data as example
sim_dat <- sim_confounded_surv(n=50, max_t=1.2)
sim_dat$group <- as.factor(sim_dat$group)

# estimate a cox-regression for the outcome
cox_mod <- coxph(Surv(time, event) ~ x1 + x2 + x3 + x4 + x5 + x6 + group,
                 data=sim_dat, x=TRUE)


# use it to calculate adjusted survival curves with bootstrapping
adjsurv <- adjustedsurv(data=sim_dat,
                        variable="group",
                        ev_time="time",
                        event="event",
                        method="direct",
                        outcome_model=cox_mod,
                        conf_int=TRUE,
                        bootstrap=TRUE,
                        n_boot=15) # should be much bigger in reality

# plot the difference with default values
plot_curve_diff(adjsurv)

# plot the ratio with default values
plot_curve_ratio(adjsurv)

# plot with reversed differences
plot_curve_diff(adjsurv, group_1="1", group_2="0")

# plot with confidence intervals
plot_curve_diff(adjsurv, conf_int=TRUE)
plot_curve_ratio(adjsurv, conf_int=TRUE)

# plot using lines instead
plot_curve_diff(adjsurv, conf_int=TRUE, type="lines")

# plot using points instead
plot_curve_diff(adjsurv, conf_int=TRUE, type="points")

# plot using an additional loess smoother
plot_curve_diff(adjsurv, loess_smoother=TRUE)

# plot without the line at reference
plot_curve_diff(adjsurv, line_at_ref=FALSE)
plot_curve_ratio(adjsurv, line_at_ref=FALSE)

# plot with some custom parameters
plot_curve_diff(adjsurv, conf_int=TRUE, color="blue", linetype="dotted",
                alpha=0.8, line_at_ref_size=1.1, line_at_ref_color="red",
                loess_smoother=TRUE, loess_span=0.55)

# adding a p-value for a difference test in the interval [0, 0.75]
plot_curve_diff(adjsurv, conf_int=TRUE, p_value=TRUE, integral_from=0,
                integral_to=0.75, integral=TRUE)

# adding a p-value for a difference test in the interval [0, 0.75],
# and also showing that integral visually in the plot
plot_curve_diff(adjsurv, conf_int=FALSE, p_value=TRUE, integral_from=0,
                integral_to=0.75, integral=TRUE, fill_area=TRUE,
                interval=TRUE)
}