# Some demos of a function presented in
# Kozak, M. (2010) 'dotplots.errors, a new R function to ease the pain of creating dotplots',
# Communications in Biometry and Crop Science, 5 (2), 69-77.

source("http://agrobiol.sggw.waw.pl/~cbcs/articles/5_2_2/function_www.R")

# Example Bhargava et al. (2008), Communications in Biometry and Crop Science 3 (1), 3-15

genotype <- paste("CA", as.roman(1:13), sep = "-")
SE <- c(0.46, 2.11, 1.70, 0.91, 1.35, 0.58, 0.61, 0.70, 0.73, 0.40, 0.51, 0.28, 0.28) 
plant.height <- c(15.38, 16.94, 17.83, 12.06, 15.41,  13.52, 14.31, 14.69, 12.45, 13.31, 8.53, 14.89, 15.25)
lower <- plant.height - SE; upper <- plant.height + SE
x <- data.frame(group = genotype, lower = lower, est = plant.height, upper = upper)

dotplot.errors(x, qlabel = "Mean plant height (cm) ")

# Affecting plotting symbol, size and color, and bars’ color can be done by calling to the simplyTheme() function.
# Here, plotting symbol (pch = 19 is closed circle), its size (cex = 2 means two times bigger plotting symbols than the default), and color

myTheme <- simpleTheme(pch = 19, cex = 2, col = "red") 
myscales <- list(cex = 1.5) # this will be used to increase the font size of the x-axis label
dotplot.errors(x, qlabel = "Mean plant height (cm) ", myTheme = myTheme, label.define = myscales, bar.color = "red")

# Alternatively, the same can be done within the call to dotplot.errors():

dotplot.errors(x, qlabel = "Mean plant height (cm) ", myTheme = simpleTheme(pch = 19, cex = 2, col = "red"), label.define = list(cex = 1.5), bar.color = "red")

# Note that thanks to the default reorder.groups = TRUE, the groups were reordered by estimate, from highest to smallest. We can reorder from smallest to highest, and let us add a reference line representing the overall mean (14.20, according to Bhargava et al. 2008):

dotplot.errors(x, qlabel = "Mean plant height (cm) ", myTheme = myTheme, label.define = myscales, bar.color = "red", reordering = "increasing", reference = 14.20)

# Let's make the arrows better visible, and add some text:
dotplot.errors(x, myTheme = simpleTheme(pch = 19, cex = 1.5, col = 1), qlabel = "Mean plant height (cm) ", add.text = " (over three environments)", end.length = .125)

# Encapsulated postscript can be produced like this (the graph will need to be assigned to an object):
myTheme <- simpleTheme(pch = 19, cex = .5, col = 1)
myplot <- dotplot.errors(x, qlabel = "Mean plant height (cm) ", myTheme = myTheme, label.define = list(cex = .7), scales = list(cex = .6), aspect = 1.5, end.length = .03, reference = 14.20)
trellis.device("postscript", file = "my_file.eps", width = 3, height = 4, paper = "special", horizontal = F)
print(myplot)
dev.off()

# Less preferred, but most often used a vertical version of the dot plot:

dotplot.errors(x, qlabel = "Mean plant height (cm) ", aspect = .5, horizontal = F)

# The aspect ratio of the graph needed to be changed to deal with the genotype names on the horizontal axis.
# And here, alphabetical ordering:

dotplot.errors(x, qlabel = "Mean plant height (cm) ", aspect = .5, reorder.groups = F, horizontal = F)

# In all above plots the groups were reordered by estimate. Now alphabetical ordering for nominal factors:

dotplot.errors(x, qlabel = "Mean plant height (cm) ", reorder.groups = F)

#Should one want to use some particular ordering, the x$group factor needs to be made an ordered factor, as here:
xx <- x
xx$group = ordered(xx$group, levels = levels(xx$group)[c(10, 1:9, 11:13)])
dotplot.errors(xx, qlabel = "Mean plant height (cm) ", reorder.groups = F)

# You can use as many reference lines as you wish (see how the arguments are abbreviated):

dotplot.errors(x, q = "Mean plant height (cm) ", ref = c(12, 14.20))
dotplot.errors(x, q = "Mean plant height (cm) ", ref = 8:19)

# These are regular lattice objects:

str(myplot)
myplot$aspect.ratio <- 1.75
myplot$x.limits <- c(0, 20)
print(myplot)

# Regular lattice plots can be updated, and so - to some extent - can be these plots:
myplot2<- update(myplot, cex = 1.25)
print(myplot2)

# Adding a label to the qualitative axis is done through ylab (or xlab for the vertical dotplot) argument passed to stripplot():

dotplot.errors(x, qlabel = "Mean plant height (cm) ", ylab = expression(italic(C.~ ~album) ~ ~ " genotype"))
dotplot.errors(x, qlabel = "Mean plant height (cm) ", xlab = expression(italic(C.~ ~album) ~ ~ " genotype"), horiz = F)

# If you need to alter the quantitative label, you can dop it by altering object:

myplot3 <- dotplot.errors(x)
myplot3$ylab <- expression("Mean plant height (cm) " %+-% " standard error")
print(myplot3)

# Or

myplot3$ylab <- list(expression("Mean plant height (cm) " %+-% " standard error"), cex = .6)
print(myplot3)