plot_surv_matrix {contsurvplot} | R Documentation |

## Plot a Discretized Heatmap of the Effect of a Continuous Covariate on a Time-To-Event Outcome

### Description

Using a previously fit time-to-event model, this function plots a discretized heatmap with the continuous covariate on the y-axis and the time-to-event on the x-axis. This is essentially a discretized version of the `plot_surv_heatmap`

plot, which makes it look very similar to a correlation matrix.

### Usage

```
plot_surv_matrix(time, status, variable, group=NULL, data, model,
cif=FALSE, na.action=options()$na.action,
horizon=NULL, fixed_t=NULL, max_t=Inf,
n_col=10, n_row=10,
start_color="red", end_color="blue",
alpha=1, xlab="Time", ylab=variable,
title=NULL, subtitle=NULL,
legend.title="S(t)", legend.position="none",
gg_theme=ggplot2::theme_bw(),
facet_args=list(),
panel_border=FALSE, axis_dist=0,
border_color="white", border_size=0.5,
numbers=TRUE, number_color="white",
number_size=3, number_family="sans",
number_fontface="plain", number_digits=2,
...)
```

### Arguments

`time` |
A single character string specifying the time-to-event variable. Needs to be a valid column name of a numeric variable in |

`status` |
A single character string specifying the status variable, indicating if a person has experienced an event or not. Needs to be a valid column name of a numeric or logical variable in |

`variable` |
A single character string specifying the continuous variable of interest, for which the survival curves should be estimated. This variable has to be contained in the |

`group` |
An optional single character string specifying a factor variable in |

`data` |
A |

`model` |
A model describing the time-to-event process (such as an |

`cif` |
Whether to plot the cumulative incidence (CIF) instead of the survival probability. If multiple failure types are present, the survival probability cannot be estimated in an unbiased way. This function will always return CIF estimates in that case. |

`na.action` |
How missing values should be handled. Can be one of: |

`horizon` |
A numeric vector containing a range of values of |

`fixed_t` |
A numeric vector containing points in time at which the survival probabilities should be calculated or |

`max_t` |
A number indicating the latest survival time which is to be plotted. |

`n_col` |
The number of columns to use in the matrix style heatmap. This parameter only controls how many tiles are shown, not how many are estimated. The amount of estimated probabilities is controlled using the |

`n_row` |
The number of rows to use in the matrix style heatmap. See |

`start_color` |
The color used for the lowest value in |

`end_color` |
The color used for the highest value in |

`alpha` |
The transparency level of the plot. |

`xlab` |
A character string used as the x-axis label of the plot. |

`ylab` |
A character string used as the y-axis label of the plot. |

`title` |
A character string used as the title of the plot. |

`subtitle` |
A character string used as the subtitle of the plot. |

`legend.title` |
A character string used as the legend title of the plot. |

`legend.position` |
Where to put the legend. See |

`gg_theme` |
A ggplot2 theme which is applied to the plot. |

`facet_args` |
A named list of arguments that are passed to the |

`panel_border` |
Whether to draw a border around the heatmap or not. Is set to FALSE by default to mimic standard heatmaps. |

`axis_dist` |
The distance of the axis ticks to the colored heatmap. Is set to 0 by default to mimic standard heatmaps. |

`border_color` |
The color of the individual rectangles borders. Defaults to |

`border_size` |
The size of the individual rectangles borders. Defaults to 0.5. |

`numbers` |
Whether to put the numbers of the average estimated probabilities into the rectangles or not. Defaults to |

`number_color` |
The color of the numbers inside the rectangles. Ignored if |

`number_size` |
The size of the numbers inside the rectangles. Ignored if |

`number_family` |
The font family of the numbers inside the rectangles. Ignored if |

`number_fontface` |
The fontface of the numbers inside the rectangles. Ignored if |

`number_digits` |
The amount of digits the numbers inside the rectangles should be rounded to. Ignored if |

`...` |
Further arguments passed to |

### Details

Heatmaps are a great tool to visualize a three dimensional surface in a two-dimensional plot. Continuously changing colors over a single area can, however, be difficult to interpret correctly if the color does not change a lot. This version makes the heatmap easier to understand by discretizing the space into equally spaced rectangles. The survival or failure probability is still estimated at a very fine grid of points in time (controlled using the `fixed_t`

and `horizon`

arguments), but is then aggregated into average probabilities afterwards. The number inside each rectangle then shows the *average* probability inside the region defined by the rectangle. This makes the plot look a lot like a correlation matrix.

The dimensions of the plot can be controlled using the `n_col`

and `n_row`

arguments. Using high numbers in these parameters makes the plot look more similar to a standard `plot_surv_heatmap`

plot. It is recommended to create the `plot_surv_heatmap`

plot first to pick appropriate dimensions for the discretized version here.

### Value

Returns a `ggplot2`

object.

### Author(s)

Robin Denz

### References

Robin Denz, Nina Timmesfeld (2023). "Visualizing the (Causal) Effect of a Continuous Variable on a Time-To-Event Outcome". In: Epidemiology 34.5

### Examples

```
library(contsurvplot)
library(riskRegression)
library(survival)
library(ggplot2)
library(splines)
# using data from the survival package
data(nafld, package="survival")
# take a random sample to keep example fast
set.seed(42)
nafld1 <- nafld1[sample(nrow(nafld1), 150), ]
# fit cox-model with age
model <- coxph(Surv(futime, status) ~ age, data=nafld1, x=TRUE)
# plot effect of age on survival using defaults
plot_surv_matrix(time="futime",
status="status",
variable="age",
data=nafld1,
model=model)
# plot it only for 60 to 80 year old people
plot_surv_matrix(time="futime",
status="status",
variable="age",
data=nafld1,
model=model,
horizon=seq(60, 80, 0.5))
## showing non-linear effects
# fit cox-model with bmi modelled using B-Splines,
# adjusting for age and sex
model2 <- coxph(Surv(futime, status) ~ age + male + bs(bmi, df=3),
data=nafld1, x=TRUE)
# plot effect of bmi on survival using defaults
plot_surv_matrix(time="futime",
status="status",
variable="bmi",
data=nafld1,
model=model2)
```

*contsurvplot*version 0.2.1 Index]