bvt_graphic_options: Plotting Options In BVT

In ZachHunter/bvt: Visualization Tools for Bioconductor

Plotting Options In BVT

Description

Documenting plotting options that are universally available to BVT functions but not otherwise documented

Details

We can break these options into basic categories as there are a lot of them. This will cover Plot Enviroment with includes legend, axis, and title formatting; Plot Formatting which includes how points are rendered, determines what error bar measure, etc; Style Formatting which controls color, line types, background, etc., and finally Advanced Settings. Much of this can be set interactively using the shiny interface and you can see the resulting code in the advanced tab. Another general note is that all theme options can be passed as function arguments to override theme defaults. Finally, while we will mention again in the Advanced Settings section, use RSOverride=TRUE to stop bvt functions from resetting the graphic environment every time, wiping out the plot history. This is particularly important when using layouts for multiple plots or in markdown scripts. This is due to a known bug in RStudio where graphics devices don't always update properly. It is turned on by default when using RStudio. Note that the graphics issuse will reset and appear in the proper fashion after resizing the plotting environment manually.

Plot Enviroment

This section covers options that format axes, labels, titles, etc.

main

Sets the title of the plot, overriding defaults.

subtitle

Sets the subtitle for the plot. This slot is empty by default and used by the showCalc option if left blank

ylab

Sets the y-axis title. Note xlab and zlab can be used to set titles for the x and z axes where applicable.

yLim

Sets the lower bounds and upper bounds, respectively, on the y-axis using a length two numeric vector. Note that xLim and zLim can also be used where applicable.

logScale

Transforms the data into log scale based on the number assigned. In order to stabilize low values, a small number, typically 1, is added to all data points be default when active. Set to false to disable. Note that data labels represent the values prior to transformation but scale is still in log. In scatter plots and 2 dimensional density plots (i.e. contour plots), a numeric vector can be supplied giving log base values (or FALSE for non-log) for the x, y, and z axis, respectively

expLabels

If logScale is active, data labels are written as powers of the logarithm base supplied when set to TRUE.

logAdjustment

The number added to each data point prior to log transformation. Default is 1. Can be set to 0.

axisText

Length two character vector that adds set text before and/or after the axis labels. eg. c("","%") for percentages. For plots with multiple data axis, these can be set individually by providing a list of the form list(x=c("d","CT"),y=c("","%")).

groupLabels

Replaces the group factor level names with the strings supplied in the character vector on the categorical axis.

subgroupLabels

Replaces the subgroup factor level names with the strings supplied in the character vector on the categorical axis. This will update the legend levels when appropriate.

highlightLabels

Replaces the highlight factor level names with the strings supplied in the character. This will updated the legend levels.

sidePlot

When set to TRUE, rotates the entire plot 90 degrees clockwise.

rotateY

Rotates the data axis labels 90 degrees when set to TRUE.

rotateGroupLabels

Rotates the group labels by 90 degrees.

titleSize

Cex like scale factor that controls the size of the plot title set with main.

groupLabSize

Cex like scale factor that controls the size of the categorical axis group labels that cane be set with groupLabels.

subgroupLabSize

Cex like scale factor that controls the size fo the subgroup labels on the categorical axis. These labels can be set with subgroupLabels.

subSize

Cex like scale factor controlling the size of the plot subtitle. Subtitles can be set with subtitle.

axisLabelSize

Cex like scale factor controling the size of the axis titles in the plot. These can be set with

yAxisLabSize

Cex like scale factor that controls the size of the numeric data labels.

legendSize

Cex like scale factor that controls the size of the legend when applicable.

groupLabelSpacing

Controls the distance of the categorical axis group labels from the axis.

subgroupLabelSpacing

Controls the distance of the categorical axis subgroup labels from the axis.

legendSpacing

Controls the distance between line items in the legend.

minorTick

Sets the number of ticks marks used between major axis ticks. Can be set to 0 or FALSE to disable.

extendTicks

Determines if the minor ticks should be confined between the first and last major tick marks (default for R). Defaults to TRUE which extends ticks to end of the axis.

Plot Formatting

This section are options that impact the actual plotting area rather than the axes, labels, titles, etc.

guides

Determines if guide lines should be drawn on the plot area to indicate the major ticks on the data axis.

minorGuides

Determines if minor guide lines are drawn to indicate minor ticks on the data axis. The number of minor ticks can be set using minorTick. This can be useful when logScale is active.

drawPoints

Determines if a data point overlay is drawn. Contours, boxes, violins, error bars, etc. will still be displayed. For box plots, outlier data points (based on IQR distance from the innerquartile boundaries and set using the outliers parameter) are still drawn as per convention. Setting outliers=0 will cause the whiskers to extend to the full range, eliminating the need for outlier plotting if that is desired.

pointMethod

Determines how the data point overlay is drawn. The options are: "linear" where all points drawn at the same position on the categorical axis; "jitter", where points are randomly assigned a categorical axis value within an interval; "distribution" where points are placed in order from highest to lowest on the categorical axis interval; and "beeswarm" where points are positioned to not overlap but pack together as close as possible. The width of the categorical axis interval where these methods can plot is determined by pointLaneWidth. The precise position of these points on the graph can be obtained in a npData object at npData$options$xypos.

swarmOverflow

If pointMethod is set to "beeswarm" and the points are unable to fit within the the region on the categorical axis determined by pointLaneWidth, this overflow can be an handled in different ways: "none" this ignores the pointLaneWidth setting and plots out the full swarm without restriction. Note that this can cause swarms from different factor levels to overlap; "gutter" causes the overflow points to be plotted along the outer edge of the allowed interval; "wrap" causes the swarm to just start over plotting the overflow points in a new swarm on top of the existing one; "random" causes overflow points to be randomly scatter on the categorical axis, and "omit" which causes the overflow points to be not be drawn.

aggFun

This options is used by dot and bar plots to determine the aggregate function used, i.e. either "mean" or "median". This will be represented as the central band or bar height, respectively.

errFun

This determines the method used for drawing error bars or confidence intervals in dot and bar plots. The options are: "se" this is the standard error of the mean and is the default setting; "sd" standard deviation; "range" gives the minimum and maximum values. Note that unlike box plots, this is not impacted by the outliers setting; "t95ci" returns the 95% confidence interval based on the t-distribution; and "boot95ci" which calculates empirical 95% confidence intervals of the aggregate function determined by the aggFun setting. This uses resampling with replacement and can take some time with larger data sets. The number of bootstraps used is set with curvePoints though this is likely to be changed in a future update. Note that "t95ci", "se", and "sd" only make sense with aggFun="mean". Also, "sd" and "se" have a default multiple of 2x but can be altered using errorMultiple.

errorMultiple

The number of standard deviations (sd) or standard errors of the mean (se) to be drawn. Default is 2.

errorBars

Controls if error bars are drawn for dot and bar plots. Note that mean/median bands and bars, respectively, will still be drawn.

barType

Used only for dot plots, this option controls how the central mean/median point is indicated per factor levels: "bar" this is the default. Bar width is controls by width, and thickness by lWidth; "dot", draws a ball where the size is determined by lWidth; "none" the mean/median point is not drawn on the graph.

drawBox

Determines if the boxes are drawn for box and violin plots. Defaults to TRUE. Note that the median bar and the violin will still be drawn for box plots and violin plots, respectively.

trimViolins

Controls if the violins in violin plots are truncated at the last data point or allowed to taper off.

trimCurves

Determines if single variable density plot curves are truncated at the extreme data points or allowed to taper off. Default value is TRUE, trimming the curves.

trimTrendLines

Determines if trend lines in geneScatter stop at the extreme data points or continue to the edge of the graph.

showTrendConfidence

Determines if trend line confidence intervals are drawn in geneScatter plots.

sizeScale

Cex like scale that determines the maximum difference in point size when size is active in geneScatter. Note that the minimum point size is controlled by the pointSize setting.

sizeLevels

When size is given a continuous variable in geneScatter this value determines the number of factor levels shown in the figure legend.

drawRug

Draws a rug plot indicating values underneath the density curve of density plots if set to TRUE.

nlevels

Determines the number of contour levels drawn in 2D density plots.

Style Formatting

This section contains the graphic formatting options that are primarily stylistic. Many of these options are also theme settings. Any theme setting can be overridden by providing the value as an argument to a bvt function. Themes are named lists of settings that allow for different values for different plot types by appending a either "BP", "VP", "DP", "Bar" or "2D" to the setting to indicate box plots, violin plots, dot plots, bar plots, or scatter plots (including 2D density/contour plots), respectively. Using these codes are unnecessary for setting options on the fly. For example providing width=1.25 to a violin plot, will automatically override the theme value for widthVP in the current theme. You can find the valid npThemes available in your environment using npThemes or create a new theme based off of an existing template with newNPTheme. Colors in bvt are controlled by the plotColors list object. You can read more about how to set colors by following the link: plotColors. For the many of the settings below, if only one value is given, then all factor levels, lines, points, etc. will have that same value. If more than one is given, the value will be assigned based on a plotting factor in order of priority: highlight, subgroup, and group. Factor level assignments are based on position in the vector, so a factor with 5 levels should be associated with either a length 1 or >= length 5 vector. Note that values are allowed to repeat and while colors will often automatically loop back to the begining of the vector if it runs out of values the settings below will typically not plot past that factor level. By passing a vector containing some NA values will cause selective drop out at those positions of the line, point, fill, etc. just for that factor level.

width

Controls the maximum width of boxes, bars, vioins, etc.

pointLaneWidth

Controls the width on the categorical axis were data points can be drawn for each factor level.

vioBoxWidth

Determines the width of the inner box plot for violin plots.

fontFamily

While future updates may support the selection of custom fonts, right now, bvt supports font family selection which includes the options "serif", "sans", and "mono".

pointSize

Cex scale to control the size of data points. This also sets the base point size when size scaling is active in scatter plots.

pointShape

A numeric vector used to select the shape of points corresponding to base R's pch setting. For geneScatter shape scales are directly associated with a factor using the shape option.

lWidth

Cex like factor controls the line width for plot features similar to lwd.

errorCapType

Controls how the end of the whiskers of box plots and the tops of the error bars of dot and bar plots are drawn. Valid options are "ball", "bar" or "none". Size or width of this cap is determined by errorBarCapWidth.

errorBarCapWidth

Controls the size of the cap for error bars and whiskers. Setting the value to 1 will cause a bar to be the same width as the corresponding box or bar.

errorBarLineType

Controls the R line type (lty) used to draw error bars and whiskers.

vioBoxWidth

Controls the relative width of the box plot found at the center of violin plots.

plotColors

A named list of color settings used in bvt. Information on how to use this list to make custom graphs can be found in the following link: plotColors.

Advanced Settings

These options are a bit more technical or at least don't fit cleanly in to one of the above categories.

outliers

This option controls how many inner quartile ranges (IQR) from the edge of the inner quartile a data point can be before being considered an outlier. The default value the standard 1.5 times the IQR. This principally impacts the whisker length on box plots and can be set to 0 to automatically have the whiskers extend to the full range. Note that outlier points are plotted normally regardless.

useRgl

Determines if 3D scatter plots and 2D density surface plots are rendered interactively using the RGL library. While only listed as suggested for the package, its can be a helpful way to visualize the data.

RSOverride

There is a known bug in RStudio that causes plot environment not to updated properly. This make plots appear to overlap until manually resized, forcing a refresh. To get around this, bvt will reset the plotting environment with every new graph when running on RStudio though this results in the loss of plot history. To disable this functionality, set RSOverride=TRUE. This is particularly important when constructing multi-panel figures and in rmarkdown files.

bandwidth

This controls the bandwidth setting for kernel density estimation used in violin plots and density plots.

curvePoints

This controls the number of line segments used to draw curves in bvt. It also controls the number of bootstraps iterations run with using the "boot95ci" option with errFun though this is likely to change in future updates.

calcType

Statistical testing based on the group factor levels are automatically calculated in genePlot and isoPlot. The options are: "ttest" performs a pairwise t-test with Holm–Bonferroni correction; "wilcox" performs a pairwise Wilcoxon rank sum test with Holm–Bonferroni correction; "anova" performs an analysis of variance test; "Tukey-HSD" performs the Tukey range test or honestly significant difference test; "none" disables statistical testing. Note that subgroup and highlight factor levels are ignored. The summery results can be reported automatically by setting verbose=TRUE or by looking at the stats section of an npData object returned by genePlot or isoPlot, i.e. npData$stats.

chowCalc

If set to TRUE and subtitle is NULL, the p-value from ANOVA or t-test/wilcoxon comparisons of two groups will be displayed below the graph.

corMethod

This is used by geneScatter to calculate correlation statistics for trend lines if present. The options are passed to cor.test and can be set to "pearson", "kendall", or "spearman". Full linear model and correlation data can be found in the returned npData object at npData$stats.

verbose

Causes statical testing results and descriptive statistics to print as output when set to TRUE.

See Also

plotColors, genePlot, isoPlot, geneScatter

ZachHunter/bvt documentation built on Sept. 18, 2024, 3:12 p.m.