boxplot.mvabund {mvabund}R Documentation

Boxplots for multivariate abundance Data

Description

Draw Boxplots of mvabund or mvformula Objects

Usage

## S3 method for class 'mvabund':
boxplot(
    x, y=NULL, ..., range=1.5, width=NULL, notch=FALSE, outline=TRUE, 
    names, border=par("fg"), col=NULL, pars=list(boxwex=0.8, 
    staplewex=0.5, outwex=0.5), at=NULL, xlab, ylab, main, pch=1, 
    fg="grey",  las=1, write.plot="show", filename="plot.mvabund", 
    n.vars=min(12,NCOL(x)), overall.main, var.subset=NA, 
    transformation="log", scale.lab="s", t.lab="o", mfrow=1, mfcol=NULL,
    ask=if(write.plot=="show"&(is.list(x)|!is.null(dotsnotnamed)))
    TRUE else FALSE )

## S3 method for class 'mvformula':
boxplot(
    x, ..., data=NULL, subset, main="", xlab=NULL, ylab="Abundances", 
    col="white", fg="grey", pch=20, las=NULL, n.vars=12, overall.main="", 
    var.subset=NA, write.plot="show", filename="plot.mvabund", 
    scale.lab=NULL, t.lab="o", mfrow=c(min(4,n.vars),3), mfcol=NULL, 
    border="black", all.labels=FALSE, ask=if(mixed & write.plot=="show") 
    TRUE else FALSE )

Arguments

x for the mvabund method x specifies the data from which the boxplots are to be produced. This can be either a numeric vector, or a single list containing such vectors. Additional unnamed arguments specify further data as separate vectors (each corresponding to a component boxplot). NAs are allowed in the data.
For the default method, unnamed arguments are additional data vectors (unless x is a list when they are ignored), and named arguments are arguments and graphical parameters to be passed to in addition to the ones given by argument pars (and override those in pars).
For the mvformula method, a formula, such as y ~ grp, where y is a numeric mvabund object of data values to be split into groups according to the grouping variable grp (a factor).
y for the mvabund method y can be an additional mvabund object, if x isn't a list.
... for the mvformula method, named arguments to be passed to the plot.mvformula method. Some arguments that are available for the mvabund method, are not available in plot.mvformula and can therefore not available in the mvformula method.
For the mvabund method, unamed arguments are additional data of vectors or matrices or mvabund objects, (unless x is a list when they are ignored),and named arguments are arguments and graphical parameters to be passed in addition to the ones given by argument pars (and override those in pars).
data for boxplot.mvformula an optional data.frame that contains the variables of the mvformula x
subset for boxplot.mvformula an optional subset of the data that should be used
range this determines how far the plot whiskers extend out from the box. If range is positive, the whiskers extend to the most extreme data point which is no more than range times the interquartile range from the box. A value of zero causes the whiskers to extend to the data extremes.
width a vector giving the relative widths of the boxes making up the plot.
notch if notch is TRUE, a notch is drawn in each side of the boxes. If the notches of two plots do not overlap this is ‘strong evidence’ that the two medians differ (Chambers et al., 1983, p. 62). See boxplot.stats for the calculations used.
outline if outline is not TRUE, the outliers are not drawn (as points whereas S+ uses lines).
names only available for the mvabund method: group labels which will be printed under each boxplot.
boxwex a scale factor to be applied to all boxes. When there are only a few groups, the appearance of the plot can be improved by making the boxes narrower.
border an optional vector of colors for the outlines of the boxplots. The values in border are recycled if the length of border is less than the number of plots. A list of the possible colors can be obtained with the function colors.
col if col is not NULL it is assumed to contain colors to be used to colour the bodies of the box plots. By default they are in the background colour.
pars a list of (potentially many) more graphical parameters, e.g., boxwex or outpch; these are passed to bxp; for details, see there.
at only available for the mvabund method: numeric vector giving the locations where the boxplots should be drawn; defaults to 1:n where n is the number of boxes.
xlab a title for the x axis, see plot.
ylab a title for the y axis, see plot.
main an optional main, a character value or a character vector (only if two mvabund.objects are passed).
pch this argument is not used.
fg the color of the axis, default=grey.
las the style of axis labels.
write.plot possible values: "show" (default) = plot is shown, or "eps", "postscript", "pdf", "jpeg", "bmp", "png" to save the plot in this format, plot is then not shown.
filename character, pathname where the file should be stored. Default location is R's working directory.
n.vars the number of variables to include in the plot.
overall.main a character to display as title for every window.
var.subset a numeric vector of indices indicating which variables of the mvabund.object should be included on the plot.
transformation an optional transformation, (ONLY) for the mvabund method. Note, that for the mvabund method transformation must be used instead of log.
Available values are:
"no" = untransformed, "sqrt"=square root transformed, "log" (default)=log(Y/min+1) transformed, "sqrt4" =4th root transformed.
scale.lab argument for limits and labelling of tickmarks:
"r" = R's default limits are used
"s" (default) = standard limits beginning at 0 are used.
t.lab argument for limits and labelling of tickmarks:
"o" (default) = “original” values of y are visible in the labels, e.g. for transformation="sqrt", then the tickmark labels are based on x (and y) not sqrt(x) (and sqrt(y))
"t" = transformed values of y are visible in the labels.
mfrow layout of the plotting window, either a pair of c(rows, columns) per window or an integer giving the prefered number of plots per window.
mfcol like mfrow, but the order of drawing is by row and not by column. If mfcol is passed, mfrow is ignored.
ask logical, logical. If TRUE the user is asked for input, before a new figure is drawn.
all.labels logical, for boxplot.mvformula, whether all labels should be drawn or just the labels on top and on the right side of each window
(this only makes a difference if there are several plots drawn per window)

Details

The function boxplot.mvabund allows simultaneous construction of many variables on a single figure. Thus a good comparative overview about the distribution of abundances for several species can be obtained.
There are several ways in which this function can be used. If one mvabund object, either named x or y or not names, is passed, it will be drawn on one plot and abundances can be compared over several variables.
If two mvabund objects, named x and y are passed for plotting, they will be shown on one plot, showing for each species the abundances of both objects directly one below the other.
If more than two mvabund objects are passed, each of them will be plotted separately.
Additionally, it is possible to specify x as a list of mvabund objects. Each of them will be plotted separately and any further mvabund data will be ignored, regardless if it is specified as y or unnamed.

The function boxplot.mvformula can be used to draw boxplots of a mvabund object in dependence of explanatory variables. The explanatory variables can be both numerical values as well as factor variables. If the formula contains both of them, there will be separate plots for the terms with numerical values and the terms with factor variables, displayed on separate windows.

The arguments plot, varwidth and add, which are availabe in the default method of boxplot, are not available for the mvabund and mvformula methods. The argument horizontal is not available for the mvabund method.
A number of other arguments like at and names are only available for the mvabund method.

Value

In contrast to the default method (boxplot.default) nothing will be returned. These functions are only used for drawing the plots.

Warning

The argument log, that is available in most plotting functions can not be used for plotting mvabund or mvformula objects. Instead use transformation for the mvabund method and for the mvformula method include transformations in the formula.

Author(s)

Ulrike Naumann and David Warton <David.Warton@unsw.edu.au>.

References

Warton, D. I. ( ) Raw data graphing: an informative but under-utilised tool for the analysis of multivariate abundances, , .

See Also

plot.mvabund.

Examples

require(graphics)

#### Basic Use ####
data(spider)
spiddat <- spider$abund
X <- spider$x

## Create the mvabund object:
spiddat <- mvabund(spiddat)

## Draw a boxplot for a mvabund object:
boxplot(spiddat)

## the same plot could be done by
plot(spiddat,type="bx")

#### Advanced Use ####
data(solberg)
solbdat <- solberg$abund
treatment<- solberg$x

# create pch type and colour vectors
treat.pch <- treat.col <- unclass(treatment)

# Boxplot for data
plot.mvabund(x=solbdat,y=treatment,type="bx",
             main="BoxPlot of The 12 Highest Abundant Species", 
             xlab="Abundance [sqrt scale]",ylab="",
             transformation="sqrt",t.lab="o",shift=TRUE)


[Package mvabund version 0.1-7 Index]