niceScatter: draw a scatter plot
In ZachHunter/NicePlots.R: Nice Plots for Data Exploration

niceScatter

R Documentation

draw a scatter plot

Description

Draws a 2D or 3D scatter plot with optional regression lines.

Usage

niceScatter(
  x,
  by = NULL,
  color = NULL,
  shape = NULL,
  size = NULL,
  trendline = FALSE,
  sizeScale = 2,
  sizeLevels = 5,
  groupLabels = NULL,
  subgroup = FALSE,
  bandwidth = NULL,
  useRgl = FALSE,
  type = "p",
  theme = basicTheme,
  main = NULL,
  sub = NULL,
  ylab = NULL,
  xlab = NULL,
  zlab = NULL,
  minorTick = FALSE,
  guides = NULL,
  plotColors = NULL,
  logScale = FALSE,
  axisText = c(NULL, NULL),
  rotateLabels = FALSE,
  add = FALSE,
  minorGuides = FALSE,
  extendTicks = TRUE,
  expLabels = FALSE,
  lWidth = NULL,
  na.rm = TRUE,
  verbose = FALSE,
  logAdjustment = 1,
  xLim = NULL,
  yLim = NULL,
  zLim = NULL,
  strictLimits = FALSE,
  legend = FALSE,
  trimTrendLines = TRUE,
  showTrendConfidence = TRUE,
  drawPoints = TRUE,
  corMethod = "pearson",
  ...
)

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.
`color`	factor or logical; if by is NULL, a factor suppolied to this option will populate by to color points by the factor levels. If by is defined then color should be set to TRUE or FALSE.
`shape`	factor or logical; if by is NULL, a factor suppolied to this option will populate by to control the shape of the points points by the factor levels. If by is defined then shape should be set to TRUE or FALSE.
`size`	factor or logical; if by is NULL, a factor suppolied to this option will populate by to control the size of the points by the factor levels. If by is defined then color should be set to TRUE or FALSE.
`trendline`	To do.
`sizeScale`	numeric; How much larger should points be scaled based on factor level than the default.
`sizeLevels`	How many levels should be used to make the size scaling effect if the value given to size is numeric.
`groupLabels`	character vector; overrides the factor levels of `by` to label the groups
`subgroup`	logical; use additional column in `by` to group the data within each level of the major factor.
`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.
`useRgl`	logical; Should the library `rgl` be used to make 3D surface plots.
`type`	character;
`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.
`zlab`	character; z-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; manually set the limits of the plotting area (eg. `xLim=c(min,max)`). Used to format the x-axis. by default but will modify the x-axis if `side=TRUE`.
`yLim`	numeric vector; manually set the limits of the plotting area (eg. `yLim=c(min,max)`). Used to format the y-axis.
`zLim`	numeric; optional limits on the z-axis for 3D plotting.
`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.
`trimTrendLines`	logical; Limits trend line to the min and max data points if set to `TRUE`.
`showTrendConfidence`	logical; Shows the 95% CI of the model tend line if set to `TRUE`.
`drawPoints`	logical; Should the points be drawn. Defaults to `TRUE`. Only useful for drawing an empty graph or only the trend lines.
`corMethod`	character; This should be a valid argument to `method` from `cor.test`. Calculated only when trendlines are requested, the values be seen using `verbose` and in the `stats` section of the output list.
`...`	additional options for S3 method variants

Details

The niceScatter function operates a little differently from the rest of the functions in this package. While it can accept a data.frame or a vector for x and by values, it is also possible to construct the by data.frame implicitly by supplying an actual factor/numeric vector to to the options like color, shape, and size instead of TRUE or FALSE. These approaches can not be mixed and matched. If a value is given to by directly then the other active options are just set to TRUE. If a numeric vector or single column data.frame is given to x, the x-axis is automatically assigned to the row numbers of the data. The standard options for type in the base R plot function can be given here to determine the plotting method. If three or more columns of data are supplied to x, niceScatter will switch to 3D plotting mode with scatterplot3d. The options color, size and shape can be used in this mode. The scatterplot3d options grid, angle and box can be given as arguments to be passed to scatterplot3d. If useRgl is TRUE, then it will attempt to load the rgl package and use rgl interactive graphics instead. Note that the shape option does not work in with rgl plot3d. However, the size option will scale the radius of the spheres in rgl correctly. When useRgl is active, the plot3d options axes and box can be endtered as arguments to niceScatter to format the graph. Finally, in 2D mode, linear trend lines with 95% confidence intervals can be drawn for the data or for each factor level of an option such as color or shape.

Examples

data(iris)
#Construct the by data.frame implicitly by supplying values to the options
niceScatter(iris[,1:2], color=iris$Species, shape=iris$Species,
   size=iris[,3], trendline = "color",theme=npColorTheme)

#Same thing but defining the by input explicitly and making a single trend line for the group.
#Note that setting trend line to color as before would produce a exact replica of the first graph.
niceScatter(iris[,1:2],by=data.frame(iris$Species,iris$Species,iris[,3]),
   color=TRUE, shape=TRUE, size=TRUE, theme=npColorTheme, trendline = TRUE)

#Using 3D
niceScatter(iris[,1:3], color=iris$Species, size=iris[,4], shape=iris$Species, angle=140)

#3D with rgl
niceScatter(iris[,1:3], color=iris$Species, size=iris[,4], useRgl=TRUE)

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