addNicePoints: Add a datapoint overlay to a box or violin plot
In ZachHunter/NicePlots.R: Nice Plots for Data Exploration

addNicePoints

R Documentation

Add a datapoint overlay to a box or violin plot

Description

This function prepares data based on settings from niceBox, niceDots, or niceVio and passes the data on to drawPoints.

Usage

addNicePoints(
  prepedData,
  by,
  filter = TRUE,
  sidePlot = F,
  subgroup = F,
  plotAt,
  pointHighlights = F,
  pointMethod = "jitter",
  pointShape = 16,
  pointSize = 1,
  width = 1,
  pointLaneWidth = 0.9,
  plotColors = formatPlotColors(list(1)),
  drawPoints = T,
  outliers = F,
  dataCols = 1,
  swarmOverflow = "random",
  calcOnly = FALSE
)

Arguments

`prepedData`	list; a list object returned by `prepCategoryWindow`
`by`	factor or dataframe of factors; One or more factors that control how the data is grouped. The first column is the primary grouping factor and the second and thrid columns are used for sub-grouping and highlighting as needed.
`filter`	logical vector; Used to further filter the data if necissary.
`sidePlot`	logical; switches the axis to plot horizontally instead of vertically.
`subgroup`	logical; Should the data be faceted into subgroups within the primary factor levels. Ignored if `by` is a `factor`.
`plotAt`	numeric; A vector of where to draw each set of points
`pointHighlights`	logical; will use additional factors in `by` to highlight points in the dot plot.
`pointMethod`	character; method to be used for ploting dots. Can be set to "jitter", "linear", "beeswarm" or "distribution".
`pointShape`	positive integer; sets pty for plotting data points. Can be a vector to support additional graphical customization.
`pointSize`	positive integer; sets the cex multiplier for point size.
`width`	numeric; A multiplier that controls how wide the ploting elements will be. Setting `width=1.1` would result in plot elements being 10% wider.
`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'.
`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.
`drawPoints`	logical; draws a dot plot overlay of the data for each box. Setting this to false causes just the outlier points to be ploted. Used in `niceBox`.
`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.
`dataCols`	numeric; A number of representing the number of data columns to be plotted. These is a combination of the dimentions of `prepedData` and/or the number of primary and secondary grouping factors. Used to determine the maximum ploting width for the points.
`swarmOverflow`	character; How to handle beeswarms that would normally overflow the `pointLaneWidth` argument. Valid options are "random", "gutter", "wrap", "omit", and "none".
`calcOnly`	logical; Will return just xy plotting data but will plot nothing if set to `TRUE`. Setting drawPoints to false will still plot outlier data.

Details

This function takes in cleaned data from prepCategoryWindow and reorganizes to to create a dot plot overlay for a graph. This code is used by both niceBox and niceVio and has been moved to an independent function to make the code more compact and easier to maintain. This code is also used to draw the outlier dots in a boxplot by setting drawPoints = FALSE.

Examples

#Add a beeswarm plot overlay to a boxplot in the iris data set:
data(iris)
data<-list(data=iris$Sepal.Length)
boxplot(iris$Sepal.Length~iris$Species)
addNicePoints(data,by=iris$Species,pointMethod="beeswarm",plotAt=1:3)

#Add an outlier point to a boxplot:
boxplot(iris$Sepal.Length~iris$Species, outline=FALSE)
addNicePoints(data,by=iris$Species,pointMethod="linear",plotAt=1:3,
    drawPoints=FALSE,outliers=1.5)

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