R/ggplot2.stripchart.R

In YTLogos/easyGgplot2: Perform and customize easily a plot with ggplot2

#' @include utilities.R ggplot2.customize.R
NULL
#' Easy stripchart plot with R package ggplot2
#' 
#' @param data data.frame or a numeric vector. Columns are variables and rows
#' are observations.
#' @param xName The name of column containing x variable (i.e groups). Default
#' value is NULL.
#' @param yName The name of column containing y variable. If yName=NULL, data
#' should be a numeric vector.
#' @param groupName The name of column containing group variable. This variable
#' is used to color plot according to the group.
#' @param position The position adjustment to use for overlappling points.
#' Default value is position_jitter(0.2).
#' @param addMean if TRUE, the mean point is added on the plot for each group.
#' Default value is FALSE.
#' @param meanPointShape The shape of mean point.
#' @param meanPointSize The size of mean point
#' @param meanPointColor Border color of the mean point. Default value is
#' "black".
#' @param meanPointFill Fill color of mean point. This parameter is used only
#' when meanPointShape=21 to 25. Default value is "blue"
#' @param addBoxplot If TRUE, boxplot is added on the dotplot. Default value is
#' FALSE.
#' @param boxplotFill Fill color of the boxplot. Default value is white.
#' @param boxplotColor Boxplot line color. Default value is black.
#' @param boxplotLineWeight Boxplot line weight. Default value is 0.5.
#' @param groupColors Color of groups. groupColors should have the same length
#' as groups.
#' @param brewerPalette This can be also used to indicate group colors. In this
#' case the parameter groupColors should be NULL. e.g: brewerPalette="Paired".
#' @param \dots Other arguments passed on to ggplot2.customize custom function
#' or to geom_dotplot functions from ggplot2 package.
#' @return a ggplot
#' @author Alboukadel Kassambara <alboukadel.kassambara@@gmail.com>
#' @seealso \code{\link{ggplot2.boxplot}, \link{ggplot2.violinplot},
#' \link{ggplot2.dotplot}, \link{ggplot2.density}, \link{ggplot2.histogram},
#' \link{ggplot2.customize}}
#' @references http://www.sthda.com
#' @examples
#' 
#' df <- ToothGrowth
#' ggplot2.stripchart(data=df, xName='dose',yName='len',
#'                 mainTitle="Plot of length according\n to the dose",
#'                 xtitle="Dose (mg)", ytitle="Length")
#' 
#' #Or use this
#' plot<-ggplot2.stripchart(data=df, xName='dose',yName='len')
#' plot<-ggplot2.customize(plot, mainTitle="Plot of length according\n to the dose",
#'                         xtitle="Dose (mg)", ytitle="Length")
#' print(plot)
#' @name ggplot2.stripchart
#' @rdname ggplot2.stripchart
#' @export ggplot2.stripchart
ggplot2.stripchart<-function(data, xName=NULL, yName=NULL, groupName=NULL,
                             position=position_jitter(0.2),
                             addMean=FALSE, meanPointShape=5, meanPointSize=4,
                             meanPointColor="black", meanPointFill="blue",
                             addBoxplot=FALSE, boxplotFill="white", boxplotColor="black",  boxplotLineWeight=0.5,				
                             groupColors=NULL, brewerPalette=NULL,...)
{
  
  bxpms <- .boxplot_params(...)
  
  #if yName is missing or null, data should be a numeric vector
  if(is.null(yName) & !is.numeric(data))
    stop("yName is missing or NULL. In this case data should be a numeric vector")
  #data is a numeric vector
  else if(is.numeric(data)){
    data=cbind(y=data, x=rep(1, length(data)))
    xName="x"
    yName="y"
  }
  #xName is missing or  NULL => single boxplot corresponding to the deistribution of the variable
  #bind group column to data
  if(is.null(xName)){
    data=cbind(data, x=rep(1, nrow(data)))
    xName="x"
  }
  
  #data
  data=data.frame(data)
  data[,xName]=factor(data[,xName])
  if(is.null(groupName)) p<-ggplot(data=data, aes_string(x=xName, y=yName))
  else{
    data[,groupName]=factor(data[,groupName])#transform groupName to factor
    p<-ggplot(data=data, aes_string(x=xName, y=yName, fill=groupName, shape=groupName, colour=groupName))
  }
  #add boxplot
  if(addBoxplot){    
    if(is.null(boxplotFill))	  p<-p+geom_boxplot(colour=boxplotColor,  position=position_dodge(0.8), 
                                                 size=boxplotLineWeight,  outlier.shape=NA, notch = bxpms$notch)
    else p<-p+geom_boxplot(fill=boxplotFill, colour=boxplotColor, position=position_dodge(0.8),
                           size=boxplotLineWeight, outlier.shape=NA, notch = bxpms$notch)
  }
  #stripchart
  spms <- .standard_params(...)
  if(!is.null(groupName)) p<-p+geom_jitter(position = position)
  else p<-p+geom_jitter(position = position, color = spms$color, shape = spms$shape, fill = spms$fill)
  #add Mean point
  if(addMean) p<-p+stat_summary(fun.y=mean, geom='point', shape=meanPointShape, 
                                size=meanPointSize, colour=meanPointColor, fill=meanPointFill)
  #group colors
  if(!is.null(groupColors)){
    p<-p+scale_fill_manual(values=groupColors)
    p<-p+scale_colour_manual(values=groupColors)
  } 
  else if(!is.null(brewerPalette)){
    p<-p+scale_fill_brewer(palette=brewerPalette)
    p<-p+scale_colour_brewer(palette=brewerPalette, guide="none")
  } 
  #ggplot2.customize : titles, colors, background, legend, ....
  p<-ggplot2.customize(p,...)
  p
}

#' @rdname ggplot2.stripchart
#' @export 
ggplot2.jitter<-function(...)
{
  ggplot2.stripchart(...)
}