blockplot: Generate a "block plot" - a histogram variant identifiying...

In metRology: Support for Metrological Applications

Description

A “block plot” is a histogram variant identifiying individual data points. Histogram bars are replaced by a stack of rectangles (“blocks”, each of which is labelled. blockplot provides for grouped data, which generates vertically separated subplots for each group. Fills and label colours can be specified for each data point.

Usage

	blockplot(x, ...)

	bplot(x, ...)

	## Default S3 method:
blockplot(x, breaks = "23", labels = paste(1:length(x)), groups = NA, 
		xlim = NULL, ylim = NULL, 
		main = NULL, xlab = NULL, ylab = "Frequency", grp.labs = FALSE, 
		include.lowest = TRUE, right = TRUE, nclass = NULL, 
		plot = TRUE,  add=FALSE, ...)

	
	## S3 method for class 'formula'
blockplot(x, data = NULL, ..., subset, main = NULL, xlab = NULL)
	
	
	nclass.23(x)

Arguments

x	An R object. For the default method, a vector of values for which the blockplot is desired. For the formula method, a valid formula, such as y ~ grp (see Details).
data	For the formula method, a data frame or list from which the variables in formula should be taken.
subset	For the formula method, an optional vector specifying a subset of observations to be used for plotting.
breaks	Either a specification for choosing breakpoints for “binning” the data, or a vector giving the breakpoints themselves. The specification can be a single number, a function, or a character string identifying a function. See ‘Details’ for detailed specification.
labels	Labels for data points, passed to text; in principle of any type acceptable to text. Labels are placed inside boxes so should be short for readability.
groups	An optional grouping variable, coerced to factor. If present, one subplot is produced for each non-empty group.
xlim	Limits (x1, x2) for the horizontal (x) range of the plot. The default is the range of breaks, after computation if necessary.
ylim	limits for the vertical range of the plot. Will be overridden if square=TRUE (see below).
main	Main title for the plot, passed to plot.
xlab, ylab	x- and y-axis labels for the plot. As usual, either can be expressions (see plotmath).
grp.labs	Logical, determining whether group labels are plotted, or a vector of labels. See ‘Details’.
include.lowest	Logical, indicating whether a value equal to the lowest (or highest, for right = FALSE) breaks value should be included in a given bin. Passed to cut.
right	Logical, indicating whether the bin intervals should be closed on the right (and open on the left) or vice versa. Passed to cut.
nclass	Suggested number of classes for breaks; equivalent to a single numerical value for breaks.
plot	If FALSE, no plot is produced. The return value is returned invisibly.
add	If TRUE, the plot is added to an existing figure.
...	Further parameters passed to other functions, in particular, bkp, which creates the plot, and plot

Details

blockplot produces a block plot - a histogram variant identifying individual data points. Histogram bars are replaced by a stack of rectangles (“blocks”, each of which can be (and by default, is) labelled.

bplot is an alias for blockplot.

For the formula method, x is a formula, such as y ~ grp, in which y is a numeric vector of data values to be split into groups according to the grouping variable grp (usually a factor). More than one grouping variable can be specified, in which case subplots are produced for each level of the interaction between grouping factors.

The specification for breakpoints, breaks, is modelled closely on that for hist. breaks can be one of:

• a vector giving the (equally spaced) breakpoints between bins;

• a function to compute the vector of breakpoints;

• a single number giving the suggested number of bins for the blockplot;

• a character string naming an algorithm to compute the number of cells. Values of "23" (the default), "Sturges", "Scott", "FD" and "Freedman-Diaconis" are currently supported; see below for their effect

• a function to compute the number of bins.

In the last three cases the number is a suggestion only, as the breakpoints will be set to “pretty” values.

The different character string specifications correspond to “nclass” functions, including those used by hist; see nclass.FD for details of those. In addition, the default "23" corresponds to the function nclass.23. This is just a wrapper for the one-line expression

ceiling(length(x)^(2/3)),

which appears to provide good results for block plots.

Considerable control of graphical elements is provided by the plotting function bkp, which is called by blockplot. In particular, arguments passed through ... to bkp can control:

• The general shape of the plot, including the asbect ratio of the “blocks”;

• whether a plot should be added to an existing figure (add)

• the fill colour and shading, the border width, type and colour, and the font size and colour of individual blocks;

• the vertical location of the plot in the figure region offset;

• the vertical spacing between multiple plots on the same figure when a grouping variable is provided (grp.spacing and grp.at;

• the presence, location and appearance of labels for individual subplots;

• whether axes are plotted on any of the four sides of the plot;

• the appearance or omission of empty groups.

See bkp for further details.

Value

Blockplot currently returns an object of class blockplot, which is a list with elements:

x	The original data
groups	If there is more than one group, a factor of groups for each data point, with additional attribute "gname" containing a default name for the grouping variable(s). groups is set to NA if there is only one group.
x.left	Vector of x-coordinates for the left side of each block
x.height	Vector of y-coordinates for each box, relative to the group baseline
x.mid	Vector of x-coordinates for the middle of each block (the text location)
x.mid	Vector of x-coordinates for the middle of each block (the text location)

Note

The name “block plot” may not be in general use, but the package author has been unable to identify either an alternative designation or an original source for this type of plot. An example - apparently hand drawn - was given in ISO 5725-2:1994 (referenced above).

Author(s)

S Ellison [e-mail]

References

ISO 5725-2:1994 Accuracy (trueness and precision) of measurement methods and results – Part 2: Basic method for the determination of repeatability and reproducibility of a standard measurement method. ISO, Geneva, 1994.

See Also

For plotting and control of plot appearance: link{bkp}

For graphical elements: text, rect

For specification of breaks: link{nclass.Sturges}, link{nclass.Scott}, link{nclass.FD}

Examples

#A simple blockplot
set.seed(55)
x<-rnorm(48, 15)
blockplot(x)

#Aspect ratio control for square blocks
blockplot(x, square=TRUE)

# Specifying groups 
grp <- gl(3, 16)
blockplot(x, groups=grp)

#Formula interface
blockplot(x~grp)

#Vectorised colour specification
blockplot(x~grp, square=TRUE, fill=ifelse(1:48 %in% c(15, 23, 24), "gold", "white") )

#Group labelling
blockplot(x~grp, square=TRUE, grp.labs=paste("Level", 1:3), grp.pos=2)

#A missing group
xm <- x
xm[ grp == "2" ] <- NA
blockplot(xm~grp, square=TRUE, grp.labs=paste("Level", 1:3), grp.pos=2)

blockplot(xm~grp, square=TRUE, grp.labs=paste("Level", 1:3), grp.pos=2, drop.unused=FALSE)

metRology documentation built on Sept. 22, 2020, 3 a.m.