rm.plot: rm.plot: Raw-Means Plots for Experimental Designs
In rm.plot: Raw-Means Plots for Experimental Designs

Description Usage Arguments Details Value Author(s) References See Also Examples

View source: R/rm.plot.R

rm.plot (for raw-means-plot) is a function for visualizing results of experimental designs with up to two factors. It plots both raw data (background) and factor means (foreground) to provide a more accurate visualization of the underlying distribution.

rm.plot(d, col.offset = 2, col.x = 3, col.d = 4, noise = 0.008, na.rm = FALSE, 
	pch = 21:25, lty = 1:5, 
	bg.b.col = "darkgrey", bg.f.col = NULL, fg.b.col = "black", fg.f.col = "black", 
	type = "o", pt.cex = 1, lwd = 1, xlab = "", ylab = "", 
	ylim, max.offset = 0.2, xaxis = TRUE, x.labels, xaxt = "n", 
	plot = TRUE, legend = TRUE, 
	mar = NULL, reset.mar = TRUE, l.pos, yjust = 0.5, l.bty = "n", l.adj = c(0, 0.5), 
	...)

`d`	a `data.frame` in long format (see `reshape` or the reshape package, I recommend the latter) that contains at least three columns: one column coding the first factor (`col.offset`), one column coding the second factor (`col.x`), and one column containing the data (`col.d`). The only mandatory argument.
`col.offset`	a `numeric` or `character` scalar, specifiying either number or name of the column coding the different lines (the offset or first factor). Default is 2.
`col.x`	a `numeric` or `character` scalar, specifiying either number or name of the column coding the x-axis factor. Default is 3.
`col.d`	a `numeric` or `character` scalar, specifiying either number or name of the data column. Default is 4.
`noise`	either a `numeric` scalar or `NULL`. If `NULL`, raw data points with same value will be indistinguishable. Otherwise, uniform noise will be added to each raw data point with same value after the first one with this value. The noise (i.e., jitter) is drawn from the intervall ranging from `-noise` to `noise` (times the maximal `ylim` distance). Default is .005, that is 0.5% of `ylim`.
`na.rm`	`logical` indicating whether `NA` values should be stripped before the computation proceeds. Default is `FALSE`. Throws an error message if FALSE and NAs are encountered.
`pch`	`pch` values (plot symbols) taken for plotting the data. Note that the same values are taken for raw data and means. see `points` for more details. Recycled if too short (with warning). Default is 21:25, because those are the only values that can be displayed filled and non-filled. All other values should not be used.
`lty`	`lty` values (line types) for connecting the means. See `par` for more details. Recycled if too short (with warning). Default is 1:5.
`bg.b.col`	background border color: border color of raw data points. Default: `"darkgrey"`
`bg.f.col`	background filling color: fill color of raw data points. Default: `NULL`
`fg.b.col`	foreground border color: border color of mean data points. Default: `black`
`fg.f.col`	foreground fill color: fill color for mean data points. Default: `black`
`type`	same as type in `plot`. Default: `o` ("overplotted")
`pt.cex`	`numeric` specifying the `cex` value used for plotting the points. Default is 1.
`lwd`	`numeric` specifying the `lwd` value used for plotting the lines. Default is 1.
`xlab`	x-axis label. Default: `""`
`ylab`	y-axis label. Default: `""`
`ylim`	the y-axis limits of the plot. If not specified (the default) will be taken from data so that all raw data points are visible and a warning message is displayed specifying the ylim.
`max.offset`	`numeric`. maximal offset of factor levels from the offset factor (`col.offset`) specifying the different lines. The centre of each factor on the x-axis is at full numbers (starting from 1 to ...). The maximum will only be reached if the number of factor levels (from `col.offset`) is even. Default: 0.2.
`xaxis`	`logical` value indicating whether or not the x-axis should be generated by `rm.plot`. If `TRUE`, labels for the x-axis will be taken either from the unique values of `col.x` or can be specified with `x.labels`.
`x.labels`	`character` vector specifiying `col.x` levels. Only relevant if `xaxis=TRUE`. Then, the values given here will be displayed at the x-axis for each factor level of `col.x`.
`xaxt`	A character which specifies whether ot not the x-axis should be plotted by the call to plot function. Interfers with the aforementioned `xaxis` argument and the automatic `xaxis` function by `rm.plot`. Just there for completeness. Default `"n"` (and should not be changed).
`plot`	`logical`. Should the `rm.plot` be drawn or not. If `TRUE` (the default) plot will be drawn. If `FALSE` only the legend will be drawn (if `legend = TRUE`) See details.
`legend`	`logical` indicating whether or not `rm.plot` should automatically add a legend on the right outside the plot area indicating which line and points refer to which `col.offset` factor levels. Default is `TRUE`.
`mar`	`NULL` or `numerical` vector of length 4 indicating the margins of the plot (see `par`). If `NULL` (the default) the right margin (i.e., `par("mar")[4]`) will be (imperfectly) guessed from the `col.offset` factors for placing the legend right to the plot. If length is four this value will be taken. Ignored for `plot = FALSE`.
`reset.mar`	`logical` indicating if the margins (`mar`) shall be resetted after setting internally. Will be ignored if `legend = FALSE`. Default is `TRUE` and should not be changed (especially with `plot = FLASE`).
`l.pos`	`numeric` vector of length 2 indicating the position of the legend. If not specified automatically determined. See details.
`yjust`	how the legend is to be justified relative to the legend y location. A value of 0 means top, 0.5 means centered and 1 means bottom justified. Default is 0.5.
`l.bty`	the type of box to be drawn around the legend. The allowed values are `"o"` and `"n"` (the default).
`l.adj`	`numeric` of length 1 or 2; the string adjustment for legend text. Useful for y-adjustment when labels are plotmath expression. see `legend` and `plotmath` for more info.
`...`	further arguments which are either passed to plot or legend. The following argumenst are passed to legend, all others are passed to plot: `"fill", "border", "angle", "density", "box.lwd", "box.lty", "box.col", "pt.cex", "pt.lwd", "xjust", "x.intersp", "y.intersp", "text.width", "text.col", "merge", "trace", "plot", "ncol", "horiz", "title", "inset", "title.col", "title.adj"`

rm.plot is basically an advanced wrapper for two other functions: plot and (if legend=TRUE) legend. Furthermore, raw data is plotted with a call to points and the means with a call to lines.

You can use rm.plot to plot only a legend by setting plot = FALSE and legend = TRUE. Then, rm.plot will draw an invisible plot with xlim = c(0,10) and ylim = c(0, 10) and place the legend on this invisible plot. You can specify l.pos to position the legend, otherwise it will be plotted at c(5,5) (i.e., in the middle of the plot). Note that xpd = TRUE in the call to legend (see link{par}).

Nothing

Henrik Singmann

see http://www.psychologie.uni-freiburg.de/Members/singmann/R/rm.plot

rm.plot2 for a wrapper around rm.plot that will aggregate the data prior to plotting if there is more than one observation per cell.

add.ps can be used to compare the values at each x-axis position, by adding p-values from t-tests to the x-axis.

x <- data.frame(id = 1:150, offset = rep(c("Group A", "Group B", "Group C"),each = 50), xaxis = sample(c("A", "B", "C", "D"),150, replace = TRUE), data = c(rnorm(50, 10, 5), rnorm(50, 15,6), rnorm(50, 20, 5)))

rm.plot(x)

rm.plot(x, main = "Example", ylab = "Values", xlab = "Factor", title = "Groups")

rm.plot(x, "offset", "xaxis", "data")

rm.plot(x, "xaxis", "offset", "data")

rm.plot(x, 3, 2, 4)

x2 <- data.frame(id = 1:150, offset = rep(c("Group A", "Group B", "Group C"),each = 50), xaxis = sample(c("A", "B", "C", "D"),150, replace = TRUE), data = c(rnorm(50, 10, 5), rnorm(50, 15,6), rnorm(50, 20, 5)))

layout(matrix(c(1,2,3,3), 2,2,byrow = TRUE), heights = c(7,1))
rm.plot(x, main = "Data x1", ylab = "Values", xlab = "Factor", legend = FALSE, mar = c(4,4,4,1)+0.1)
rm.plot(x2, main = "Data x2", ylab = "Values", xlab = "Factor", legend = FALSE, mar = c(4,4,4,1)+0.1)
rm.plot(x2, plot = FALSE, title = "Groups")


y <- data.frame(id = 1:300, offset = rep(1, 300), axis = sample(LETTERS[1:6],300, replace = TRUE), data = c(rnorm(100, 1), rnorm(100), rnorm(100,1)))

par(mfrow = c(2,2))

rm.plot(y, legend = FALSE)

rm.plot(y, type = "p", legend = FALSE)

rm.plot(y, type = "l", legend = FALSE)

rm.plot(y, 3, 2, x.labels = "one group only")

 


z <- data.frame (id = 1:200, offset = rep(c("C 1", "C 2"), 200), axis = sample(LETTERS[1:4], 200, replace = TRUE), data = sample(1:20, 200, replace = TRUE))

par(mfrow = c(2,2))

rm.plot(z, noise = NULL, main = "no jitter")

rm.plot(z, noise = .001, main = "smaller jitter")

rm.plot(z, main = "standard jitter")

rm.plot(z, noise = .01, main = "bigger jitter")