Learn R Programming

metRology (version 0.9-28-1)

xs.plot: Mean/Standard deviation plot with confidence region.

Description

Produces a plot of standard deviations versus means with a confidence region based on either robust or classical estimates of location and scale.

Usage

xs.plot(x, …)

# S3 method for default xs.plot(x,g,s, degfree, labels.arg=NA, mu, sigma, probs=c(0.5, 0.95, 0.99), basis=c("robust","classical"), method=c("chisq","density"), main=paste("X-S plot -", basis, "basis"), xlab=deparse(substitute(x)), ylab, contours=TRUE, col.contours="lightgrey", lty.contours=par("lty"), lwd.contours=par("lwd"), label.contours=contours, format.clab="p=%3.2f", pos.clab="bottomright", col.clab=col.contours, cex.clab=0.7, cex.label=0.7, pos=3, adj=NULL, pch=par("pch"), col=par("col"), bg=par("bg"), cex=par("cex"), add=FALSE, …)

XSplot(x, …)

Arguments

x

Numeric vector of values to be plotted.

g

grouping factor of length length(x).

s

numeric vector of standard deviations of length length(x) associated with x.

degfree

A single value for degrees of freedom associated with all the standard deviations s. Ignored if s is not supplied.

labels.arg

An optional vector of point labels, coerced to character on use.

mu

A single location used to centre the confidence region. The default is specified by "basis"; see Details.

sigma

A measure of dispersion against which deviations x-mu can be compared.

probs

A vector of probabilities for confidence region contours.

basis

Controls the nature of the location and scale estimators used to produce the confidence contours drawn on the plot. See Details for specification.

method

The method used to calculate the confidence region. See Details.

main

Main title for the plot.

xlab, ylab

x- and y-axis labels,

contours

logical, specifying whether confidence contours should be drawn.

col.contours, lty.contours, lwd.contours

Colour, line type and line width for contour lines.

label.contours

Logical, controlling whether contour lines are labelled with approximate probabilities.

format.clab

Format string for contour labels, passed to sprintf.

pos.clab

Specification for location of contour labels. A vector can be provided to give multiple labels. See Details for further description.

col.clab, cex.clab

Colour and expansion for contour labels.

pch, col, bg, cex

Graphical parameters passed to points.

cex.label

Expansion factor for point labels, passed to text.

pos, adj

Specifies position/adjustment of point labels. Passed to text; see text for details.

add

If TRUE the plot region is not cleared before plotting; points and contours are added to the present plot. Use pch=NA to suppress symbols if only added contours are required.

Other parameters passed to plot.

Value

A list with components:

x, y

respectively, the plotted locations and standard deviations. (the names allow a simple call to plot())

mu

The location and pooled SD estimates \(\hat{\mu}\) and \(\hat{\sigma}\) used to construct the confidence ellipsoids.

clist

A list of sets of coordinates for each confidence region.

Details

A plot of standard deviations against locations is produced, together with optional confidence region(s) calculated (by default) by a method suggested in ISO 13528:2005.

If s is supplied, x is taken as a vector of locations and s a vector of standard deviations. degfree must be supplied in this case.

If g is supplied and s is not, the locations and standard deviations used are the means and standard deviations for each group. degfree is calculated from the median group size. Groups should, of course, be of the same size for accurate inference; however, using the median group size allows for some groups with missing values.

If s and g are both supplied, g is ignored with a warning

If requested by contours=TRUE, confidence regions are drawn for each value of probs. Contour location and shape are controlled by basis which specifies the location and scale estimators used, and method, which specifies the method of calculation for the contours. Two methods are supported; one using the chi-squared distribution (method="chisq") and one based on equal density countours (method="density"). The default, and the method recommended by the cited Standard, is method="chisq" and basis="robust".

Both calculations for confidence regions require estimation of a location \(\hat{\mu}\) and an estimate \(\hat{\sigma}\) of the pooled within-group standard deviation or pooled estimate from s. If basis="robust", \(\hat{\mu}\) and \(\hat{\sigma}\) are calculated using algA and algS respectively. If basis="classical", \(\hat{\mu}\) and \(\hat{\sigma}\) are the mean of the group means and the classical pooled standard deviation respectively. If mu or sigma are given, these are used in place of the calculated \(\hat{\mu}\) and \(\hat{\sigma}\) respectively.

If method="chisq", contours for probability \(p\) are calculated as

$$s=\hat{\sigma}\exp\left ( \pm\frac{1}{\sqrt{2(n-1)}}\sqrt{\chi_{2,p}^2-n \left ( \frac{x-\hat{\mu}}{\hat{\sigma}}\right ) ^2}\right )$$

for \(x\) from \( \hat{\mu}-\hat{\sigma}\sqrt{\frac{\chi_{2,p}^2}{n}}\) to \(\hat{\mu}+\hat{\sigma}\sqrt{\frac{\chi_{2,p}^2}{n}}\).

If method="density", contours for probability \(p\) are calculated using Helmert's distribution to provide constant likelihood contours round the chosen mean and standard deviation. In the present implementation, these are found using uniroot to find the mean corresponding to the required density at given standard deviations. The density chosen is \(d_{max}(1-p)\) where \(p\) is the probability and \(d_{max}\) the maximum density for Helmert's distribution for the requisite nunber of degrees of freedom. (See Kruskal (1946) for a description of Helmert's distribution and, for example, Pawitan (2001) for the rationale behind the choice of density contour level.) This seems to give reasonably good results for \(n \ge 3 \) but is anticonservative (particularly to high \(s\)) for \(n = 2 \).

Contours are by default labelled. Label locations can be specified using pos.clab. Options are code"top", code"topright", code"right", code"bottomright", code"bottom", code"bottomleft", code"left" and code"topleft". A vector can be specified to give labels at more than one such location. Contour labels are usually placed approximately at the location(s) indicated and adjusted outward appropriately. For the special case of method="density" and degfree=1 (or where group sizes \(n=1\)), for which the region is a maximu width at s=0, "bottomright" and "bottomleft" place labels immediately below the countour boundary at \(s=0\) and, if specified, "bottom" is replaced with c("bottomright", "bottomleft").

XSplot is an alias for xs.plot.

References

ISO 13528:2005, Statistical methods for use in proficiency testing by interlaboratory comparisons, International Organization for Standardization, Geneva (2005)

Y Pawitan, (2001) In all likelihood: Statistical Modelling and Inference Using Likelihood,Clarendon Press, Oxford, pp258-9

W Kruskal, American Mathematical Monthly 53, 435-438, (1946)

See Also

algA, algS

axis for axis control; points, text for plotting parameters; sprintf for contour label formatting.

duewer.plot for an alternative plot for locations and associated standard errors or standard uncertainties;

Examples

Run this code
# NOT RUN {
	require(metRology)
	set.seed(1017)
	x <- rnorm(80)
	g <- gl(20,4)
	
	xs.plot(x,g)

	#Identical plot with precalculated s:
	X <- tapply(x,g,mean)
	S <- tapply(x,g,sd)
	xs.plot(X, s=S, degfree=3)

	#Specify different location and within-group SD estimates:
	xs.plot(X, s=S, degfree=3, mu=median(X), sigma=median(S))
	
	#Illustrate multiple contour labelling, point labels and further embellishment
	rv <- xs.plot(x,g, pos.clab=c("bottomleft", "bottomright"), labels=TRUE)
	abline(v=rv$mu, h=rv$s, col=2)
	
	
# }

Run the code above in your browser using DataLab