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]", ...)
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 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.
Limits (x1, x2)
for the horizontal (\(x\)) range of the plot. The default is the range of breaks
, after computation if necessary.
limits for the vertical range of the plot. Will be overridden if square=TRUE
(see below).
Main title for the plot, passed to plot
.
x- and y-axis labels for the plot. As usual, either can be expressions (see plotmath
).
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
.
Logical: If TRUE
, the plot will be added to an existing plot.
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.
Numeric scalar, giving the minimum vertical spacing (in units of block height) between subplots when there is more than one group.
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 colour for the rectangles (“blocks”) making up the plot.
Recycled to length length(x)
. Passed to rect
.
Border colour for the rectangles (“blocks”) making up the plot.
Recycled to length length(x)
. Passed to rect
.
Shading line density for (“blocks”) making up the plot. Recycled
to length length(x)
. Passed to rect
.
Shading line angle for (“blocks”) making up the plot. Recycled
to length length(x)
. Passed to rect
.
Border line type for (“blocks”) making up the plot. Recycled
to length length(x)
. Passed to rect
.
Border line width for (“blocks”) making up the plot. Recycled
to length length(x)
. Passed to rect
.
Colour used for text labels in each (“block”) making up the plot.
Recycled to length length(x)
. Passed to text
.
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.
Vector of two values giving text location adjustment for all block labels.
Passed to text
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.
Scalar: Line width for the subplot baseline(s).
Scalar: Line type for the subplot baseline(s).
Scalar: Line colour for the subplot baseline(s).
Logical, determining whether group labels are plotted, or a vector of labels. See ‘Details’.
Specification for the position of group labels. Follows pos
in
text
. See ‘Details’.
List of arguments to be passed to text
when drawing group labels.
Logical, indicating whether axes are drawn. Can be a vector of two logicals, specifying horizontal and vertical axes respectively. See ‘Graphical elements’ for details.
Aspect ratio, passed to plot
Logical, controlling whether a frame (box) is drawn round the plot.
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.
Character string appended to missing group labels.
Further parameters passed to plot
bxp
returns the original object x
with additional elements:
The vertical coordinated for the subplot baselines.
The width of the blocks in the plot.
bkp
provides considerable control of graphical elements. The main
elements, and the arguments controlling their location and appearance, are:
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.
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.
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;
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 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.
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.
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.
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
# NOT RUN {
#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)
# }
Run the code above in your browser using DataLab