prepCategoryWindow: prepare a plotting environment for categorical data such as...
In ZachHunter/NicePlots.R: Nice Plots for Data Exploration

prepCategoryWindow

R Documentation

prepare a plotting environment for categorical data such as bar plots or box plots

Description

takes untransformed data and draws the x and y axis with support for subgrouping data within factors, log transformation and outlier trimming.

Usage

prepCategoryWindow(
  x,
  by = NULL,
  groupLabels = levels(by),
  minorTick = FALSE,
  guides = TRUE,
  yLim = NULL,
  rotateLabels = FALSE,
  rotateY = TRUE,
  theme = NA,
  plotColors = if (is.na(theme)) {
     list(bg = "open", guides = "black", lines =
    "gray22", points = "darkgrey", fill = "white")
 } else {
     theme$plotColors
 },
  trim = FALSE,
  logScale = FALSE,
  axisText = c(NULL, NULL),
  minorGuides = FALSE,
  extendTicks = FALSE,
  subgroup = FALSE,
  expLabels = TRUE,
  sidePlot = FALSE,
  subgroupLabels = NULL,
  strictLimits = FALSE,
  legend = FALSE,
  pointHighlights = FALSE,
  logAdjustment = 1,
  stack = FALSE,
  preferMulti = TRUE,
  maxSize = FALSE,
  sizeColumn,
  ...
)

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.
`groupLabels`	character vector; overrides the factor levels of `by` to label the groups
`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`.
`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`.
`theme`	list; A `NicePlots` plotColor list from a theme.
`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.
`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.
`logScale`	positive numeric; the base for the for log scale data transformation calculated as `log(x+1,logScale)`.
`axisText`	character; a length two character vector containing text to be prepended or appended to the major tick labels, respectively.
`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.
`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.
`subgroupLabels`	character vector; sets the labels used for the `subgroup` factor. Defaults to the levels of the factor.
`strictLimits`	logical; eliminates padding on the value axis so 0 can be flush with the x-axis. Defaults to `FALSE`.
`legend`	logical/character; Draw a legend in the plot margins. If a character string is given it will overide the factor name default for the legend title.
`pointHighlights`	logical; Is pointHightlights turned on? This is used to determin with column of `by` should be used for legend factor levels.
`logAdjustment`	= numeric; This number is added to the input data prior to log transformation. Default value is 1.
`stack`	logical; Used for stack stacked bar plots. Used exclusively by `niceBar`.
`preferMulti`	logical; Are multiple legends preferred
`maxSize`	numeric; This is largest size scaling value for size scale legends. Defaults to `FALSE`
`sizeColumn`	numeric; This indicates which column should be used for the size scaling.
`...`	additional options mostly to be passed along to subsequent functions

Details

This function does all the hard work of setting up the x and y axis for plotting as well as optionally log transforming and/or trimming the data of outliers. In particular, it adds much more robust support for plotting of log transformed data and subgrouping of primary vectors. Other features include the addition of both major and minor guidelines, support for horizontal plotting and improved label formatting options.

Value

formats the plotting area and returns a named list with 'data' and 'labels' corresponding to the trimmed and/or transformed data and the labels for the primary factors, respectively.