kplot: Dot-and-bar plot for Key Comparisons
In metRology: Support for Metrological Applications

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

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

kplot(x, ...)

## Default S3 method:
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, ...)

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, ...)

`x`	an R object. For the default method, a vector of reported values. For the ilab method, an object of class ‘ilab’
`U`	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.
`k`	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 necessary) or a vector of length of length `length(x)`.
`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 marginal density is required via `do.pdf=TRUE`.
`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.main`) is provided in the same units as `x`; the percentage axis (`axis.pct`) shows corresponding percentage deviation.
`at`	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.

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.

Invisibly returns a list with components:

`order`	The order for plotting the original data, as returned by `order`.
`at`	x-axis locations used, in plotting order.

S Ellison s.ellison@lgc.co.uk

arrows.

  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)