bkp: Draw block plots from block plot objects
In metRology: Support for Metrological Applications

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

bkp draws block plots based on block plot objects generated by blockplot and its methods. It is normally called from within blockplot but can be invoked directly.

	bkp(x, labels = x$labels, xlim = NULL, ylim = NULL, 
            main = NULL, xlab = NULL, ylab = "Frequency", 
            square = FALSE, add = FALSE, offset = 0, 
            grp.spacing = 2, grp.at = NA, 
            fill = NA, border = NULL, density = NULL, angle = 45, 
            lty = 1, lwd = 2, label.col = 1, cex = NA, adj = c(0.5, 0.4), 
            uline = 2, uline.lwd = lwd, uline.lty = 1, 
            uline.col = if (!is.null(border)) border else par("fg"), 
            grp.labs = FALSE, grp.pos = 1, glab.control = list(), 
            axes = c(TRUE, FALSE), asp = NA, frame.plot = any(axes), 
            drop.unused = TRUE, unused.label="[Missing]", ...)

`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).
`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.
`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`).
`square`	Logical: If `square=TRUE`, the aspect ratio is set (via `asp`) to make the individual blocks appear square when rendered. Note that this generally overrides `ylim`.
`add`	Logical: If `TRUE`, the plot will be added to an existing plot.
`offset`	Numeric scalar value. Vertical offset for the plot, in units of block height. `offset` is added to the vertical position of the boxplot and any subplots. `offset` can be considered as a number of vertical block heights to raise (or lower, if negative) the plot. This, with `add`, is useful for adding further groups manually to an existing plot.
`grp.spacing`	Numeric scalar, giving the minimum vertical spacing (in units of block height) between subplots when there is more than one group.
`grp.at`	Optional vector specifying explicit vertical locations for subplot baselines (including the first group). The default (`grp.at=NA`) is to use `grp.spacing`. If specified, `grp.at` overrides `grp.spacing`.
`fill`	Fill colour for the rectangles (“blocks”) making up the plot. Recycled to length `length(x)`. Passed to `rect`.
`border`	Border colour for the rectangles (“blocks”) making up the plot. Recycled to length `length(x)`. Passed to `rect`.
`density`	Shading line density for (“blocks”) making up the plot. Recycled to length `length(x)`. Passed to `rect`.
`angle`	Shading line angle for (“blocks”) making up the plot. Recycled to length `length(x)`. Passed to `rect`.
`lty`	Border line type for (“blocks”) making up the plot. Recycled to length `length(x)`. Passed to `rect`.
`lwd`	Border line width for (“blocks”) making up the plot. Recycled to length `length(x)`. Passed to `rect`.
`label.col`	Colour used for text labels in each (“block”) making up the plot. Recycled to length `length(x)`. Passed to `text`.
`cex`	Size of text labels in each (“block”) making up the plot. Recycled to length `length(x)` and passed to `text`. The default is to fit text inside each block automatically.
`adj`	Vector of two values giving text location adjustment for all block labels. Passed to `text`
`uline`	Specification for the distance by which the baseline for each subplot extends beyond the data range for the group. See ‘Graphical elements’ for details. The default is two units either side.
`uline.lwd`	Scalar: Line width for the subplot baseline(s).
`uline.lty`	Scalar: Line type for the subplot baseline(s).
`uline.col`	Scalar: Line colour for the subplot baseline(s).
`grp.labs`	Logical, determining whether group labels are plotted, or a vector of labels. See ‘Details’.
`grp.pos`	Specification for the position of group labels. Follows `pos` in `text`. See ‘Details’.
`glab.control`	List of arguments to be passed to `text` when drawing group labels.
`axes`	Logical, indicating whether axes are drawn. Can be a vector of two logicals, specifying horizontal and vertical axes respectively. See ‘Graphical elements’ for details.
`asp`	Aspect ratio, passed to `plot`
`frame.plot`	Logical, controlling whether a frame (box) is drawn round the plot.
`drop.unused`	Logical specification for the treatment of empty groups. If `TRUE`, groups (identified by levels in `x$groups`) that contain no non-missing values will be omitted from the plot. If `FALSE`, a space is created for the missing subplot but no subplot is generated. If `grp.labels` requires group labelling, the group label is drawn in the space with `unused.label` appended.
`unused.label`	Character string appended to missing group labels.
`...`	Further parameters passed to `plot`

bkp provides considerable control of graphical elements. The main elements, and the arguments controlling their location and appearance, are:

General appearance

A block plot of a single group of data has the general appearance of a histogram. However, instead of vertical bars (of possibly variable width) indicating the number of data points within the bin interval, each bin is a stack of rectangles, each corresponding to a single data point and with an optional label identifying the datum.

Block plots of this kind are useful for data sets of modest size; typically 10-100 per group, as individual labels quickly become hard to identify in larger data sets.

By default, blockplot produces one such plot for a set of data. If a series of such plots is needed, this can be accommodated either by using blockplot with add=TRUE to build up a plot manually, setting xlim, ylim and breaks to accommodate all the required groups. Alternatively, a grouping factor can be provided (via argument groups) which will produce a series of subplots, laid out automatically. The use of groups and the corresponding layout options are detailed below (see “Groups”).

The vertical position of a single block plot within the figure can be set using offset, which sets the baseline height, in units of block height, from the figure origin. This is useful for separating several groups that are added manually; just set offset appropriately for each separate plot. Note that setting offset has no effect on the automatic ylim setting, which means that ylim must be set manually to accommodate the vertical offset.

Blocks

Each individual rectangle (“block” in the plot corresponds to a single data point. In this implementation, blocks appear in rank order from left to right and from bottom to top; that is, data are placed in vertical bins as in a normal histogram but, in addition, the vertical ordering of blocks corresponds to the data order within each bin, with blocks at the bottom corresponding to lower values.

Blocks are always 1 unit high, so the total vertical height of each bin corresponds directly to frequency (not density) in a histogram. The block width is the interval between breaks, which must be equispaced.

By default, the apparent aspect ratio for blocks depends primarily on xlim and ylim and the height and width of the plotting device. However, setting square=TRUE will cause the plot aspect ration (asp) to be set such that the bocks appear square in the current plot window.

Fill colour, border colour and style, fill effects and text colour of individual blocks can all be controlled using fill, border, density, angle, lty, lwd and label.col, as the relevant arguments can be vectors of length length(x). This allows conditional formatting, for example to identify a particular data point or some secondary grouping variable.

Subplot baseline

The baseline for each subplot is controlled by uline, as follows:

TRUE:: The line extends the full width of the plot;
FALSE:: No baseline is drawn;
numeric:: If numeric (as for the default), uline specifies the distance that the baseline extends beyond each end of the data, in units of block width. uline can be length 2 numeric vector, which specifies the baseline extension on the left and right sides respectively.

Colour, line type, and line width for the subplot baseline(s) can be controlled with uline.col, uline.lty, and uline.lwd respectively.

Axes

Axes can be controlled with the axes argument, which controls whether or not axes are drawn. If a vector of two logical values (as for the default), axes specifies drawing for horizontal and vertical axes respectively.

The horizontal axis is normally continuous for the plot. If a vertical (frequency) axis is requested (either by axes=TRUE or, for example, by axes=c(TRUE, TRUE), a vertical axis is drawn for each subplot, starting at zero at the baseline and terminating at the highest vertical value in the subplot. Vertical axes, restarting at 0 at the next subplot baseline, are drawn if there is more than one group.

Groups

blockplot provides a simple grouping mechanism to display separate subplots for different groups of data on the same figure. The default method provides for a grouping variable specified via groups. The formula method provides a somewhat more flexible interface, allowing specification of more than one grouping variable. Like boxplot, if there is more than one goruping variable in the formula, subplots are drawn for each (non-empty) level of the interaction term.

Subplots for different groups are arranged vertically. Vertical position can be specified explicitly via grp.at or, more simply, by setting grp.spacing. The latter sets grp.at to equal vertical spacing such that the smallest vertical gap is grp.spacing. Both grp.at and grp.spacing are in units of block height; that is, grpspacing=2 (the default) means that the smallest vertical gap is equivalent to two blocks.

Group labels

Labels can be added to each subplot. These are controlled by grp.labs .. grp.labs provides the specification for group labels, and can be a single logical or a vector of labels. Effects of grp.labs are as follows:

FALSE (The default): No group labels are drawn.
TRUE Labels are taken as levels(groups), and set to "1" if there is only one group.
Vector If a character vector (or expression) is provided, these are used as labels for the groups plotted.

WARNING: If missing values in x cause group levels to be dropped, those groups will not be plotted. grp.labs must have the same length as the number of groups plotted. An error is generated if the length of labels differs from the number of groups actually plotted.

grp.pos specifies the general positioning of group labels relative to each subplot. grp.pos follows pos in text: Values of 1, 2, 3 and 4, respectively indicate positions below, to the left of, above and to the right of the plot.

The detailed positioning of group labels is automatic; the four positions specified by grp.pos correspond approximately to the midpoints of the corresponding edge of each plot, where the ‘edges’ are the baseline, leftmost block, topmost block and rightmost block. Labels are placed a short distance outward from these edges. Labels are justified according to position; grp.pos is re-used as the default pos argument to text.

Further control of group label position is available via grp.control, which is a list (empty by default) of arguments passed to text. Ths can include arguments such as pos and adj, as well as appearance elements such as col, cex etc.

bxp returns the original object x with additional elements:

`grp.at`	The vertical coordinated for the subplot baselines.
`blockwidth`	The width of the blocks in the plot.

Stephen L R Ellison s.ellison@lgcgroup.com.

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.

For constructing breaks and grouping: blockplot

For graphical elements: text, rect

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

#Aspect ratio control for square blocks
bkp(b, square=TRUE)

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

# Add vertical axes ( axes=TRUE asks for horizontal and vertical axes)
bkp(bg, axes=TRUE ) 

#Axes both left and right
par(mar=c(5,4,4,4)+0.1)
bkp(bg, axes=c(TRUE, TRUE, FALSE, TRUE) ) 
		#Note that axes[3] is FALSE to suppress top axis
		
# Vectorised colour specification
bkp(bg, square=TRUE, fill=ifelse(1:48 %in% c(15, 23, 24), "gold", "white") )

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