plot_kaplan_meier-methods: Plot Kaplan-Meier survival curves.
In familiar: End-to-End Automated Machine Learning and Model Evaluation

plot_kaplan_meier

R Documentation

Plot Kaplan-Meier survival curves.

Description

This function creates Kaplan-Meier survival curves from stratification data stored in a familiarCollection object.

Usage

plot_kaplan_meier(
  object,
  draw = FALSE,
  dir_path = NULL,
  split_by = NULL,
  color_by = NULL,
  linetype_by = NULL,
  facet_by = NULL,
  facet_wrap_cols = NULL,
  combine_legend = TRUE,
  ggtheme = NULL,
  discrete_palette = NULL,
  x_label = "time",
  x_label_shared = "column",
  y_label = "survival probability",
  y_label_shared = "row",
  legend_label = waiver(),
  plot_title = waiver(),
  plot_sub_title = waiver(),
  caption = NULL,
  x_range = NULL,
  x_n_breaks = 5,
  x_breaks = NULL,
  y_range = c(0, 1),
  y_n_breaks = 5,
  y_breaks = NULL,
  confidence_level = NULL,
  conf_int_style = c("ribbon", "step", "none"),
  conf_int_alpha = 0.4,
  censoring = TRUE,
  censor_shape = "plus",
  show_logrank = TRUE,
  show_survival_table = TRUE,
  width = waiver(),
  height = waiver(),
  units = waiver(),
  export_collection = FALSE,
  ...
)

## S4 method for signature 'ANY'
plot_kaplan_meier(
  object,
  draw = FALSE,
  dir_path = NULL,
  split_by = NULL,
  color_by = NULL,
  linetype_by = NULL,
  facet_by = NULL,
  facet_wrap_cols = NULL,
  combine_legend = TRUE,
  ggtheme = NULL,
  discrete_palette = NULL,
  x_label = "time",
  x_label_shared = "column",
  y_label = "survival probability",
  y_label_shared = "row",
  legend_label = waiver(),
  plot_title = waiver(),
  plot_sub_title = waiver(),
  caption = NULL,
  x_range = NULL,
  x_n_breaks = 5,
  x_breaks = NULL,
  y_range = c(0, 1),
  y_n_breaks = 5,
  y_breaks = NULL,
  confidence_level = NULL,
  conf_int_style = c("ribbon", "step", "none"),
  conf_int_alpha = 0.4,
  censoring = TRUE,
  censor_shape = "plus",
  show_logrank = TRUE,
  show_survival_table = TRUE,
  width = waiver(),
  height = waiver(),
  units = waiver(),
  export_collection = FALSE,
  ...
)

## S4 method for signature 'familiarCollection'
plot_kaplan_meier(
  object,
  draw = FALSE,
  dir_path = NULL,
  split_by = NULL,
  color_by = NULL,
  linetype_by = NULL,
  facet_by = NULL,
  facet_wrap_cols = NULL,
  combine_legend = TRUE,
  ggtheme = NULL,
  discrete_palette = NULL,
  x_label = "time",
  x_label_shared = "column",
  y_label = "survival probability",
  y_label_shared = "row",
  legend_label = waiver(),
  plot_title = waiver(),
  plot_sub_title = waiver(),
  caption = NULL,
  x_range = NULL,
  x_n_breaks = 5,
  x_breaks = NULL,
  y_range = c(0, 1),
  y_n_breaks = 5,
  y_breaks = NULL,
  confidence_level = NULL,
  conf_int_style = c("ribbon", "step", "none"),
  conf_int_alpha = 0.4,
  censoring = TRUE,
  censor_shape = "plus",
  show_logrank = TRUE,
  show_survival_table = TRUE,
  width = waiver(),
  height = waiver(),
  units = waiver(),
  export_collection = FALSE,
  ...
)

Arguments

`object`	`familiarCollection` object, or one or more `familiarData` objects, that will be internally converted to a `familiarCollection` object. It is also possible to provide a `familiarEnsemble` or one or more `familiarModel` objects together with the data from which data is computed prior to export. Paths to such files can also be provided.
`draw`	(optional) Draws the plot if TRUE.
`dir_path`	(optional) Path to the directory where created figures are saved to. Output is saved in the `stratification` subdirectory. If `NULL` no figures are saved, but are returned instead.
`split_by`	(optional) Splitting variables. This refers to column names on which datasets are split. A separate figure is created for each split. See details for available variables.
`color_by`	(optional) Variables used to determine fill colour of plot objects. The variables cannot overlap with those provided to the `split_by` argument, but may overlap with other arguments. See details for available variables.
`linetype_by`	(optional) Variables that are used to determine the linetype of lines in a plot. The variables cannot overlap with those provided to the `split_by` argument, but may overlap with other arguments. Sett details for available variables.
`facet_by`	(optional) Variables used to determine how and if facets of each figure appear. In case the `facet_wrap_cols` argument is `NULL`, the first variable is used to define columns, and the remaing variables are used to define rows of facets. The variables cannot overlap with those provided to the `split_by` argument, but may overlap with other arguments. See details for available variables.
`facet_wrap_cols`	(optional) Number of columns to generate when facet wrapping. If NULL, a facet grid is produced instead.
`combine_legend`	(optional) Flag to indicate whether the same legend is to be shared by multiple aesthetics, such as those specified by `color_by` and `linetype_by` arguments.
`ggtheme`	(optional) `ggplot` theme to use for plotting.
`discrete_palette`	(optional) Palette to use to color the different risk strata in case a non-singular variable was provided to the `color_by` argument.
`x_label`	(optional) Label to provide to the x-axis. If NULL, no label is shown.
`x_label_shared`	(optional) Sharing of x-axis labels between facets. One of three values: `overall`: A single label is placed at the bottom of the figure. Tick text (but not the ticks themselves) is removed for all but the bottom facet plot(s). `column`: A label is placed at the bottom of each column. Tick text (but not the ticks themselves) is removed for all but the bottom facet plot(s). `individual`: A label is placed below each facet plot. Tick text is kept.
`y_label`	(optional) Label to provide to the y-axis. If NULL, no label is shown.
`y_label_shared`	(optional) Sharing of y-axis labels between facets. One of three values: `overall`: A single label is placed to the left of the figure. Tick text (but not the ticks themselves) is removed for all but the left-most facet plot(s). `row`: A label is placed to the left of each row. Tick text (but not the ticks themselves) is removed for all but the left-most facet plot(s). `individual`: A label is placed below each facet plot. Tick text is kept.
`legend_label`	(optional) Label to provide to the legend. If NULL, the legend will not have a name.
`plot_title`	(optional) Label to provide as figure title. If NULL, no title is shown.
`plot_sub_title`	(optional) Label to provide as figure subtitle. If NULL, no subtitle is shown.
`caption`	(optional) Label to provide as figure caption. If NULL, no caption is shown.
`x_range`	(optional) Value range for the x-axis.
`x_n_breaks`	(optional) Number of breaks to show on the x-axis of the plot. `x_n_breaks` is used to determine the `x_breaks` argument in case it is unset.
`x_breaks`	(optional) Break points on the x-axis of the plot.
`y_range`	(optional) Value range for the y-axis.
`y_n_breaks`	(optional) Number of breaks to show on the y-axis of the plot. `y_n_breaks` is used to determine the `y_breaks` argument in case it is unset.
`y_breaks`	(optional) Break points on the y-axis of the plot.
`confidence_level`	(optional) Confidence level for the strata in the plot.
`conf_int_style`	(optional) Confidence interval style. See details for allowed styles.
`conf_int_alpha`	(optional) Alpha value to determine transparency of confidence intervals or, alternatively, other plot elements with which the confidence interval overlaps. Only values between 0.0 (fully transparent) and 1.0 (fully opaque) are allowed.
`censoring`	(optional) Flag to indicate whether censored samples should be indicated on the survival curve.
`censor_shape`	(optional) Shape used to indicate censored samples on the survival curve. Available shapes are documented in the `ggplot2` vignette Aesthetic specifications. By default a plus shape is used.
`show_logrank`	(optional) Specifies whether the results of a logrank test to assess differences between the risk strata is annotated in the plot. A log-rank test can only be shown when `color_by` and `linestyle_by` are either unset, or only contain `risk_group`.
`show_survival_table`	(optional) Specifies whether a survival table is shown below the Kaplan-Meier survival curves. Survival in the risk strata is assessed for each of the breaks in `x_breaks`.
`width`	(optional) Width of the plot. A default value is derived from the number of facets.
`height`	(optional) Height of the plot. A default value is derived from number of facets and the inclusion of survival tables.
`units`	(optional) Plot size unit. Either `cm` (default), `mm` or `⁠in⁠`.
`export_collection`	(optional) Exports the collection if TRUE.
`...`	Arguments passed on to `as_familiar_collection`, `ggplot2::ggsave`, `extract_risk_stratification_data` `familiar_data_names` Names of the dataset(s). Only used if the `object` parameter is one or more `familiarData` objects. `collection_name` Name of the collection. `device` Device to use. Can either be a device function (e.g. png), or one of "eps", "ps", "tex" (pictex), "pdf", "jpeg", "tiff", "png", "bmp", "svg" or "wmf" (windows only). If `NULL` (default), the device is guessed based on the `filename` extension. `scale` Multiplicative scaling factor. `dpi` Plot resolution. Also accepts a string input: "retina" (320), "print" (300), or "screen" (72). Applies only to raster output types. `limitsize` When `TRUE` (the default), `ggsave()` will not save images larger than 50x50 inches, to prevent the common error of specifying dimensions in pixels. `bg` Background colour. If `NULL`, uses the `plot.background` fill value from the plot theme. `create.dir` Whether to create new directories if a non-existing directory is specified in the `filename` or `path` (`TRUE`) or return an error (`FALSE`, default). If `FALSE` and run in an interactive session, a prompt will appear asking to create a new directory when necessary. `data` A `dataObject` object, `data.table` or `data.frame` that constitutes the data that are assessed. `is_pre_processed` Flag that indicates whether the data was already pre-processed externally, e.g. normalised and clustered. Only used if the `data` argument is a `data.table` or `data.frame`. `cl` Cluster created using the `parallel` package. This cluster is then used to speed up computation through parallellisation. `ensemble_method` Method for ensembling predictions from models for the same sample. Available methods are: `median` (default): Use the median of the predicted values as the ensemble value for a sample. `mean`: Use the mean of the predicted values as the ensemble value for a sample. `verbose` Flag to indicate whether feedback should be provided on the computation and extraction of various data elements. `message_indent` Number of indentation steps for messages shown during computation and extraction of various data elements. `detail_level` (optional) Sets the level at which results are computed and aggregated. `ensemble`: Results are computed at the ensemble level, i.e. over all models in the ensemble. This means that, for example, bias-corrected estimates of model performance are assessed by creating (at least) 20 bootstraps and computing the model performance of the ensemble model for each bootstrap. `hybrid` (default): Results are computed at the level of models in an ensemble. This means that, for example, bias-corrected estimates of model performance are directly computed using the models in the ensemble. If there are at least 20 trained models in the ensemble, performance is computed for each model, in contrast to `ensemble` where performance is computed for the ensemble of models. If there are less than 20 trained models in the ensemble, bootstraps are created so that at least 20 point estimates can be made. `model`: Results are computed at the model level. This means that, for example, bias-corrected estimates of model performance are assessed by creating (at least) 20 bootstraps and computing the performance of the model for each bootstrap. Note that each level of detail has a different interpretation for bootstrap confidence intervals. For `ensemble` and `model` these are the confidence intervals for the ensemble and an individual model, respectively. That is, the confidence interval describes the range where an estimate produced by a respective ensemble or model trained on a repeat of the experiment may be found with the probability of the confidence level. For `hybrid`, it represents the range where any single model trained on a repeat of the experiment may be found with the probability of the confidence level. By definition, confidence intervals obtained using `hybrid` are at least as wide as those for `ensemble`. `hybrid` offers the correct interpretation if the goal of the analysis is to assess the result of a single, unspecified, model. `hybrid` is generally computationally less expensive then `ensemble`, which in turn is somewhat less expensive than `model`. A non-default `detail_level` parameter can be specified for separate evaluation steps by providing a parameter value in a named list with data elements, e.g. `list("auc_data"="ensemble", "model_performance"="hybrid")`. This parameter can be set for the following data elements: `auc_data`, `decision_curve_analyis`, `model_performance`, `permutation_vimp`, `ice_data`, `prediction_data` and `confusion_matrix`.

Details

This function generates a Kaplan-Meier survival plot based on risk group stratification by the learners.

familiar does not determine what units the x-axis has or what kind of survival the y-axis represents. It is therefore recommended to provide x_label and y_label arguments.

Available splitting variables are: fs_method, learner, data_set, risk_group and stratification_method. By default, separate figures are created for each combination of fs_method and learner, with faceting by data_set, colouring of the strata in each individual plot by risk_group.

Available palettes for discrete_palette are those listed by grDevices::palette.pals() (requires R >= 4.0.0), grDevices::hcl.pals() (requires R >= 3.6.0) and rainbow, heat.colors, terrain.colors, topo.colors and cm.colors, which correspond to the palettes of the same name in grDevices. If not specified, a default palette based on palettes in Tableau are used. You may also specify your own palette by using colour names listed by grDevices::colors() or through hexadecimal RGB strings.

Greenwood confidence intervals of the Kaplan-Meier curve can be shown using various styles set by conf_int_style:

ribbon (default): confidence intervals are shown as a ribbon with an opacity of conf_int_alpha around the point estimate of the Kaplan-Meier curve.
step (default): confidence intervals are shown as a step function around the point estimate of the Kaplan-Meier curve.
none: confidence intervals are not shown. The point estimate of the ROC curve is shown as usual.

Labelling methods such as set_risk_group_names or set_data_set_names can be applied to the familiarCollection object to update labels, and order the output in the figure.