plot_auc_precision_recall_curve: Plot the precision-recall curve.

Description

This method creates precision-recall curves based on data in a familiarCollection object.

Usage

plot_auc_precision_recall_curve(
  object,
  draw = FALSE,
  dir_path = NULL,
  split_by = NULL,
  color_by = NULL,
  facet_by = NULL,
  facet_wrap_cols = NULL,
  ggtheme = NULL,
  discrete_palette = NULL,
  x_label = waiver(),
  y_label = waiver(),
  legend_label = waiver(),
  plot_title = waiver(),
  plot_sub_title = waiver(),
  caption = NULL,
  x_n_breaks = 5L,
  x_breaks = NULL,
  y_n_breaks = 5L,
  y_breaks = NULL,
  conf_int_style = c("ribbon", "step", "none"),
  conf_int_alpha = 0.2,
  width = waiver(),
  height = waiver(),
  units = waiver(),
  export_collection = FALSE,
  ...
)
# S4 method for ANY
plot_auc_precision_recall_curve(
  object,
  draw = FALSE,
  dir_path = NULL,
  split_by = NULL,
  color_by = NULL,
  facet_by = NULL,
  facet_wrap_cols = NULL,
  ggtheme = NULL,
  discrete_palette = NULL,
  x_label = waiver(),
  y_label = waiver(),
  legend_label = waiver(),
  plot_title = waiver(),
  plot_sub_title = waiver(),
  caption = NULL,
  x_n_breaks = 5L,
  x_breaks = NULL,
  y_n_breaks = 5L,
  y_breaks = NULL,
  conf_int_style = c("ribbon", "step", "none"),
  conf_int_alpha = 0.2,
  width = waiver(),
  height = waiver(),
  units = waiver(),
  export_collection = FALSE,
  ...
)
# S4 method for familiarCollection
plot_auc_precision_recall_curve(
  object,
  draw = FALSE,
  dir_path = NULL,
  split_by = NULL,
  color_by = NULL,
  facet_by = NULL,
  facet_wrap_cols = NULL,
  ggtheme = NULL,
  discrete_palette = NULL,
  x_label = waiver(),
  y_label = waiver(),
  legend_label = waiver(),
  plot_title = waiver(),
  plot_sub_title = waiver(),
  caption = NULL,
  x_n_breaks = 5L,
  x_breaks = NULL,
  y_n_breaks = 5L,
  y_breaks = NULL,
  conf_int_style = c("ribbon", "step", "none"),
  conf_int_alpha = 0.2,
  width = waiver(),
  height = waiver(),
  units = waiver(),
  export_collection = FALSE,
  ...
)

Value

NULL or list of plot objects, if dir_path is NULL.

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.

Additionally, some familiarData objects can be created from prediction tables (familiarDataElementPredictionTable). Other familiarData objects can be created from data (dataObject, or data.table). Please check details for more information.

draw

(optional) Draws the plot if TRUE.

dir_path

(optional) Path to the directory where the plots of receiver operating characteristic curves are saved to. Output is saved in the performance 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.

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.

ggtheme

(optional) ggplot theme to use for plotting.

discrete_palette

(optional) Palette for colouring the plot elements according to the groupings indicated by the color_by argument (if any). familiar has a default palette. Other palettes are supported by paletteer, 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. You may also specify your own palette by providing a vector of colour names listed by grDevices::colors() or through hexadecimal RGB strings.

x_label

(optional) Label to provide to the x-axis. If NULL, no label is shown.

y_label

(optional) Label to provide to the y-axis. If NULL, no label is shown.

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_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_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.

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.

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 the number of features and the number of facets.

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

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). Only applies when converting pixel units, as is typical for 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.

Details

This function generates area under the precision-recall curve plots.

Available splitting variables are: vimp_method, learner, data_set and positive_class. By default, the data is split by vimp_method and learner, with faceting by data_set and colouring by positive_class.

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.

Bootstrap confidence intervals of the ROC curve (if present) 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 ROC curve.
step (default): confidence intervals are shown as a step function around the point estimate of the ROC curve.
none: confidence intervals are not shown. The point estimate of the ROC curve is shown as usual.

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