raw.means.plot: raw.means.plot: Raw-Means Plots for Experimental Designs

In plotrix: Various Plotting Functions

raw.means.plot: Raw-Means Plots for Experimental Designs

Description

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/cell means (foreground) to provide a more accurate visualization of the underlying distribution.

Usage

raw.means.plot(data, col.offset = 2, col.x = 3, col.value = 4, na.rm = FALSE,
 avoid.overlap = c("y", "x", "both"), y.factor = 1, y.amount = NULL,
 x.amount = 0.05, 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), ...)

raw.means.plot2(data, col.id, col.offset, col.x, col.value,
 fun.aggregate = "mean", ...)

Arguments

data	a ‘⁠data.frame⁠’ in long format (i.e., each datapoint one row, see ‘⁠\link{reshape}⁠’ or the reshape package) 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 values (‘⁠col.value⁠’).
col.id	a ‘⁠character⁠’ scalar, specifiying the name of the column specifying the id column. (only for ‘⁠raw.means.plot2⁠’)
col.offset	a ‘⁠character⁠’ or ‘⁠numeric⁠’ (only ‘⁠raw.means.plot⁠’) scalar, specifiying either name or number of the column coding the different lines (the offset or first factor).
col.x	a ‘⁠character⁠’ or ‘⁠numeric⁠’ (only ‘⁠raw.means.plot⁠’) scalar, specifiying either name or number of the column coding the x-axis factor. Default is 3.
col.value	a ‘⁠character⁠’ or ‘⁠numeric⁠’ (only ‘⁠raw.means.plot⁠’) scalar, specifiying either name or number of the data column. Default is 4.
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.
avoid.overlap	character. What should happen to datapoints within one cell of the two factors that have the same value. ‘⁠"y"⁠’ (the default) jitter is added so that overlapping points are distinguishable on the y-axis ‘⁠"x"⁠’ jitter is added so that overlapping points are distinguishable on the x-axis ‘⁠"both"⁠’ jitter is added so that overlapping points are distinguishable on both the y- and the x-axis. anything else. No jitter is added.
y.factor	‘⁠factor⁠’ for controlling the amount of jitter on the y-axis (will be passed to jitter).
y.amount	‘⁠amount⁠’ for controlling the amount of jitter on the y-axis (will be passed to jitter).
x.amount	‘⁠amount⁠’ for controlling the amount of jitter on the x-axis (will be passed to jitter).
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. Silently recycled. Default: ‘⁠"darkgrey"⁠’
bg.f.col	background filling color: fill color of raw data points. Silently recycled. Default: ‘⁠NULL⁠’
fg.b.col	foreground border color: border color of mean data points. Silently recycled. Default: ‘⁠black⁠’
fg.f.col	foreground fill color: fill color for mean data points. Silently recycled. 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 ‘⁠raw.means.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 ‘⁠raw.means.plot⁠’. Just there for completeness. Default ‘⁠"n"⁠’ (and should not be changed).
plot	‘⁠logical⁠’. Should the ‘⁠raw.means.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 ‘⁠raw.means.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 (or ‘⁠raw.means.plot⁠’ for ‘⁠raw.means.plot2⁠’). The following arguments 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"⁠’
fun.aggregate	Function or function name used for aggregating the data across the two factors. Default is ‘⁠"mean"⁠’. (only for ‘⁠raw.means.plot2⁠’)

Details

‘⁠raw.means.plot2⁠’ is probably the more useful function, as it allows for using a data.frame with more than two-factors and aggregates across the other factors, but needs a column specifying the experimental unit (e.g., participant).

‘⁠raw.means.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 ‘⁠raw.means.plot⁠’ to plot only a legend by setting ‘⁠plot = FALSE⁠’ and ‘⁠legend = TRUE⁠’. Then, ‘⁠raw.means.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 par).

Value

Nothing. This function is invoked for its side effects.

Author(s)

Henrik Singmann ([e-mail]) with ideas from Jim Lemon

See Also

add.ps can be used in addition to‘⁠raw.means.plot⁠’ to compare the factors at each x-axis position, by adding p-values from t-tests to the x-axis.

Examples

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)))

raw.means.plot(x)

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

raw.means.plot(x, "offset", "xaxis", "data")

raw.means.plot(x, "xaxis", "offset", "data")

raw.means.plot(x, 3, 2, 4)

# different colors:
raw.means.plot(x, main = "Example", ylab = "Values", xlab = "Factor",
 title = "Groups", fg.f.col = c("red","blue", "green"))

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))
raw.means.plot(x, main = "Data x1", ylab = "Values", xlab = "Factor",
 legend = FALSE, mar = c(4,4,4,1)+0.1)
raw.means.plot(x2, main = "Data x2", ylab = "Values", xlab = "Factor",
 legend = FALSE, mar = c(4,4,4,1)+0.1)
raw.means.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))

raw.means.plot(y, legend = FALSE)

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

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

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


# Example with overlapping points
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))

# x versus y jitter
par(mfrow = c(2,2))
raw.means.plot(z, avoid.overlap = "none", main = "no-jitter")
raw.means.plot(z, main = "y-axis jitter (default)")
raw.means.plot(z, avoid.overlap = "x", main = "x-axis jitter")
raw.means.plot(z, avoid.overlap = "both", main = "both-axis jitter")


# y-axis jitter (default)
par(mfrow = c(2,2))
raw.means.plot(z, avoid.overlap = "none", main = "no jitter")
raw.means.plot(z, y.factor = 0.5, main = "smaller y-jitter")
raw.means.plot(z, main = "standard y-jitter")
raw.means.plot(z, y.factor = 2, main = "bigger y-jitter")


# x-axis jitter (default)
par(mfrow = c(2,2))
raw.means.plot(z, avoid.overlap = "none", main = "no jitter")
raw.means.plot(z, avoid.overlap = "x", x.amount = 0.025,
 main = "smaller x -jitter")
raw.means.plot(z, avoid.overlap = "x", main = "standard x-jitter")
raw.means.plot(z, avoid.overlap = "x", x.amount= 0.1,
 main = "bigger x-jitter")



## Not run: 

#The examples uses the OBrienKaiser dataset from car and needs reshape.
require(reshape)
require(car)
data(OBrienKaiser)
OBKnew <- cbind(factor(1:nrow(OBrienKaiser)), OBrienKaiser)
colnames(OBKnew)[1] <- "id"
OBK.long <- melt(OBKnew)
OBK.long[, c("measurement", "time")] <-
 t(vapply(strsplit(as.character(OBK.long$variable), "\\."),  "[", c("", "")))

raw.means.plot2(OBK.long, "id", "measurement", "gender", "value")

raw.means.plot2(OBK.long, "id", "treatment", "gender", "value")

# also use add.ps:
# For this example the position at each x-axis are within-subject comparisons!
raw.means.plot2(OBK.long, "id", "measurement", "gender", "value")
add.ps(OBK.long, "id", "measurement", "gender", "value", paired = TRUE)
 #reference is "fup"

raw.means.plot2(OBK.long, "id", "measurement", "gender", "value")
add.ps(OBK.long, "id", "measurement", "gender", "value", ref.offset = 2,
 paired = TRUE) #reference is "post"

# Use R's standard (i.e., Welch test)
raw.means.plot2(OBK.long, "id", "treatment", "gender", "value")
add.ps(OBK.long, "id", "treatment", "gender", "value",
 prefixes = c("p(control vs. A)", "p(control vs. B)"))

# Use standard t-test
raw.means.plot2(OBK.long, "id", "treatment", "gender", "value")
add.ps(OBK.long, "id", "treatment", "gender", "value", var.equal = TRUE,
 prefixes = c("p(control vs. A)", "p(control vs. B)"))


## End(Not run)

plotrix documentation built on Nov. 10, 2023, 5:07 p.m.