niceDensity: draw a kernal density plot
In ZachHunter/NicePlots.R: Nice Plots for Data Exploration

niceDensity

R Documentation

draw a kernal density plot

Description

Draws a kernal density plot of one or two variables.

Usage

niceDensity(
  x,
  by = NULL,
  drawPoints = TRUE,
  groupLabels = NULL,
  subgroup = FALSE,
  bandwidth = NULL,
  drawRug = FALSE,
  useRgl = FALSE,
  plotType = c("contour", "surface"),
  theme = basicTheme,
  main = NULL,
  sub = NULL,
  ylab = NULL,
  xlab = NULL,
  minorTick = FALSE,
  guides = NULL,
  plotColors = NULL,
  logScale = FALSE,
  axisText = c(NULL, NULL),
  rotateLabels = FALSE,
  add = FALSE,
  minorGuides = NULL,
  extendTicks = TRUE,
  expLabels = FALSE,
  lWidth = NULL,
  na.rm = TRUE,
  verbose = FALSE,
  logAdjustment = 1,
  xLim = NULL,
  yLim = NULL,
  strictLimits = FALSE,
  legend = FALSE,
  trimCurves = TRUE,
  sidePlot = FALSE,
  ...
)

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.
`drawPoints`	logical; draws a dot plot overlay for contour plots
`groupLabels`	character vector; overrides the factor levels of `by` to label the groups
`subgroup`	logical; Will use the factor levels in `by` to plot a series of distributions from the data in `x`.
`bandwidth`	numeric; Manually sets the bandwith for the kernal density estimation overiding default calculations. For 2D plots `bandwidth` should be a vector of length 2. Set to `NULL` or `NA` to enable default calculations.
`drawRug`	logical; adds a `rug` plot overlay to a kernel density plot. Default is FALSE.
`useRgl`	logical; Should the library `rgl` be used to make 3D surface plots.
`plotType`	character; Can be set to `contour` or `surface` to control the type of 2D plot.
`theme`	list object; Themes are are an optional way of storing graphical preset options that are compatible with all nicePlot graphing functions.
`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.
`ylab`	character; y-axis label.
`xlab`	character; x-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`.
`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`	numeric; A length two numeric vector indicating the log scale the x and y axis, respectively. If only one value is given, it is applied to boxth axis. Set to `FALSE` to disable (Default).
`axisText`	list; A named list, "x" and "y" with two optional character values to be placed before and/or after the numeric axis label, respectively.
`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.
`add`	logical; Adds the plot to the existing window rather the generating a new plotting enviroment
`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.
`expLabels`	logical; prints the major tick labels is `logScale^{x}` instead of the raw value
`lWidth`	numeric; Line width, equivelent to the cex `lwd` option.
`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.
`logAdjustment`	numeric; This number is added to the input data prior to log transformation. Default value is 1.
`xLim`	numeric vector; lower a upper limits for the x-axis.
`yLim`	numeric vector; manually set the limits of the plotting area (eg. `yLim=c(min,max)`). Used to format the y-axis.
`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.
`trimCurves`	logical; Should the density curves be restricted to the min and max of the data.
`sidePlot`	logical; Swaps the x and y axis for ploting. Does not apply to 2D and 3D plots.
`...`	additional options for S3 method variants

Details

niceDensity is draws gernal density plots. This can be a single kernal density plot or a series of density plots overplotted on the graph based on a grouping factor from by. The subgroup option should be set to TRUE to anable this functionality. If two or more variables are passed in x in a data.frame, matrix or tibble, then the first two columns will be used to generate a scatter plot with a 2-D scatter plot with a contour plot overlay giving the 2D kernal density estimates. Setting subgroup to TRUE is this case will color the points by the first factor in by. Alternatively, for two column input, plotType can be set to "suface" to draw a 3D prepresnetation of the kernal density over the x-y plane using persp. Plotting options such as theta/phi to control rotation for persp or nlevels for contour, can be entered as arguments to niceDensity and will be passed along via do.call. Finally, if the rgl package is installed and useRgl is set to TRUE, the interactive persp3d function will be used instead. All kernal densities are calculated using the KernSmooth package. The values in npData object returned by the function are slightly different. The "summary" value gives the min and max for x and optionally y along with the density estimate fhat. The "stats" value contains a data.frame the actual x, y, and fhat paired values. The theme value curvePoints is used to determine the number of line segments per curve and can be overriden in the command line like all other theme options.

Examples

data(iris)
#Basic kernal density plot
niceDensity(iris[,1], main="Distrinbution of Sepal Length")

#Kernal density plot subgrouped by species
niceDensity(iris[,1],iris$Species, main="Sepal Length by Species",
subgroup=TRUE)

#Same thing with trimCurves=FALSE
niceDensity(iris[,1],iris$Species, main="Sepal Length by Species",
subgroup=TRUE, trimCurves=FALSE)

#2D Density of Sepal Width vs. Length
niceDensity(iris[,1:2],iris$Species, main="Sepal Width vs. Length",
subgroup=TRUE)

#Representing the 2D contour plot in 3D
niceDensity(iris[,1:2],iris$Species, main="Sepal Width vs. Length",
plotType="surface", theta=-60)

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