Generic Plot Method for cvCovEst

Source: R/plot_functions.R

The plot method is a generic method for plotting objects of class, "cvCovEst". The method is designed as a tool for diagnostic and exploratory analysis purposes when selecting a covariance matrix estimator using cvCovEst.

# S3 method for cvCovEst
plot(
  x,
  dat_orig,
  estimator = NULL,
  plot_type = c("summary"),
  stat = c("min"),
  k = NULL,
  leading = TRUE,
  abs_v = TRUE,
  switch_vars = FALSE,
  min_max = FALSE,
  ...
)

Arguments

x

An object of class, "cvCovEst". Specifically, this is the standard output of the function cvCovEst.

dat_orig

The numeric data.frame, matrix, or similar object originally passed to cvCovEst.

estimator

A character vector specifying one or more classes of estimators to compare. If NULL, the class of estimator associated with optimal cvCovEst selection is used.

plot_type

A character vector specifying one of four choices of diagnostic plots. Default is "summary". See Details for more about each plotting choice.

stat

A character vector of one or more summary statistics to use when comparing estimators. Default is "min" for minimum cross-validated risk. See Details for more options.

k

A integer indicating the number of leading/trailing eigenvalues to plot. If NULL, will default to the number of columns in dat_orig.

leading

A logical indicating if the leading eigenvalues should be used. Default is TRUE. If FALSE, the trailing eigenvalues are used instead.

abs_v

A logical determining if the absolute value of the matrix entries should be used for plotting the matrix heat map. Default is TRUE.

switch_vars

A logical. If TRUE, the hyperparameters used for the x-axis and factor variables are switched in the plot of the cross-validated risk. Only applies to estimators with more than one hyperparameter. Default is FALSE.

min_max

A logical. If TRUE, only the minimum and maximum values of the factor hyperparameter will be used. Only applies to estimators with more than one hyperparameter. Default is FALSE.

...

Additional arguments passed to the plot method. These are not explicitly used and should be ignored by the user.

Value

A plot object

Details

This plot method is designed to aide users in understanding the estimation procedure carried out in cvCovEst(). There are currently four different values for plot_type that can be called:

  • "eigen" - Plots the eigenvalues associated with the specified estimator and stat arguments in decreasing order.

  • "risk" - Plots the cross-validated risk of the specified estimator as a function of the hyperparameter values passed to cvCovEst(). This type of plot is only compatible with estimators which take hyperparameters as arguments.

  • "heatmap" - Plots a covariance heat map associated with the specified estimator and stat arguments. Multiple estimators and performance stats may be specified to produce grids of heat maps.

  • "summary" - Specifying this plot type will run all of the above plots for the best performing estimator selected by cvCovEst(). These plots are then combined into a single panel along with a table containing the best performing estimator within each class. If the optimal estimator selected by cvCovEst() does not have hyperparameters, then the risk plot is replaced with a table displaying the minimum, first quartile, median, third quartile, and maximum of the cross-validated risk associated with each class of estimator.

The stat argument accepts five values. They each correspond to a summary statistic of the cross-validated risk distribution within a class of estimator. Possible values are:

  • "min" - minimum

  • "Q1" - first quartile

  • "median" - median

  • "Q3" - third quartile

  • "max" - maximum

Examples

cv_dat <- cvCovEst(
  dat = mtcars,
  estimators = c(
    thresholdingEst, sampleCovEst
  ),
  estimator_params = list(
    thresholdingEst = list(gamma = seq(0.1, 0.9, 0.1))
  )
)

plot(x = cv_dat, dat_orig = mtcars)