plot_univariate_importance-methods: Plot univariate importance.
In familiar: End-to-End Automated Machine Learning and Model Evaluation

plot_univariate_importance

R Documentation

Plot univariate importance.

Description

This function plots the univariate analysis data stored in a familiarCollection object.

Usage

plot_univariate_importance(
  object,
  feature_cluster_method = waiver(),
  feature_linkage_method = waiver(),
  feature_cluster_cut_method = waiver(),
  feature_similarity_threshold = waiver(),
  draw = FALSE,
  dir_path = NULL,
  p_adjustment_method = waiver(),
  split_by = NULL,
  color_by = NULL,
  facet_by = NULL,
  facet_wrap_cols = NULL,
  show_cluster = TRUE,
  ggtheme = NULL,
  discrete_palette = NULL,
  gradient_palette = waiver(),
  x_label = waiver(),
  y_label = "feature",
  legend_label = waiver(),
  plot_title = waiver(),
  plot_sub_title = waiver(),
  caption = NULL,
  limit_n_features = waiver(),
  x_range = NULL,
  x_n_breaks = 5L,
  x_breaks = NULL,
  significance_level_shown = 0.05,
  width = waiver(),
  height = waiver(),
  units = waiver(),
  verbose = TRUE,
  export_collection = FALSE,
  ...
)

## S4 method for signature 'ANY'
plot_univariate_importance(
  object,
  feature_cluster_method = waiver(),
  feature_linkage_method = waiver(),
  feature_cluster_cut_method = waiver(),
  feature_similarity_threshold = waiver(),
  draw = FALSE,
  dir_path = NULL,
  p_adjustment_method = waiver(),
  split_by = NULL,
  color_by = NULL,
  facet_by = NULL,
  facet_wrap_cols = NULL,
  show_cluster = TRUE,
  ggtheme = NULL,
  discrete_palette = NULL,
  gradient_palette = waiver(),
  x_label = waiver(),
  y_label = "feature",
  legend_label = waiver(),
  plot_title = waiver(),
  plot_sub_title = waiver(),
  caption = NULL,
  limit_n_features = waiver(),
  x_range = NULL,
  x_n_breaks = 5L,
  x_breaks = NULL,
  significance_level_shown = 0.05,
  width = waiver(),
  height = waiver(),
  units = waiver(),
  verbose = TRUE,
  export_collection = FALSE,
  ...
)

## S4 method for signature 'familiarCollection'
plot_univariate_importance(
  object,
  feature_cluster_method = waiver(),
  feature_linkage_method = waiver(),
  feature_cluster_cut_method = waiver(),
  feature_similarity_threshold = waiver(),
  draw = FALSE,
  dir_path = NULL,
  p_adjustment_method = waiver(),
  split_by = NULL,
  color_by = NULL,
  facet_by = NULL,
  facet_wrap_cols = NULL,
  show_cluster = TRUE,
  ggtheme = NULL,
  discrete_palette = NULL,
  gradient_palette = waiver(),
  x_label = waiver(),
  y_label = "feature",
  legend_label = waiver(),
  plot_title = waiver(),
  plot_sub_title = waiver(),
  caption = NULL,
  limit_n_features = waiver(),
  x_range = NULL,
  x_n_breaks = 5L,
  x_breaks = NULL,
  significance_level_shown = 0.05,
  width = waiver(),
  height = waiver(),
  units = waiver(),
  verbose = TRUE,
  export_collection = FALSE,
  ...
)

Arguments

`object`	A `familiarCollection` object, or other other objects from which a `familiarCollection` can be extracted. See details for more information.
`feature_cluster_method`	The method used to perform clustering. These are the same methods as for the `cluster_method` configuration parameter: `none`, `hclust`, `agnes`, `diana` and `pam`. `none` cannot be used when extracting data regarding mutual correlation or feature expressions. If not provided explicitly, this parameter is read from settings used at creation of the underlying `familiarModel` objects.
`feature_linkage_method`	The method used for agglomerative clustering in `hclust` and `agnes`. These are the same methods as for the `cluster_linkage_method` configuration parameter: `average`, `single`, `complete`, `weighted`, and `ward`. If not provided explicitly, this parameter is read from settings used at creation of the underlying `familiarModel` objects.
`feature_cluster_cut_method`	The method used to divide features into separate clusters. The available methods are the same as for the `cluster_cut_method` configuration parameter: `silhouette`, `fixed_cut` and `dynamic_cut`. `silhouette` is available for all cluster methods, but `fixed_cut` only applies to methods that create hierarchical trees (`hclust`, `agnes` and `diana`). `dynamic_cut` requires the `dynamicTreeCut` package and can only be used with `agnes` and `hclust`. If not provided explicitly, this parameter is read from settings used at creation of the underlying `familiarModel` objects.
`feature_similarity_threshold`	The threshold level for pair-wise similarity that is required to form feature clusters with the `fixed_cut` method. If not provided explicitly, this parameter is read from settings used at creation of the underlying `familiarModel` objects.
`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 `variable_importance` subdirectory. If NULL no figures are saved, but are returned instead.
`p_adjustment_method`	(optional) Indicates type of p-value that is shown. One of `holm`, `hochberg`, `hommel`, `bonferroni`, `BH`, `BY`, `fdr`, `none`, `p_value` or `q_value` for adjusted p-values, uncorrected p-values
`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.
`show_cluster`	(optional) Show which features were clustered together.
`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.
`gradient_palette`	(optional) Palette to use for filling the bars in case the `color_by` argument is not set. The bars are then coloured according to their importance. By default, no gradient is used, and the bars are not filled according to importance. Use `NULL` to fill the bars using the default palette in `familiar`. Other palettes are supported by the `paletteer` package, `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.
`limit_n_features`	(optional) The number of features that should be included in the plot. Only the most important features are shown. By default, the number of features is not limited.
`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.
`significance_level_shown`	Position(s) to draw vertical lines indicating a significance level, e.g. 0.05. Can be NULL to not draw anything.
`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⁠`.
`verbose`	Flag to indicate whether feedback should be provided for the plotting.
`export_collection`	(optional) Exports the collection if TRUE.
`...`	Arguments passed on to `as_familiar_collection`, `ggplot2::ggsave`, `extract_univariate_analysis` `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. `data` A `dataObject` object, `data.table` or `data.frame` that constitutes the data that are assessed. `cl` Cluster created using the `parallel` package. This cluster is then used to speed up computation through parallellisation. `feature_similarity_metric` Metric to determine pairwise similarity between features. Similarity is computed in the same manner as for clustering, and `feature_similarity_metric` therefore has the same options as `cluster_similarity_metric`: `mcfadden_r2`, `cox_snell_r2`, `nagelkerke_r2`, `spearman`, `kendall` and `pearson`. If not provided explicitly, this parameter is read from settings used at creation of the underlying `familiarModel` objects. `icc_type` String indicating the type of intraclass correlation coefficient (`1`, `2` or `3`) that should be used to compute robustness for features in repeated measurements during the evaluation of univariate importance. These types correspond to the types in Shrout and Fleiss (1979). If not provided explicitly, this parameter is read from settings used at creation of the underlying `familiarModel` objects. `message_indent` Number of indentation steps for messages shown during computation and extraction of various data elements.

Details

This function generates a horizontal barplot with the length of the bars corresponding to the 10-logarithm of the (multiple-testing corrected) p-value.

Features are assessed univariately using one-sample location t-tests after fitting a suitable regression model. The fitted model coefficient and the covariance matrix are then used to compute a p-value.

The following splitting variables are available for split_by, color_by and facet_by:

vimp_method: variable importance methods
learner: learners
data_set: data sets

Unlike for plots of feature ranking in initial variable importance computation and after modelling (as assessed by model-specific routines), clusters of features are now found during creation of underlying familiarData objects, instead of through consensus clustering. Hence, clustering results may differ due to differences in the underlying datasets.

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