1 /* Flot plugin for plotting error bars.
3 Copyright (c) 2007-2013 IOLA and Ole Laursen.
4 Licensed under the MIT license.
6 Error bars are used to show standard deviation and other statistical
9 * Created by Rui Pereira - rui (dot) pereira (at) gmail (dot) com
11 This plugin allows you to plot error-bars over points. Set "errorbars" inside
12 the points series to the axis name over which there will be error values in
13 your data array (*even* if you do not intend to plot them later, by setting
14 "show: null" on xerr/yerr).
16 The plugin supports these options:
20 errorbars: "x" or "y" or "xy",
22 show: null/false or true,
23 asymmetric: null/false or true,
24 upperCap: null or "-" or function,
25 lowerCap: null or "-" or function,
27 radius: null or number
29 yerr: { same options as xerr }
33 Each data point array is expected to be of the type:
37 "xy" [ x, y, xerr, yerr ]
39 Where xerr becomes xerr_lower,xerr_upper for the asymmetric error case, and
40 equivalently for yerr. Eg., a datapoint for the "xy" case with symmetric
41 error-bars on X and asymmetric on Y would be:
43 [ x, y, xerr, yerr_lower, yerr_upper ]
45 By default no end caps are drawn. Setting upperCap and/or lowerCap to "-" will
46 draw a small cap perpendicular to the error bar. They can also be set to a
47 user-defined drawing function, with (ctx, x, y, radius) as parameters, as eg.
49 function drawSemiCircle( ctx, x, y, radius ) {
51 ctx.arc( x, y, radius, 0, Math.PI, false );
52 ctx.moveTo( x - radius, y );
53 ctx.lineTo( x + radius, y );
57 Color and radius both default to the same ones of the points series if not
58 set. The independent radius parameter on xerr/yerr is useful for the case when
59 we may want to add error-bars to a line, without showing the interconnecting
60 points (with radius: 0), and still showing end caps on the error-bars.
61 shadowSize and lineWidth are derived as well from the points series.
69 errorbars: null, //should be 'x', 'y' or 'xy'
70 xerr: { err: 'x', show: null, asymmetric: null, upperCap: null, lowerCap: null, color: null, radius: null},
71 yerr: { err: 'y', show: null, asymmetric: null, upperCap: null, lowerCap: null, color: null, radius: null}
76 function processRawData(plot, series, data, datapoints){
77 if (!series.points.errorbars)
82 { x: true, number: true, required: true },
83 { y: true, number: true, required: true }
86 var errors = series.points.errorbars;
87 // error bars - first X then Y
88 if (errors == 'x' || errors == 'xy') {
89 // lower / upper error
90 if (series.points.xerr.asymmetric) {
91 format.push({ x: true, number: true, required: true });
92 format.push({ x: true, number: true, required: true });
94 format.push({ x: true, number: true, required: true });
96 if (errors == 'y' || errors == 'xy') {
97 // lower / upper error
98 if (series.points.yerr.asymmetric) {
99 format.push({ y: true, number: true, required: true });
100 format.push({ y: true, number: true, required: true });
102 format.push({ y: true, number: true, required: true });
104 datapoints.format = format;
107 function parseErrors(series, i){
109 var points = series.datapoints.points;
111 // read errors from points array
116 var xerr = series.points.xerr,
117 yerr = series.points.yerr;
119 var eb = series.points.errorbars;
120 // error bars - first X
121 if (eb == 'x' || eb == 'xy') {
122 if (xerr.asymmetric) {
126 if (yerr.asymmetric){
129 } else eyl = points[i + 4];
133 if (yerr.asymmetric) {
136 } else eyl = points[i + 3];
139 } else if (eb == 'y')
140 if (yerr.asymmetric) {
143 } else eyl = points[i + 2];
146 if (exu == null) exu = exl;
147 if (eyu == null) eyu = eyl;
149 var errRanges = [exl, exu, eyl, eyu];
150 // nullify if not showing
162 function drawSeriesErrors(plot, ctx, s){
164 var points = s.datapoints.points,
165 ps = s.datapoints.pointsize,
166 ax = [s.xaxis, s.yaxis],
167 radius = s.points.radius,
168 err = [s.points.xerr, s.points.yerr];
170 //sanity check, in case some inverted axis hack is applied to flot
172 if (ax[0].p2c(ax[0].max) < ax[0].p2c(ax[0].min)) {
174 var tmp = err[0].lowerCap;
175 err[0].lowerCap = err[0].upperCap;
176 err[0].upperCap = tmp;
180 if (ax[1].p2c(ax[1].min) < ax[1].p2c(ax[1].max)) {
182 var tmp = err[1].lowerCap;
183 err[1].lowerCap = err[1].upperCap;
184 err[1].upperCap = tmp;
187 for (var i = 0; i < s.datapoints.points.length; i += ps) {
190 var errRanges = parseErrors(s, i);
193 for (var e = 0; e < err.length; e++){
195 var minmax = [ax[e].min, ax[e].max];
198 if (errRanges[e * err.length]){
205 var upper = [x, y][e] + errRanges[e * err.length + 1],
206 lower = [x, y][e] - errRanges[e * err.length];
208 //points outside of the canvas
209 if (err[e].err == 'x')
210 if (y > ax[1].max || y < ax[1].min || upper < ax[0].min || lower > ax[0].max)
212 if (err[e].err == 'y')
213 if (x > ax[0].max || x < ax[0].min || upper < ax[1].min || lower > ax[1].max)
216 // prevent errorbars getting out of the canvas
217 var drawUpper = true,
220 if (upper > minmax[1]) {
224 if (lower < minmax[0]) {
229 //sanity check, in case some inverted axis hack is applied to flot
230 if ((err[e].err == 'x' && invertX) || (err[e].err == 'y' && invertY)) {
236 drawLower = drawUpper;
239 minmax[0] = minmax[1];
246 upper = ax[e].p2c(upper);
247 lower = ax[e].p2c(lower);
248 minmax[0] = ax[e].p2c(minmax[0]);
249 minmax[1] = ax[e].p2c(minmax[1]);
251 //same style as points by default
252 var lw = err[e].lineWidth ? err[e].lineWidth : s.points.lineWidth,
253 sw = s.points.shadowSize != null ? s.points.shadowSize : s.shadowSize;
255 //shadow as for points
256 if (lw > 0 && sw > 0) {
259 ctx.strokeStyle = "rgba(0,0,0,0.1)";
260 drawError(ctx, err[e], x, y, upper, lower, drawUpper, drawLower, radius, w + w/2, minmax);
262 ctx.strokeStyle = "rgba(0,0,0,0.2)";
263 drawError(ctx, err[e], x, y, upper, lower, drawUpper, drawLower, radius, w/2, minmax);
266 ctx.strokeStyle = err[e].color? err[e].color: s.color;
269 drawError(ctx, err[e], x, y, upper, lower, drawUpper, drawLower, radius, 0, minmax);
275 function drawError(ctx,err,x,y,upper,lower,drawUpper,drawLower,radius,offset,minmax){
282 // error bar - avoid plotting over circles
284 if (upper > x + radius) drawPath(ctx, [[upper,y],[Math.max(x + radius,minmax[0]),y]]);
285 else drawUpper = false;
286 if (lower < x - radius) drawPath(ctx, [[Math.min(x - radius,minmax[1]),y],[lower,y]] );
287 else drawLower = false;
290 if (upper < y - radius) drawPath(ctx, [[x,upper],[x,Math.min(y - radius,minmax[0])]] );
291 else drawUpper = false;
292 if (lower > y + radius) drawPath(ctx, [[x,Math.max(y + radius,minmax[1])],[x,lower]] );
293 else drawLower = false;
296 //internal radius value in errorbar, allows to plot radius 0 points and still keep proper sized caps
297 //this is a way to get errorbars on lines without visible connecting dots
298 radius = err.radius != null? err.radius: radius;
302 if (err.upperCap == '-'){
303 if (err.err=='x') drawPath(ctx, [[upper,y - radius],[upper,y + radius]] );
304 else drawPath(ctx, [[x - radius,upper],[x + radius,upper]] );
305 } else if ($.isFunction(err.upperCap)){
306 if (err.err=='x') err.upperCap(ctx, upper, y, radius);
307 else err.upperCap(ctx, x, upper, radius);
312 if (err.lowerCap == '-'){
313 if (err.err=='x') drawPath(ctx, [[lower,y - radius],[lower,y + radius]] );
314 else drawPath(ctx, [[x - radius,lower],[x + radius,lower]] );
315 } else if ($.isFunction(err.lowerCap)){
316 if (err.err=='x') err.lowerCap(ctx, lower, y, radius);
317 else err.lowerCap(ctx, x, lower, radius);
322 function drawPath(ctx, pts){
324 ctx.moveTo(pts[0][0], pts[0][1]);
325 for (var p=1; p < pts.length; p++)
326 ctx.lineTo(pts[p][0], pts[p][1]);
330 function draw(plot, ctx){
331 var plotOffset = plot.getPlotOffset();
334 ctx.translate(plotOffset.left, plotOffset.top);
335 $.each(plot.getData(), function (i, s) {
336 if (s.points.errorbars && (s.points.xerr.show || s.points.yerr.show))
337 drawSeriesErrors(plot, ctx, s);
342 function init(plot) {
343 plot.hooks.processRawData.push(processRawData);
344 plot.hooks.draw.push(draw);
347 $.plot.plugins.push({