niceVio: draw a violin plot
In ZachHunter/NicePlots.R: Nice Plots for Data Exploration

niceVio

R Documentation

draw a violin plot

Description

draws a violin plot with optional scatter plot overlays, subgrouping options and log scale support.

Usage

niceVio(
  x,
  by = NULL,
  bandwidth = NULL,
  groupLabels = NULL,
  main = NULL,
  sub = NULL,
  ylab = NULL,
  minorTick = FALSE,
  guides = TRUE,
  theme = basicTheme,
  outliers = 1.5,
  pointSize = NULL,
  width = NULL,
  pointShape = NULL,
  plotColors = NULL,
  logScale = FALSE,
  trim = FALSE,
  pointMethod = NULL,
  axisText = c(NULL, NULL),
  showCalc = FALSE,
  calcType = "wilcox",
  drawBox = TRUE,
  yLim = NULL,
  rotateLabels = FALSE,
  rotateY = FALSE,
  add = FALSE,
  minorGuides = NULL,
  extendTicks = TRUE,
  subgroup = FALSE,
  subgroupLabels = NULL,
  expLabels = TRUE,
  sidePlot = FALSE,
  drawPoints = TRUE,
  pointHighlights = FALSE,
  highlightLabels = NULL,
  pointLaneWidth = 0.7,
  flipFacts = FALSE,
  na.rm = FALSE,
  verbose = FALSE,
  legend = FALSE,
  trimViolins = TRUE,
  logAdjustment = 1,
  ...
)

Arguments

`x`	numeric vector or data frame; The input to `prepCategoryWindow` can be a numeric vector a data frame of numeric vectors.
`by`	factor or data frame of factors; used as the primary grouping factor and the factor levels will be used as group names if `groupLabels` is not specified. If `by` is a data frame and `subgroup=TRUE`, the second column is assumed to be a secondary grouping factor, breaking out the data into sub-categories within each major group determined by the levels of the first column.
`bandwidth`	numeric; Used to override the default bandwidth calculation in `vioplot`. Default value is `NULL`.
`groupLabels`	character vector; overrides the factor levels of `by` to label the groups
`main`	character; title for the graph which is supplied to the `main` argument.
`sub`	character; subtitle for the graph which is supplied to the `sub` argument. If `NULL` and `showCalc=TRUE` it will be used to display the output form `calcStats`.
`ylab`	character; y-axis label.
`minorTick`	positive integer; number of minor tick-marks to draw between each pair of major ticks-marks.
`guides`	logical; will draw guidelines at the major tick-marks if set to `TRUE`. Color of the guidelines is determined by `plotColors$guides`.
`theme`	list object; Themes are are an optional way of storing graphical preset options that are compatible with all nicePlot graphing functions.
`outliers`	positive numeric; number of interquartile ranges (IQR) past the Q1 (25%) and Q3 (75%) cumulative distribution values. Outliers are often defined as `1.5 \times IQR` and extreme outliers are more than `3 \times IQR` away from the inner 50% data range.
`pointSize`	positive integer; sets the cex multiplier for point size.
`width`	numeric; scaling factor controlling the width of the violins.
`pointShape`	positive integer; sets pty for plotting data points. Can be a vector to support additional graphical customization.
`plotColors`	list; a named list of vectors of colors that set the color options for all NicePlot functions. Names left unspecified will be added and set to default values automatically.
`logScale`	positive numeric; the base for the for log scale data transformation calculated as `log(x+1,logScale)`.
`trim`	positive numeric; passed to `threshold` argument of `quantileTrim` if any data points are so extreme that they should be removed before plotting and downstream analysis. Set to `FALSE` to disable.
`pointMethod`	character; method to be used for ploting dots. Can be set to "jitter", "linear", "beeswarm" or "distribution".
`axisText`	character; a length two character vector containing text to be prepended or appended to the major tick labels, respectively.
`showCalc`	logical; if a p-value can be easily calculated for your data, it will be displayed using the `sub` annotation setting.
`calcType`	character; should match one of 'none', 'wilcox', 'Tukey','t.test','anova' which will determine which, if any statistical test should be performed on the data.
`drawBox`	logical; should the interquartile boxes be drawn.
`yLim`	numeric vector; manually set the limits of the plotting area (eg. `yLim=c(min,max)`). Used to format the y-axis by default but will modify the x-axis if `side=TRUE`.
`rotateLabels`	logical; sets `las=2` for the x-axis category labels. Will affect y-axis if `side=TRUE`. Note that this may not work well if long names or with subgrouped data.
`rotateY`	logical; sets `las=2` for the y-axis major tick-mark labels. Will affect x-axis if `side=TRUE`.
`add`	logical; causes plotting to be added to the existing plot rather the start a new one.
`minorGuides`	logical; draws guidelines at minor tick-marks
`extendTicks`	logical; extends minor tick-marks past the first and last major tick to the edge of the graph provided there is enough room. Works for both log-scale and regular settings.
`subgroup`	logical; use additional column in `by` to group the data within each level of the major factor.
`subgroupLabels`	character vector; sets the labels used for the `subgroup` factor. Defaults to the levels of the factor.
`expLabels`	logical; prints the major tick labels is `logScale^{x}` instead of the raw value
`sidePlot`	logical; switches the axis to plot horizontally instead of vertically.
`drawPoints`	logical; draws a dot plot overlay of the data for each box
`pointHighlights`	logical; will use additional factors in `by` to highlight points in the dot plot
`highlightLabels`	character; An optional character vector to override the factor labels associated with point highlights if active.
`pointLaneWidth`	numeric; This controls how far data point dots can move along the categorical axis when plotting. Used for `pointMethod` options 'jitter', 'beeswarm', and 'distribution'.
`flipFacts`	logical; When a dataframe of values is given, column names are used as a secondary grouping factor by default. Setting `flipFacts=TRUE` makes the column names the primary factor and `by` the secondary factor.
`na.rm`	logical; Should `NA`s be removed from the data set? Both data input and the factor input from `by` with be checked.
`verbose`	logical; Prints summary and p-value calculations to the screen. All data is silently by the function returned either way.
`legend`	logical/character; if not equal to `FALSE` with cause a legend to be drawn in the margins. If set to a character string instead of a logical value, the string will be used as the legend title insteas of the factor column name from `by`.
`trimViolins`	logical; Should the violins be truncated at the edges of the data range.
`logAdjustment`	= numeric; This number is added to the input data prior to log transformation. Default value is 1.
`...`	additional options for S3 method variants

Details

This violin plot function offers extensive log scale support, outlier detection, data point overlay options, data subsetting with a secondary factor, and data point highlighting with a tertiary factor. The complicated part of using this function is handling its many options. A wrapper function to set up and run it with preset options may be a good idea if you are using it along. The function niceDots is an example of this. Briefly put, the by argument can be a data frame of factors and the function will work through the columns in order as needed. If x is a numeric vector, then by should be a factor to group it into categories. If by is a data frame of factors and subgroup=TRUE, then the first column for by is used as the grouping factor and the second column is used as the sub-grouping factor. If pointHighlights==TRUE, and subgroup=TRUE, the the third column of by is used to highlight points data point overlay (assuming drawPoints=TRUE). If subgroup=FALSE and subgroup=TRUE, then the second column of by is used to control the point highlighting. If x itself is a data frame of numeric vectors, subgroup is automatically set to false and each column of x is plotted like a sub-group and grouped by the first column of by. Data point highlighting with pointHighlights=TRUE can still be used when x is a data frame and the highlighting factor will be drawn from the second column of by. Please note that the p-values can not always be calculated and are for general exploratory use only. More careful analysis is necessary to determine statistical significance. This function is as S3 generic and can be extended to provide class specific functionality. To further facilitate data exploration, outputs from statistical testing and data set summaries are printed to the console.

Examples

data(iris)
mCols<-makeColorMatrix()
myCols<-list(fill=c(mCols[1,3],mCols[2,3],mCols[3,3]),lines="darkblue")
Lab<-"Sepal Length"
niceVio(iris$Sepal.Length,by=iris$Species,minorTick=4,showCalc=TRUE,
    calcType="anova",ylab=Lab,main="Sepal Length by Species",plotColors=myCols)


plot(density(iris$Petal.Length))
lengthFact<-factor(iris$Petal.Length>2.82,labels=c("short","long"))


Title<-"Sepal Length by Species and Petal Length"
factorFrame<-data.frame(Species=iris$Species,PetalLength=lengthFact)
niceVio(iris$Sepal.Length, by=factorFrame, minorTick=4,subgroup=TRUE,
    ylab=Lab,main=Title,plotColors=myCols)

ZachHunter/NicePlots.R documentation built on Sept. 23, 2023, 4:04 a.m.