ErrorBars

ErrorBars [/W=winName /CLIP=clip /L=lineThick /T=thick /X=xWidth /Y=yWidth /RGB=strokeColor ] traceName, mode [errorSpecification ]

The ErrorBars operation adds or removes error bars to or from the named trace in the specified graph and modifies error bar settings.

The "error bars" are lines that extend from each data point to "caps". The length of the line (or "bar") is usually used to bracket a measured value by the amount of uncertainty, or "error" in the measurement.

Parameters

traceName is the name of a trace on a graph (see Trace Names).

A string containing traceName can be used with the $ operator to specify traceName.

mode is one of the following keywords:

OFF	No error bars.
X	Horizontal error bars only.
Y	Vertical error bars only.
XY	Horizontal and vertical error bars.
BOX [=fillColor]	Box error bars, optionally with fill color expressed as (r,g,b) or (r,g,b,a). If no color is specified, boxes are not filled. The fillColor parameter was added in Igor Pro 8.00.
ELLIPSE={mode, p, alpha}
	Plots error ellipses.
	You must provide error values via a three-column wave using the ewave=ew error specification described below.
	mode=0: ew contains the standard deviation in X, the standard deviation in Y, and the correlation between X and Y. mode=1: ew contains the variance in X, the variance in Y, and the covariance of X and Y.
	p is the probability level represented by the error ellipses. p=0.6837, p=0.95, and p=0.997 represent one, two, and three standard deviations respectively. Larger values of p result in larger ellipses corresponding to higher confidence levels.
	alpha is an opacity value in the range of 0 (fully transparent) to 65535 (fully opaque). See Error Ellipse Color for details.
	The ellipse mode was added in Igor Pro 9.00.
	See Error Ellipses for further discussion.
NOCHANGE	This mode allows you to programmatically change aspects of error bars using flags (see Flags below) without affecting the mode or error specification. The NOCHANGE mode was added in Igor Pro 9.00.
SHADE={options, fillMode, fgColor, bkColor [ , negFillMode, negFgColor, negBkColor ]}
	SHADE was added in Igor Pro 7.00.
	options is reserved for future use and must be zero.
	fillMode sets the fill pattern:
	fillMode =0: Solid black. fillMode =1: Solid black. fillMode =2: Solid black. fillMode =3: 75% gray fillMode =4: 50% gray fillMode =5: 25% gray. fillMode >=6: See Fill Patterns.
	fgColor is (r,g,b) or (r,g,b,a). If all zeros including alpha, i.e., (0,0,0,0), then the actual color will be the trace color with an alpha of 20000.
	bkColor is used for patterns only and can be simply (0,0,0) for solid fills.
	negFillMode is the same as fillMode but for negative error shading.
	negFgColor is the same as fgColor but for negative error shading.
	negBkColor is the same as bkColor but for negative error shading.
	The errorSpecification, described below, affects only the Y amplitude of error shading.
	The X values of the trace to which shading is applied must be monotonic. Results with non-monotonic X values are undefined.
	See Error Shading for more information and examples. See Color Blending for information on the alpha color parameter.

For any mode other than OFF and NOCHANGE, there is an error specification whose format is:

	keyword [=value]

Error Specification Parameters

For any mode other than OFF and NOCHANGE, you must provide an error specification which consists of a keyword followed by zero or more parameters:

pct=value	value is the length of an error bar expressed as a percentage of the trace X or Y value.
sqrt	The error bar length is the square root of the trace X or Y value.
const=value	value is the length of an error bar independent of the trace X or Y value.
ewave=ew	ew is a three-column wave with error ellipse parameters. Each row represents information for one trace data point. The interpretation of the columns of ew depends on the mode parameter provided with the ELLIPSE keyword:
	mode=0: ew contains the standard deviation in X, the standard deviation in Y, and the correlation between X and Y. mode=1: ew contains the variance in X, the variance in Y, and the covariance of X and Y.
	ew may include a subrange specification as long as it results in effectively a 2D wave with three columns and a row for each trace data point. See Subrange Display Syntax.
	See Error Ellipses for further discussion.
wave =(w1,w2)	Each error bar length is obtained from the corresponding point of wave w1 for negative bars and from w2 for positive bars.
	If you omit w1 no negative bars are drawn. If you omit w2 no positive bars are drawn.
	You can use Subrange Display Syntax for w1 and w2.
mulWave = ew	Each error bar length is computed from a multiplier taken from the corresponding point of a wave ew. If your trace wave is tw, the error bar lengths are computed as:
	positive error bar length = tw * (ew - 1)
	negative error bar length = tw * (1 - 1/ew)
	This is appropriate if you have computed geometric mean and standard deviation, as would be appropriate for errors with lognormal distribution. Such error bars appear symmetrical on a log axis.
	The values in ew must be greater than or equal to 1. Values less than 1 result in the error bar not be displayed for that data point. An error value of exactly 1 results in a zero-length error bar.
	The mulWave keyword was added in Igor Pro 9.00.
nochange	The errorSpecification is unchanged from existing values. nochange allows you to, for instance, change the fill color for the box mode without having to repeat errorSpecification for the X and Y errors. nochange was added in Igor Pro 8.00.

See Examples below for examples using mode and errorSpecification.

mode and errorSpecification control only the lengths of the horizontal and vertical lines (the "bars") to the "caps". All other sizes and thicknesses are controlled by the flags.

Flags

/CLIP=clip
/CLIP={clipH, clipV}	Sets a distance in points by which error bars are allowed to extend beyond the plot area. If you use the first form, the vertical and horizontal values are both set to clip. Use the second form to set horizontal and vertical clipping independently. clipH and clipV default to 2 points. Values may be negative to restrict error bar drawing to an area inside the plot area. /CLIP was added in Igor Pro 9.00.
/L=lineThick	lineThick is the thickness of both the X and Y error bars drawn from the point on the wave to the caps. If you use the ELLIPSE keyword to draw error ellipses, lineThick sets the thickness of the ellipse outline.
/RGB=strokeColor	Sets the color of the lines used to draw the error bars. strokeColor is expressed as (r,g,b) or (r,g,b,a). The default color, used if you omit /RGB, is the same as the color of the trace to which the error bars are attached. The /RGB flag was added in Igor Pro 8.00.
	If you use the ELLIPSE keyword, strokeColor sets the color of the ellipse outline.
/T=thick	thick is the thickness of both the X and Y error bar "caps". In box mode, /T sets the thickness of the box outline.
/W=winName	Changes error bars in the named graph window or subwindow. When omitted, action will affect the active window or subwindow. This must be the first flag specified when used in a Proc or Macro or on the command line.
	When identifying a subwindow with winName, see Subwindow Syntax for details on forming the window hierarchy.
/X=xWidth	xWidth is the width (height, actually) of the caps to the left or right of the point.
/Y=yWidth	yWidth is the width of the caps above or below the point.

The thicknesses and widths are in units of points. The thickness parameters need not be integers. Although only integral thicknesses can be displayed exactly on a standard resolution screen, nonintegral thicknesses are produced properly on high resolution devices. Use /T=0 to completely suppress the caps and /L=0 to completely suppress the lines to the caps.

Details

If a wave specifying error values for waveName is shorter than waveName then the last value of the error wave is used for the unavailable points. If a point in an error wave contains NaN (Not a Number) then the half-bar associated with that point is not shown.

Examples

// X 10% of wave1, Y is 5% of wave1
ErrorBars wave1, XY pct=10, pct=5

// X error bars only, square root of wave1
ErrorBars wave1,X sqrt

// Y error bars only, constant error value = 4.3
ErrorBars wave1,Y const=4.3

// Error box, 10% in horizontal direction, 5% in vertical direction
ErrorBars wave1,BOX pct=10,pct=5

// Error box filled with blue color having 50% alpha (transparency)
// 10% in horizontal direction, 5% in vertical direction
ErrorBars wave1,BOX=(0,0,65535,32767) pct=10,pct=5	

// Change the error box fill to red color having 50% alpha
// without changing the way the errors are computed.
ErrorBars wave1,BOX=(65535,0,0,32767) nochange, nochange

// Y error bars only, wave w1 has errors for Y+ bars
// wave w2 has errors for Y- bars
ErrorBars wave1,Y wave=(w1,w2)

// Y error bars only, same wave for both Y+ and Y-.
// Overrides the trace color to make the error bars black.
ErrorBars/RGB=(0,0,0) wave1,Y wave=(w1,w1)

// Y error bars only, no Y+ error bars, wave w2 has errors for Y- bars
ErrorBars wave1,Y wave=(,w2)

// Turns error bars for wave1 off
ErrorBars wave1,OFF

Error Ellipse Example

See Error Ellipse Example.

See Also

Error Bars, Trace Names, Programming With Trace Names