heatmap_lipidome_from_limma {lipidomeR}

Create 'lipidomeR' heatmaps of model statistics

Description

Use this function to creating heatmaps of model statistics from the output of the compute_models_with_limma function or related functions (compute_F_test_with_limma and compute_post_hoc_test_with_limma).

Usage

heatmap_lipidome_from_limma(
  x,
  names.mapping = NULL,
  axis.x.carbons = TRUE,
  baseline.adjusted = FALSE,
  class.facet = "row",
  class.subset = NULL,
  F.test = FALSE,
  omit.class = NULL,
  omit.factor = NULL,
  order.factor = FALSE,
  p.val.thresholds = c(0.01, 0.05, 0.1),
  p.val.labels = c(8, 4, 3),
  p.val.label.bg.size = 2,
  p.val.label.size = 1,
  p.adj.method = "BH",
  plot.individual = FALSE,
  plot.all = TRUE,
  print.figure = TRUE,
  print.formula = TRUE,
  formula.width = 110,
  legend.key.size.multiplier = 2,
  range.min.N.carbons = 5,
  range.min.N.double.bonds = 5,
  scales = "fixed",
  shadowtext = FALSE,
  space = "free",
  survival = FALSE,
  verbose = FALSE,
  wrap.contrast.name = TRUE
)

Arguments

x

(Required) list of output from the compute_models_with_limma function or related functions.

names.mapping

(Optional) mapping of lipid names from the map_lipid_names function.

axis.x.carbons

(Optional) TRUE or FALSE: Should the lipid size (i.e., number of carbon atoms in the fatty acid chain) be presented on the x-axis or y-axis?

baseline.adjusted

TRUE or FALSE: Is the model object that is specified as argument x a baseline-adjusted regression model? (Note: this model type is not yet provided in the package.)

class.facet

(Optional) character string with possible values 'col', 'row' or 'wrap': Present lipid classes as panels organized into columns, rows or into a wrapped layout spanning over multiple rows and columns. The alternative 'wrap' is only available with plot.infividual = TRUE.

class.subset

(Optional) character vector specifying a subset of the lipid classes (e.g., c( 'PC', 'SM', 'TG' )). Same outcome can be achieved with the argument omit.class.

F.test

(Optional) TRUE or FALSE: Should the result of an F-test be visualized instead of individual model coefficients? Result from the function compute_F_test_with_limma needs to be provided as argument x for the heatmap_lipidome_from_limma function along with the argument F.test = TRUE.

omit.class

(Optional) character vector of lipid classes omitted from the visualization (e.g., c( 'PC', 'SM', 'TG' )).

omit.factor

(Optional) character vector of lipid classes omitted from the visualization (e.g., c( 'Time' )).

order.factor

(Optional) TRUE or FALSE: Sort the factor panels alphabetically?

p.val.thresholds

(Optional) numeric vector with increasing values of highlighting thresholds for multiple-testing-corrected p-values. For instance, c( 0.01, 0.05, 0.1 ) gives distinct highlighting of associations in the ranges p < 0.01, 0.01 \geq p < 0.05, and 0.05 \geq p < 0.1. If the number of these categories is changed from the default value, also the argument p.val.labels needs to be modified to match it.

p.val.labels

(Optional) numeric vector of point characters for the p-value highlighting categories specified in the argument p.val.thresholds. The values need to be compatible with the function scale_shape_manual. If the number of these labels is changed from the default value, also the argument p.val.thresholds needs to be modified to match it.

p.val.label.bg.size

(Optional) numeric value to scale the size of the colored background of the symbols that indicate values with statistical significance. The background is used to ensure that the white symbols are visible also when the color of a heatmap rectangle is of a bleak color.

p.val.label.size

(Optional) numeric value to scale the size of the symbols that indicate values with statistical significance.

p.adj.method

(Optional) name of the method to correct p-values for multiple testing. Accepted values are as in the function stats::p.adjust().

plot.individual

(Optional) TRUE or FALSE: Create specific figures for each coefficient of the model? For models with many independent variables, this may take some time to complete.

plot.all

(Optional) TRUE or FALSE: Create a combined figure of all the coefficients of the model? For models with many independent variables, this may lead to too busy a figure.

print.figure

(Optional) TRUE or FALSE: Print created figure(s) to the standard output? Note that when plot.individual = TRUE, multiple figures will be printed consecutively.

print.formula

(Optional) TRUE or FALSE: Add the model formula as a title to the figure? We recommend to use print.formula = TRUE to make the result more understandable and reproducible.

formula.width

(Optional) numeric value to specify the width of a line in the model formula. Relevant only if print.formula = TRUE.

legend.key.size.multiplier

(Optional) numeric value to scale the size of the figure (key) legends.

range.min.N.carbons

(Optional) numeric value to specify the minimum range of the axis showing the lipid size (number of carbon atoms in the fatty acid chains). This value can be increased from the default value to improve readability in situations, where there are lipid classes with little or no variation in the lipid size.

range.min.N.double.bonds

(Optional) numeric value to specify the minimum range of the axis showing the lipid saturation (number of double bonds in the fatty acid chains). This value can be increased from the default value to improve readability in situtions, where there are lipid classes with little or no variation in the lipid saturation.

scales

(Optional) character string with possible values 'fixed', 'free', 'free_x' or 'free_y'. This argument specifies, whether the axes in multiple sub-heatmaps will be in the same scale ('fixed') or in a scale specific to each sub-figure. See the function facet_grid for details.

shadowtext

(Optional) TRUE or FALSE: Should an alternative method of statistical significance highlighting be used in the figure? If TRUE, highlighting will be based on the function geom_shadowtext.

space

(Optional) character string with possible values 'fixed', 'free', 'free_x' or 'free_y'. This argument specifies, whether the sub-heatmaps will be of identical size ('fixed') or not. See the function facet_grid for details.

survival

(Optional) TRUE or FALSE: Is the model object that is specified as argument x a survival model? (Note: this model type is not yet provided in the package.)

verbose

(Optional) TRUE or FALSE: Print information about the progress of the function call?

wrap.contrast.name

(Optional) TRUE or FALSE: Wrap the name of a contrast to multiple lines to ensure readability?

Value

List of 'lipidomeR' heatmap figure(s).

See Also

compute_models_with_limma for computing the argument x for this function.