kplot: Dot-and-bar plot for Key Comparisons

Description

Produces a dot plot of typical metrology comparison data (value/uncertainty) with error bars, assigned value and uncertainty and optional percentage deviation axis or marginal density

Usage

kplot(x, ...)

## S3 method for class 'default':
kplot(x,U=NULL, labels=names(x),  assigned=NULL, U.assigned=NULL, 
	U.lo=U, U.hi=U, k=2, strata=NULL,
	do.percent=!is.null(assigned) && !do.pdf, 
	ordered=TRUE, order.strata=levels(strata),
	xlim=c(0.5, length(x)+0.5), ylim,
	main=NULL, xlab=NULL, ylab=NULL,
	axis.main=2, axis.pct=4, at=1:length(x), at.main=NULL,
	cex.axis=0.8, las=2, las.pct=1, ylab.line=2.5, 
	ylab.line.pct=2.1, ci.width=0.03, col.ci=par("fg"), 
	lty.ci=par("lty"), lwd.ci=par("lwd"), pch=21, 
	col=par("fg"), bg="white", add.outliers=FALSE, 
	outlier.offset=0.2, mar=NULL, box=TRUE,
	do.pdf=FALSE, do.individual.pdf=do.pdf, 
	col.pdf=par("fg"), lwd.pdf=1, lty.pdf=1,
	do.total.pdf=TRUE, col.total.pdf=col.pdf[1], 
	lwd.total.pdf=2, lty.total.pdf=1, n.pdf=200, 
	pdf.layout=c(4,1), pdf.scale=0.7, pdf.offset=0.05, 
	xlim.pdf, pdf.axis=FALSE, las.pdf=0, 
	mgp.pdf=c(3,0.5,0), ...)
	
## S3 method for class 'ilab':
kplot(x, \dots)

kpoints(x,U=NULL, labels=names(x), U.lo=U, U.hi=U, k=2, 
	strata=NULL, ordered=TRUE, order.strata=levels(strata),
	at=1:length(x), ci.width=0.03, col.ci=par("fg"), 
	lty.ci=par("lty"), lwd.ci=par("lwd"), pch=21, 
	col=par("fg"), bg="white", add.outliers=FALSE, 
	outlier.offset=0.2, ...)

Arguments

an R object. For the default method, a vector of reported values. For the ilab method, an object of class ilab

Vector of length length(x) of expanded uncertainties

labels

Vector of of length length(x) labels for x-axis marks.

assigned

Assigned value for the comparison. Plotted as a horizontal line on the plot.

U.assigned

Expanded uncertainty for the assigned value

U.lo, U.hi

Vectors of of length length(x) of lower and upper limits for the uncertainty intervals around the reported values, to allow asymmetric intervals. Both default to U.

Coverage factor originally used in calculating U. Required only if do.pdf=TRUE, as k is used to calculate standard uncertainties from U. k can be a scalar (recycled to length length(x) if n

strata

A Factor identifying subsets of the data. Currently not implemented.

do.percent

Logical indicating whether percentage deviation should be plotted as a secondary axis. Defaults to TRUE if an assigned value is provided and FALSE if there is no assigned value or if a margi

ordered

If TRUE, values are plotted in ascending order.

order.strata

Character vector showing the order of plotting for strata. Currently not implemented.

xlim, ylim

Plot limits as in plot.default.

main, xlab, ylab

Titles; see ?title for details.

axis.main, axis.pct

Integers specifying on which side of the plot the relevant axis is to be drawn, passed to axis as side. The axis is placed as for follows: 1=below, 2=left, 3=above and 4=right. The main axis (axis.mai

Vector of x-axis locations for the data points, x-axis tick marks and labels. Defaults to 1:length(x).

at.main

The points at which tick-marks are to be drawn on the main (y) axis. Passed to axis via at.

cex.axis

The magnification to be used for axis annotation relative to the current setting of 'cex'. Passed to axis.

las, las.pct

Integers defining x- and y axis and percentage axis label orientation; see par(las).

ylab.line, ylab.line.pct

Margin lines for main and percentage axis titles. Passed to axis.

ci.width

Width of error bar terminators, passed to arrows.

col.ci, lty.ci, lwd.ci

Graphical parameters for the error bars; passed to arrows.

pch, col, bg

Graphical parameters for data points, passed to points. bg specifies the fill colour for pch from 21 to 25.

add.outliers

If TRUE, points outside ylim are indicated as an arrow indicating the direction in which the omitted points lie, with a text label showing the reported value.

outlier.offset

X-offset (in x-axis units) specifying lateral location of outlier tet labels relative to x-axis location of the outlier indicator.

mar

Plot margins as in par(mar). The default varies depending on do.pct and do.pdf.

box

If TRUE, a box is drawn round the plot region.

do.pdf

If TRUE, a marginal density and/or individual densities for the individual reported values are plotted based on the reported values x and standard uncertainties calculated as U/k.

do.individual.pdf

Logical controlling whether the individual densities are plotted as well as/instead of the combined density.

col.pdf, lwd.pdf, lty.pdf

Graphical parameters controlling the appearance of the marginal density plot(s). Vectors are permitted, allowing different styles for each individual pdf.

do.total.pdf

Logical controlling whether the sum of individual densities is plotted.

col.total.pdf, lwd.total.pdf, lty.total.pdf

Graphical parameters controlling the appearance of the marginal density plot for the combined density.

n.pdf

Number of points used to construct the marginal density.

pdf.layout

Vector of length 2 specifying the relative sizes of the main plot and marginal density plot. See ?layout for details.

pdf.scale, pdf.offset

Offset and scaling factor used to control the location and height of the marginal density plot(s).

xlim.pdf

Controls the x-axis (i.e. the horizontal axis) for the marginal density plotting area.

pdf.axis

If TRUE and no other axis has been plotted to the right of the main plot, an axis is plotted with the marginal density.

las.pdf, mgp.pdf

Axis control parameters passed to axis to plot the axis for the marginal density.

...

Parameters passed to other functions; currently unused.

Value

Invisibly returns a list with components:
orderThe order for plotting the original data, as returned by order.
atx-axis locations used, in plotting order.

Details

If do.pdf=TRUE a marginal density plot is added. This plot is constructed from a set of (currently) normal densities centred at x with standard deviation U/k. If a marginal density is plotted, par("layout") is changed to pdf.layout; otherwise, par("layout") is set to matrix(1). Both override any previously set layout. par("layout") is preserved on exit. The ilab method passes all parameters in ... to the default method with default values for x, upper and lower bounds U.lo and U.hi, labels and title taken from the ilab object. kpoints is a convenience function for adding points with confidence intervals to an existing plot. kpoints is not a generic function and requires a vector x. Note that kpoints does not check for the presence of a marginal density plot.

Examples

Run this code

data(Pb)
  kplot(Pb$value, Pb$U, assigned=2.99, U.assigned=0.06)
  kplot(Pb$value, Pb$U, assigned=2.99, U.assigned=0.06, do.pdf=TRUE)
	
  #Use of return value for annotation
  kp<-kplot(Pb$value, Pb$U, assigned=2.99, U.assigned=0.06)
  text(kp$at, Pb$value-Pb$U, Pb$lab, srt=90, pos=4, cex=0.7)