alchemy 1.0.0

data/vendor/assets/javascripts/alchemy/jquery/plugins/flot-0.7/API.txt

@@ -0,0 +1,1201 @@
+Flot Reference
+--------------
+
+Consider a call to the plot function:
+
+   var plot = $.plot(placeholder, data, options)
+
+The placeholder is a jQuery object or DOM element or jQuery expression
+that the plot will be put into. This placeholder needs to have its
+width and height set as explained in the README (go read that now if
+you haven't, it's short). The plot will modify some properties of the
+placeholder so it's recommended you simply pass in a div that you
+don't use for anything else. Make sure you check any fancy styling
+you apply to the div, e.g. background images have been reported to be a
+problem on IE 7.
+
+The format of the data is documented below, as is the available
+options. The plot object returned from the call has some methods you
+can call. These are documented separately below.
+
+Note that in general Flot gives no guarantees if you change any of the
+objects you pass in to the plot function or get out of it since
+they're not necessarily deep-copied.
+
+
+Data Format
+-----------
+
+The data is an array of data series:
+
+  [ series1, series2, ... ]
+
+A series can either be raw data or an object with properties. The raw
+data format is an array of points:
+
+  [ [x1, y1], [x2, y2], ... ]
+
+E.g.
+
+  [ [1, 3], [2, 14.01], [3.5, 3.14] ]
+
+Note that to simplify the internal logic in Flot both the x and y
+values must be numbers (even if specifying time series, see below for
+how to do this). This is a common problem because you might retrieve
+data from the database and serialize them directly to JSON without
+noticing the wrong type. If you're getting mysterious errors, double
+check that you're inputting numbers and not strings.
+
+If a null is specified as a point or if one of the coordinates is null
+or couldn't be converted to a number, the point is ignored when
+drawing. As a special case, a null value for lines is interpreted as a
+line segment end, i.e. the points before and after the null value are
+not connected.
+
+Lines and points take two coordinates. For filled lines and bars, you
+can specify a third coordinate which is the bottom of the filled
+area/bar (defaults to 0).
+
+The format of a single series object is as follows:
+
+  {
+    color: color or number
+    data: rawdata
+    label: string
+    lines: specific lines options
+    bars: specific bars options
+    points: specific points options
+    xaxis: number
+    yaxis: number
+    clickable: boolean
+    hoverable: boolean
+    shadowSize: number
+  }
+
+You don't have to specify any of them except the data, the rest are
+options that will get default values. Typically you'd only specify
+label and data, like this:
+
+  {
+    label: "y = 3",
+    data: [[0, 3], [10, 3]]
+  }
+
+The label is used for the legend, if you don't specify one, the series
+will not show up in the legend.
+
+If you don't specify color, the series will get a color from the
+auto-generated colors. The color is either a CSS color specification
+(like "rgb(255, 100, 123)") or an integer that specifies which of
+auto-generated colors to select, e.g. 0 will get color no. 0, etc.
+
+The latter is mostly useful if you let the user add and remove series,
+in which case you can hard-code the color index to prevent the colors
+from jumping around between the series.
+
+The "xaxis" and "yaxis" options specify which axis to use. The axes
+are numbered from 1 (default), so { yaxis: 2} means that the series
+should be plotted against the second y axis.
+
+"clickable" and "hoverable" can be set to false to disable
+interactivity for specific series if interactivity is turned on in
+the plot, see below.
+
+The rest of the options are all documented below as they are the same
+as the default options passed in via the options parameter in the plot
+commmand. When you specify them for a specific data series, they will
+override the default options for the plot for that data series.
+
+Here's a complete example of a simple data specification:
+
+  [ { label: "Foo", data: [ [10, 1], [17, -14], [30, 5] ] },
+    { label: "Bar", data: [ [11, 13], [19, 11], [30, -7] ] } ]
+
+
+Plot Options
+------------
+
+All options are completely optional. They are documented individually
+below, to change them you just specify them in an object, e.g.
+
+  var options = {
+    series: {
+      lines: { show: true },
+      points: { show: true }
+    }
+  };
+
+  $.plot(placeholder, data, options);
+
+
+Customizing the legend
+======================
+
+  legend: {
+    show: boolean
+    labelFormatter: null or (fn: string, series object -> string)
+    labelBoxBorderColor: color
+    noColumns: number
+    position: "ne" or "nw" or "se" or "sw"
+    margin: number of pixels or [x margin, y margin]
+    backgroundColor: null or color
+    backgroundOpacity: number between 0 and 1
+    container: null or jQuery object/DOM element/jQuery expression
+  }
+
+The legend is generated as a table with the data series labels and
+small label boxes with the color of the series. If you want to format
+the labels in some way, e.g. make them to links, you can pass in a
+function for "labelFormatter". Here's an example that makes them
+clickable:
+
+  labelFormatter: function(label, series) {
+    // series is the series object for the label
+    return '<a href="#' + label + '">' + label + '</a>';
+  }
+
+"noColumns" is the number of columns to divide the legend table into.
+"position" specifies the overall placement of the legend within the
+plot (top-right, top-left, etc.) and margin the distance to the plot
+edge (this can be either a number or an array of two numbers like [x,
+y]). "backgroundColor" and "backgroundOpacity" specifies the
+background. The default is a partly transparent auto-detected
+background.
+
+If you want the legend to appear somewhere else in the DOM, you can
+specify "container" as a jQuery object/expression to put the legend
+table into. The "position" and "margin" etc. options will then be
+ignored. Note that Flot will overwrite the contents of the container.
+
+
+Customizing the axes
+====================
+
+  xaxis, yaxis: {
+    show: null or true/false
+    position: "bottom" or "top" or "left" or "right"
+    mode: null or "time"
+
+    color: null or color spec
+    tickColor: null or color spec
+    
+    min: null or number
+    max: null or number
+    autoscaleMargin: null or number
+    
+    transform: null or fn: number -> number
+    inverseTransform: null or fn: number -> number
+    
+    ticks: null or number or ticks array or (fn: range -> ticks array)
+    tickSize: number or array
+    minTickSize: number or array
+    tickFormatter: (fn: number, object -> string) or string
+    tickDecimals: null or number
+
+    labelWidth: null or number
+    labelHeight: null or number
+    reserveSpace: null or true
+    
+    tickLength: null or number
+
+    alignTicksWithAxis: null or number
+  }
+
+All axes have the same kind of options. The following describes how to
+configure one axis, see below for what to do if you've got more than
+one x axis or y axis.
+
+If you don't set the "show" option (i.e. it is null), visibility is
+auto-detected, i.e. the axis will show up if there's data associated
+with it. You can override this by setting the "show" option to true or
+false.
+
+The "position" option specifies where the axis is placed, bottom or
+top for x axes, left or right for y axes. The "mode" option determines
+how the data is interpreted, the default of null means as decimal
+numbers. Use "time" for time series data, see the time series data
+section.
+
+The "color" option determines the color of the labels and ticks for
+the axis (default is the grid color). For more fine-grained control
+you can also set the color of the ticks separately with "tickColor"
+(otherwise it's autogenerated as the base color with some
+transparency).
+
+The options "min"/"max" are the precise minimum/maximum value on the
+scale. If you don't specify either of them, a value will automatically
+be chosen based on the minimum/maximum data values. Note that Flot
+always examines all the data values you feed to it, even if a
+restriction on another axis may make some of them invisible (this
+makes interactive use more stable).
+
+The "autoscaleMargin" is a bit esoteric: it's the fraction of margin
+that the scaling algorithm will add to avoid that the outermost points
+ends up on the grid border. Note that this margin is only applied when
+a min or max value is not explicitly set. If a margin is specified,
+the plot will furthermore extend the axis end-point to the nearest
+whole tick. The default value is "null" for the x axes and 0.02 for y
+axes which seems appropriate for most cases.
+
+"transform" and "inverseTransform" are callbacks you can put in to
+change the way the data is drawn. You can design a function to
+compress or expand certain parts of the axis non-linearly, e.g.
+suppress weekends or compress far away points with a logarithm or some
+other means. When Flot draws the plot, each value is first put through
+the transform function. Here's an example, the x axis can be turned
+into a natural logarithm axis with the following code:
+
+  xaxis: {
+    transform: function (v) { return Math.log(v); },
+    inverseTransform: function (v) { return Math.exp(v); }
+  }
+
+Similarly, for reversing the y axis so the values appear in inverse
+order:
+  
+  yaxis: {
+    transform: function (v) { return -v; },
+    inverseTransform: function (v) { return -v; }
+  }
+
+Note that for finding extrema, Flot assumes that the transform
+function does not reorder values (it should be monotone).
+
+The inverseTransform is simply the inverse of the transform function
+(so v == inverseTransform(transform(v)) for all relevant v). It is
+required for converting from canvas coordinates to data coordinates,
+e.g. for a mouse interaction where a certain pixel is clicked. If you
+don't use any interactive features of Flot, you may not need it.
+
+
+The rest of the options deal with the ticks.
+
+If you don't specify any ticks, a tick generator algorithm will make
+some for you. The algorithm has two passes. It first estimates how
+many ticks would be reasonable and uses this number to compute a nice
+round tick interval size. Then it generates the ticks.
+
+You can specify how many ticks the algorithm aims for by setting
+"ticks" to a number. The algorithm always tries to generate reasonably
+round tick values so even if you ask for three ticks, you might get
+five if that fits better with the rounding. If you don't want any
+ticks at all, set "ticks" to 0 or an empty array.
+
+Another option is to skip the rounding part and directly set the tick
+interval size with "tickSize". If you set it to 2, you'll get ticks at
+2, 4, 6, etc. Alternatively, you can specify that you just don't want
+ticks at a size less than a specific tick size with "minTickSize".
+Note that for time series, the format is an array like [2, "month"],
+see the next section.
+
+If you want to completely override the tick algorithm, you can specify
+an array for "ticks", either like this:
+
+  ticks: [0, 1.2, 2.4]
+
+Or like this where the labels are also customized:
+
+  ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]]
+
+You can mix the two if you like.
+  
+For extra flexibility you can specify a function as the "ticks"
+parameter. The function will be called with an object with the axis
+min and max and should return a ticks array. Here's a simplistic tick
+generator that spits out intervals of pi, suitable for use on the x
+axis for trigonometric functions:
+
+  function piTickGenerator(axis) {
+    var res = [], i = Math.floor(axis.min / Math.PI);
+    do {
+      var v = i * Math.PI;
+      res.push([v, i + "\u03c0"]);
+      ++i;
+    } while (v < axis.max);
+    
+    return res;
+  }
+
+You can control how the ticks look like with "tickDecimals", the
+number of decimals to display (default is auto-detected).
+
+Alternatively, for ultimate control over how ticks are formatted you can
+provide a function to "tickFormatter". The function is passed two
+parameters, the tick value and an axis object with information, and
+should return a string. The default formatter looks like this:
+
+  function formatter(val, axis) {
+    return val.toFixed(axis.tickDecimals);
+  }
+
+The axis object has "min" and "max" with the range of the axis,
+"tickDecimals" with the number of decimals to round the value to and
+"tickSize" with the size of the interval between ticks as calculated
+by the automatic axis scaling algorithm (or specified by you). Here's
+an example of a custom formatter:
+
+  function suffixFormatter(val, axis) {
+    if (val > 1000000)
+      return (val / 1000000).toFixed(axis.tickDecimals) + " MB";
+    else if (val > 1000)
+      return (val / 1000).toFixed(axis.tickDecimals) + " kB";
+    else
+      return val.toFixed(axis.tickDecimals) + " B";
+  }
+
+"labelWidth" and "labelHeight" specifies a fixed size of the tick
+labels in pixels. They're useful in case you need to align several
+plots. "reserveSpace" means that even if an axis isn't shown, Flot
+should reserve space for it - it is useful in combination with
+labelWidth and labelHeight for aligning multi-axis charts.
+
+"tickLength" is the length of the tick lines in pixels. By default, the
+innermost axes will have ticks that extend all across the plot, while
+any extra axes use small ticks. A value of null means use the default,
+while a number means small ticks of that length - set it to 0 to hide
+the lines completely.
+
+If you set "alignTicksWithAxis" to the number of another axis, e.g.
+alignTicksWithAxis: 1, Flot will ensure that the autogenerated ticks
+of this axis are aligned with the ticks of the other axis. This may
+improve the looks, e.g. if you have one y axis to the left and one to
+the right, because the grid lines will then match the ticks in both
+ends. The trade-off is that the forced ticks won't necessarily be at
+natural places.
+
+
+Multiple axes
+=============
+
+If you need more than one x axis or y axis, you need to specify for
+each data series which axis they are to use, as described under the
+format of the data series, e.g. { data: [...], yaxis: 2 } specifies
+that a series should be plotted against the second y axis.
+
+To actually configure that axis, you can't use the xaxis/yaxis options
+directly - instead there are two arrays in the options:
+
+   xaxes: []
+   yaxes: []
+
+Here's an example of configuring a single x axis and two y axes (we
+can leave options of the first y axis empty as the defaults are fine):
+
+  {
+    xaxes: [ { position: "top" } ],
+    yaxes: [ { }, { position: "right", min: 20 } ]
+  }
+
+The arrays get their default values from the xaxis/yaxis settings, so
+say you want to have all y axes start at zero, you can simply specify
+yaxis: { min: 0 } instead of adding a min parameter to all the axes.
+
+Generally, the various interfaces in Flot dealing with data points
+either accept an xaxis/yaxis parameter to specify which axis number to
+use (starting from 1), or lets you specify the coordinate directly as
+x2/x3/... or x2axis/x3axis/... instead of "x" or "xaxis".
+
+  
+Time series data
+================
+
+Time series are a bit more difficult than scalar data because
+calendars don't follow a simple base 10 system. For many cases, Flot
+abstracts most of this away, but it can still be a bit difficult to
+get the data into Flot. So we'll first discuss the data format.
+
+The time series support in Flot is based on Javascript timestamps,
+i.e. everywhere a time value is expected or handed over, a Javascript
+timestamp number is used. This is a number, not a Date object. A
+Javascript timestamp is the number of milliseconds since January 1,
+1970 00:00:00 UTC. This is almost the same as Unix timestamps, except it's
+in milliseconds, so remember to multiply by 1000!
+
+You can see a timestamp like this
+
+  alert((new Date()).getTime())
+
+Normally you want the timestamps to be displayed according to a
+certain time zone, usually the time zone in which the data has been
+produced. However, Flot always displays timestamps according to UTC.
+It has to as the only alternative with core Javascript is to interpret
+the timestamps according to the time zone that the visitor is in,
+which means that the ticks will shift unpredictably with the time zone
+and daylight savings of each visitor.
+
+So given that there's no good support for custom time zones in
+Javascript, you'll have to take care of this server-side.
+
+The easiest way to think about it is to pretend that the data
+production time zone is UTC, even if it isn't. So if you have a
+datapoint at 2002-02-20 08:00, you can generate a timestamp for eight
+o'clock UTC even if it really happened eight o'clock UTC+0200.
+
+In PHP you can get an appropriate timestamp with
+'strtotime("2002-02-20 UTC") * 1000', in Python with
+'calendar.timegm(datetime_object.timetuple()) * 1000', in .NET with
+something like:
+
+  public static int GetJavascriptTimestamp(System.DateTime input)
+  {
+    System.TimeSpan span = new System.TimeSpan(System.DateTime.Parse("1/1/1970").Ticks);
+    System.DateTime time = input.Subtract(span);
+    return (long)(time.Ticks / 10000);
+  }
+
+Javascript also has some support for parsing date strings, so it is
+possible to generate the timestamps manually client-side.
+
+If you've already got the real UTC timestamp, it's too late to use the
+pretend trick described above. But you can fix up the timestamps by
+adding the time zone offset, e.g. for UTC+0200 you would add 2 hours
+to the UTC timestamp you got. Then it'll look right on the plot. Most
+programming environments have some means of getting the timezone
+offset for a specific date (note that you need to get the offset for
+each individual timestamp to account for daylight savings).
+
+Once you've gotten the timestamps into the data and specified "time"
+as the axis mode, Flot will automatically generate relevant ticks and
+format them. As always, you can tweak the ticks via the "ticks" option
+- just remember that the values should be timestamps (numbers), not
+Date objects.
+
+Tick generation and formatting can also be controlled separately
+through the following axis options:
+
+  minTickSize: array
+  timeformat: null or format string
+  monthNames: null or array of size 12 of strings
+  twelveHourClock: boolean
+
+Here "timeformat" is a format string to use. You might use it like
+this:
+
+  xaxis: {
+    mode: "time"
+    timeformat: "%y/%m/%d"
+  }
+  
+This will result in tick labels like "2000/12/24". The following
+specifiers are supported
+
+  %h: hours
+  %H: hours (left-padded with a zero)
+  %M: minutes (left-padded with a zero)
+  %S: seconds (left-padded with a zero)
+  %d: day of month (1-31), use %0d for zero-padding
+  %m: month (1-12), use %0m for zero-padding
+  %y: year (four digits)
+  %b: month name (customizable)
+  %p: am/pm, additionally switches %h/%H to 12 hour instead of 24
+  %P: AM/PM (uppercase version of %p)
+
+Inserting a zero like %0m or %0d means that the specifier will be
+left-padded with a zero if it's only single-digit. So %y-%0m-%0d
+results in unambigious ISO timestamps like 2007-05-10 (for May 10th).
+
+You can customize the month names with the "monthNames" option. For
+instance, for Danish you might specify:
+
+  monthNames: ["jan", "feb", "mar", "apr", "maj", "jun", "jul", "aug", "sep", "okt", "nov", "dec"]
+
+If you set "twelveHourClock" to true, the autogenerated timestamps
+will use 12 hour AM/PM timestamps instead of 24 hour.
+  
+The format string and month names are used by a very simple built-in
+format function that takes a date object, a format string (and
+optionally an array of month names) and returns the formatted string.
+If needed, you can access it as $.plot.formatDate(date, formatstring,
+monthNames) or even replace it with another more advanced function
+from a date library if you're feeling adventurous.
+
+If everything else fails, you can control the formatting by specifying
+a custom tick formatter function as usual. Here's a simple example
+which will format December 24 as 24/12:
+
+  tickFormatter: function (val, axis) {
+    var d = new Date(val);
+    return d.getUTCDate() + "/" + (d.getUTCMonth() + 1);
+  }
+
+Note that for the time mode "tickSize" and "minTickSize" are a bit
+special in that they are arrays on the form "[value, unit]" where unit
+is one of "second", "minute", "hour", "day", "month" and "year". So
+you can specify
+
+  minTickSize: [1, "month"]
+
+to get a tick interval size of at least 1 month and correspondingly,
+if axis.tickSize is [2, "day"] in the tick formatter, the ticks have
+been produced with two days in-between.
+
+
+
+Customizing the data series
+===========================
+
+  series: {
+    lines, points, bars: {
+      show: boolean
+      lineWidth: number
+      fill: boolean or number
+      fillColor: null or color/gradient
+    }
+
+    points: {
+      radius: number
+      symbol: "circle" or function
+    }
+
+    bars: {
+      barWidth: number
+      align: "left" or "center"
+      horizontal: boolean
+    }
+
+    lines: {
+      steps: boolean
+    }
+
+    shadowSize: number
+  }
+  
+  colors: [ color1, color2, ... ]
+
+The options inside "series: {}" are copied to each of the series. So
+you can specify that all series should have bars by putting it in the
+global options, or override it for individual series by specifying
+bars in a particular the series object in the array of data.
+  
+The most important options are "lines", "points" and "bars" that
+specify whether and how lines, points and bars should be shown for
+each data series. In case you don't specify anything at all, Flot will
+default to showing lines (you can turn this off with
+lines: { show: false }). You can specify the various types
+independently of each other, and Flot will happily draw each of them
+in turn (this is probably only useful for lines and points), e.g.
+
+  var options = {
+    series: {
+      lines: { show: true, fill: true, fillColor: "rgba(255, 255, 255, 0.8)" },
+      points: { show: true, fill: false }
+    }
+  };
+
+"lineWidth" is the thickness of the line or outline in pixels. You can
+set it to 0 to prevent a line or outline from being drawn; this will
+also hide the shadow.
+
+"fill" is whether the shape should be filled. For lines, this produces
+area graphs. You can use "fillColor" to specify the color of the fill.
+If "fillColor" evaluates to false (default for everything except
+points which are filled with white), the fill color is auto-set to the
+color of the data series. You can adjust the opacity of the fill by
+setting fill to a number between 0 (fully transparent) and 1 (fully
+opaque).
+
+For bars, fillColor can be a gradient, see the gradient documentation
+below. "barWidth" is the width of the bars in units of the x axis (or
+the y axis if "horizontal" is true), contrary to most other measures
+that are specified in pixels. For instance, for time series the unit
+is milliseconds so 24 * 60 * 60 * 1000 produces bars with the width of
+a day. "align" specifies whether a bar should be left-aligned
+(default) or centered on top of the value it represents. When
+"horizontal" is on, the bars are drawn horizontally, i.e. from the y
+axis instead of the x axis; note that the bar end points are still
+defined in the same way so you'll probably want to swap the
+coordinates if you've been plotting vertical bars first.
+
+For lines, "steps" specifies whether two adjacent data points are
+connected with a straight (possibly diagonal) line or with first a
+horizontal and then a vertical line. Note that this transforms the
+data by adding extra points.
+
+For points, you can specify the radius and the symbol. The only
+built-in symbol type is circles, for other types you can use a plugin
+or define them yourself by specifying a callback:
+
+  function cross(ctx, x, y, radius, shadow) {
+      var size = radius * Math.sqrt(Math.PI) / 2;
+      ctx.moveTo(x - size, y - size);
+      ctx.lineTo(x + size, y + size);
+      ctx.moveTo(x - size, y + size);
+      ctx.lineTo(x + size, y - size);
+  }
+
+The parameters are the drawing context, x and y coordinates of the
+center of the point, a radius which corresponds to what the circle
+would have used and whether the call is to draw a shadow (due to
+limited canvas support, shadows are currently faked through extra
+draws). It's good practice to ensure that the area covered by the
+symbol is the same as for the circle with the given radius, this
+ensures that all symbols have approximately the same visual weight.
+
+"shadowSize" is the default size of shadows in pixels. Set it to 0 to
+remove shadows.
+
+The "colors" array specifies a default color theme to get colors for
+the data series from. You can specify as many colors as you like, like
+this:
+
+  colors: ["#d18b2c", "#dba255", "#919733"]
+
+If there are more data series than colors, Flot will try to generate
+extra colors by lightening and darkening colors in the theme.
+
+
+Customizing the grid
+====================
+
+  grid: {
+    show: boolean
+    aboveData: boolean
+    color: color
+    backgroundColor: color/gradient or null
+    labelMargin: number
+    axisMargin: number
+    markings: array of markings or (fn: axes -> array of markings)
+    borderWidth: number
+    borderColor: color or null
+    minBorderMargin: number or null
+    clickable: boolean
+    hoverable: boolean
+    autoHighlight: boolean
+    mouseActiveRadius: number
+  }
+
+The grid is the thing with the axes and a number of ticks. Many of the
+things in the grid are configured under the individual axes, but not
+all. "color" is the color of the grid itself whereas "backgroundColor"
+specifies the background color inside the grid area, here null means
+that the background is transparent. You can also set a gradient, see
+the gradient documentation below.
+
+You can turn off the whole grid including tick labels by setting
+"show" to false. "aboveData" determines whether the grid is drawn
+above the data or below (below is default).
+
+"labelMargin" is the space in pixels between tick labels and axis
+line, and "axisMargin" is the space in pixels between axes when there
+are two next to each other. Note that you can style the tick labels
+with CSS, e.g. to change the color. They have class "tickLabel".
+
+"borderWidth" is the width of the border around the plot. Set it to 0
+to disable the border. You can also set "borderColor" if you want the
+border to have a different color than the grid lines.
+"minBorderMargin" controls the default minimum margin around the
+border - it's used to make sure that points aren't accidentally
+clipped by the canvas edge so by default the value is computed from
+the point radius.
+
+"markings" is used to draw simple lines and rectangular areas in the
+background of the plot. You can either specify an array of ranges on
+the form { xaxis: { from, to }, yaxis: { from, to } } (with multiple
+axes, you can specify coordinates for other axes instead, e.g. as
+x2axis/x3axis/...) or with a function that returns such an array given
+the axes for the plot in an object as the first parameter.
+
+You can set the color of markings by specifying "color" in the ranges
+object. Here's an example array:
+
+  markings: [ { xaxis: { from: 0, to: 2 }, yaxis: { from: 10, to: 10 }, color: "#bb0000" }, ... ]
+
+If you leave out one of the values, that value is assumed to go to the
+border of the plot. So for example if you only specify { xaxis: {
+from: 0, to: 2 } } it means an area that extends from the top to the
+bottom of the plot in the x range 0-2.
+
+A line is drawn if from and to are the same, e.g.
+
+  markings: [ { yaxis: { from: 1, to: 1 } }, ... ]
+
+would draw a line parallel to the x axis at y = 1. You can control the
+line width with "lineWidth" in the range object.
+
+An example function that makes vertical stripes might look like this:
+
+  markings: function (axes) {
+    var markings = [];
+    for (var x = Math.floor(axes.xaxis.min); x < axes.xaxis.max; x += 2)
+      markings.push({ xaxis: { from: x, to: x + 1 } });
+    return markings;
+  }
+
+
+If you set "clickable" to true, the plot will listen for click events
+on the plot area and fire a "plotclick" event on the placeholder with
+a position and a nearby data item object as parameters. The coordinates
+are available both in the unit of the axes (not in pixels) and in
+global screen coordinates.
+
+Likewise, if you set "hoverable" to true, the plot will listen for
+mouse move events on the plot area and fire a "plothover" event with
+the same parameters as the "plotclick" event. If "autoHighlight" is
+true (the default), nearby data items are highlighted automatically.
+If needed, you can disable highlighting and control it yourself with
+the highlight/unhighlight plot methods described elsewhere.
+
+You can use "plotclick" and "plothover" events like this:
+
+    $.plot($("#placeholder"), [ d ], { grid: { clickable: true } });
+
+    $("#placeholder").bind("plotclick", function (event, pos, item) {
+        alert("You clicked at " + pos.x + ", " + pos.y);
+        // axis coordinates for other axes, if present, are in pos.x2, pos.x3, ...
+        // if you need global screen coordinates, they are pos.pageX, pos.pageY
+
+        if (item) {
+          highlight(item.series, item.datapoint);
+          alert("You clicked a point!");
+        }
+    });
+
+The item object in this example is either null or a nearby object on the form:
+
+  item: {
+      datapoint: the point, e.g. [0, 2]
+      dataIndex: the index of the point in the data array
+      series: the series object
+      seriesIndex: the index of the series
+      pageX, pageY: the global screen coordinates of the point
+  }
+
+For instance, if you have specified the data like this 
+
+    $.plot($("#placeholder"), [ { label: "Foo", data: [[0, 10], [7, 3]] } ], ...);
+
+and the mouse is near the point (7, 3), "datapoint" is [7, 3],
+"dataIndex" will be 1, "series" is a normalized series object with
+among other things the "Foo" label in series.label and the color in
+series.color, and "seriesIndex" is 0. Note that plugins and options
+that transform the data can shift the indexes from what you specified
+in the original data array.
+
+If you use the above events to update some other information and want
+to clear out that info in case the mouse goes away, you'll probably
+also need to listen to "mouseout" events on the placeholder div.
+
+"mouseActiveRadius" specifies how far the mouse can be from an item
+and still activate it. If there are two or more points within this
+radius, Flot chooses the closest item. For bars, the top-most bar
+(from the latest specified data series) is chosen.
+
+If you want to disable interactivity for a specific data series, you
+can set "hoverable" and "clickable" to false in the options for that
+series, like this { data: [...], label: "Foo", clickable: false }.
+
+
+Specifying gradients
+====================
+
+A gradient is specified like this:
+
+  { colors: [ color1, color2, ... ] }
+
+For instance, you might specify a background on the grid going from
+black to gray like this:
+
+  grid: {
+    backgroundColor: { colors: ["#000", "#999"] }
+  }
+
+For the series you can specify the gradient as an object that
+specifies the scaling of the brightness and the opacity of the series
+color, e.g.
+
+  { colors: [{ opacity: 0.8 }, { brightness: 0.6, opacity: 0.8 } ] }
+
+where the first color simply has its alpha scaled, whereas the second
+is also darkened. For instance, for bars the following makes the bars
+gradually disappear, without outline:
+
+  bars: {
+      show: true,
+      lineWidth: 0,
+      fill: true,
+      fillColor: { colors: [ { opacity: 0.8 }, { opacity: 0.1 } ] }
+  }
+  
+Flot currently only supports vertical gradients drawn from top to
+bottom because that's what works with IE.
+
+
+Plot Methods
+------------
+
+The Plot object returned from the plot function has some methods you
+can call:
+
+  - highlight(series, datapoint)
+
+    Highlight a specific datapoint in the data series. You can either
+    specify the actual objects, e.g. if you got them from a
+    "plotclick" event, or you can specify the indices, e.g.
+    highlight(1, 3) to highlight the fourth point in the second series
+    (remember, zero-based indexing).
+
+  
+  - unhighlight(series, datapoint) or unhighlight()
+
+    Remove the highlighting of the point, same parameters as
+    highlight.
+
+    If you call unhighlight with no parameters, e.g. as
+    plot.unhighlight(), all current highlights are removed.
+
+
+  - setData(data)
+
+    You can use this to reset the data used. Note that axis scaling,
+    ticks, legend etc. will not be recomputed (use setupGrid() to do
+    that). You'll probably want to call draw() afterwards.
+
+    You can use this function to speed up redrawing a small plot if
+    you know that the axes won't change. Put in the new data with
+    setData(newdata), call draw(), and you're good to go. Note that
+    for large datasets, almost all the time is consumed in draw()
+    plotting the data so in this case don't bother.
+
+    
+  - setupGrid()
+
+    Recalculate and set axis scaling, ticks, legend etc.
+
+    Note that because of the drawing model of the canvas, this
+    function will immediately redraw (actually reinsert in the DOM)
+    the labels and the legend, but not the actual tick lines because
+    they're drawn on the canvas. You need to call draw() to get the
+    canvas redrawn.
+    
+  - draw()
+
+    Redraws the plot canvas.
+
+  - triggerRedrawOverlay()
+
+    Schedules an update of an overlay canvas used for drawing
+    interactive things like a selection and point highlights. This
+    is mostly useful for writing plugins. The redraw doesn't happen
+    immediately, instead a timer is set to catch multiple successive
+    redraws (e.g. from a mousemove). You can get to the overlay by
+    setting up a drawOverlay hook.
+
+  - width()/height()
+
+    Gets the width and height of the plotting area inside the grid.
+    This is smaller than the canvas or placeholder dimensions as some
+    extra space is needed (e.g. for labels).
+
+  - offset()
+
+    Returns the offset of the plotting area inside the grid relative
+    to the document, useful for instance for calculating mouse
+    positions (event.pageX/Y minus this offset is the pixel position
+    inside the plot).
+
+  - pointOffset({ x: xpos, y: ypos })
+
+    Returns the calculated offset of the data point at (x, y) in data
+    space within the placeholder div. If you are working with multiple axes, you
+    can specify the x and y axis references, e.g. 
+
+      o = pointOffset({ x: xpos, y: ypos, xaxis: 2, yaxis: 3 })
+      // o.left and o.top now contains the offset within the div
+
+  - resize()
+
+    Tells Flot to resize the drawing canvas to the size of the
+    placeholder. You need to run setupGrid() and draw() afterwards as
+    canvas resizing is a destructive operation. This is used
+    internally by the resize plugin.
+
+  - shutdown()
+
+    Cleans up any event handlers Flot has currently registered. This
+    is used internally.
+
+
+There are also some members that let you peek inside the internal
+workings of Flot which is useful in some cases. Note that if you change
+something in the objects returned, you're changing the objects used by
+Flot to keep track of its state, so be careful.
+
+  - getData()
+
+    Returns an array of the data series currently used in normalized
+    form with missing settings filled in according to the global
+    options. So for instance to find out what color Flot has assigned
+    to the data series, you could do this:
+
+      var series = plot.getData();
+      for (var i = 0; i < series.length; ++i)
+        alert(series[i].color);
+
+    A notable other interesting field besides color is datapoints
+    which has a field "points" with the normalized data points in a
+    flat array (the field "pointsize" is the increment in the flat
+    array to get to the next point so for a dataset consisting only of
+    (x,y) pairs it would be 2).
+
+  - getAxes()
+
+    Gets an object with the axes. The axes are returned as the
+    attributes of the object, so for instance getAxes().xaxis is the
+    x axis.
+
+    Various things are stuffed inside an axis object, e.g. you could
+    use getAxes().xaxis.ticks to find out what the ticks are for the
+    xaxis. Two other useful attributes are p2c and c2p, functions for
+    transforming from data point space to the canvas plot space and
+    back. Both returns values that are offset with the plot offset.
+    Check the Flot source code for the complete set of attributes (or
+    output an axis with console.log() and inspect it).
+
+    With multiple axes, the extra axes are returned as x2axis, x3axis,
+    etc., e.g. getAxes().y2axis is the second y axis. You can check
+    y2axis.used to see whether the axis is associated with any data
+    points and y2axis.show to see if it is currently shown. 
+ 
+  - getPlaceholder()
+
+    Returns placeholder that the plot was put into. This can be useful
+    for plugins for adding DOM elements or firing events.
+
+  - getCanvas()
+
+    Returns the canvas used for drawing in case you need to hack on it
+    yourself. You'll probably need to get the plot offset too.
+  
+  - getPlotOffset()
+
+    Gets the offset that the grid has within the canvas as an object
+    with distances from the canvas edges as "left", "right", "top",
+    "bottom". I.e., if you draw a circle on the canvas with the center
+    placed at (left, top), its center will be at the top-most, left
+    corner of the grid.
+
+  - getOptions()
+
+    Gets the options for the plot, normalized, with default values
+    filled in. You get a reference to actual values used by Flot, so
+    if you modify the values in here, Flot will use the new values.
+    If you change something, you probably have to call draw() or
+    setupGrid() or triggerRedrawOverlay() to see the change.
+    
+
+Hooks
+=====
+
+In addition to the public methods, the Plot object also has some hooks
+that can be used to modify the plotting process. You can install a
+callback function at various points in the process, the function then
+gets access to the internal data structures in Flot.
+
+Here's an overview of the phases Flot goes through:
+
+  1. Plugin initialization, parsing options
+  
+  2. Constructing the canvases used for drawing
+
+  3. Set data: parsing data specification, calculating colors,
+     copying raw data points into internal format,
+     normalizing them, finding max/min for axis auto-scaling
+
+  4. Grid setup: calculating axis spacing, ticks, inserting tick
+     labels, the legend
+
+  5. Draw: drawing the grid, drawing each of the series in turn
+
+  6. Setting up event handling for interactive features
+
+  7. Responding to events, if any
+
+  8. Shutdown: this mostly happens in case a plot is overwritten 
+
+Each hook is simply a function which is put in the appropriate array.
+You can add them through the "hooks" option, and they are also available
+after the plot is constructed as the "hooks" attribute on the returned
+plot object, e.g.
+
+  // define a simple draw hook
+  function hellohook(plot, canvascontext) { alert("hello!"); };
+
+  // pass it in, in an array since we might want to specify several
+  var plot = $.plot(placeholder, data, { hooks: { draw: [hellohook] } });
+
+  // we can now find it again in plot.hooks.draw[0] unless a plugin
+  // has added other hooks
+
+The available hooks are described below. All hook callbacks get the
+plot object as first parameter. You can find some examples of defined
+hooks in the plugins bundled with Flot.
+
+ - processOptions  [phase 1]
+
+   function(plot, options)
+   
+   Called after Flot has parsed and merged options. Useful in the
+   instance where customizations beyond simple merging of default
+   values is needed. A plugin might use it to detect that it has been
+   enabled and then turn on or off other options.
+
+ 
+ - processRawData  [phase 3]
+
+   function(plot, series, data, datapoints)
+ 
+   Called before Flot copies and normalizes the raw data for the given
+   series. If the function fills in datapoints.points with normalized
+   points and sets datapoints.pointsize to the size of the points,
+   Flot will skip the copying/normalization step for this series.
+   
+   In any case, you might be interested in setting datapoints.format,
+   an array of objects for specifying how a point is normalized and
+   how it interferes with axis scaling.
+
+   The default format array for points is something along the lines of:
+
+     [
+       { x: true, number: true, required: true },
+       { y: true, number: true, required: true }
+     ]
+
+   The first object means that for the first coordinate it should be
+   taken into account when scaling the x axis, that it must be a
+   number, and that it is required - so if it is null or cannot be
+   converted to a number, the whole point will be zeroed out with
+   nulls. Beyond these you can also specify "defaultValue", a value to
+   use if the coordinate is null. This is for instance handy for bars
+   where one can omit the third coordinate (the bottom of the bar)
+   which then defaults to 0.
+
+
+ - processDatapoints  [phase 3]
+
+   function(plot, series, datapoints)
+ 
+   Called after normalization of the given series but before finding
+   min/max of the data points. This hook is useful for implementing data
+   transformations. "datapoints" contains the normalized data points in
+   a flat array as datapoints.points with the size of a single point
+   given in datapoints.pointsize. Here's a simple transform that
+   multiplies all y coordinates by 2:
+
+     function multiply(plot, series, datapoints) {
+         var points = datapoints.points, ps = datapoints.pointsize;
+         for (var i = 0; i < points.length; i += ps)
+             points[i + 1] *= 2;
+     }
+
+   Note that you must leave datapoints in a good condition as Flot
+   doesn't check it or do any normalization on it afterwards.
+
+
+ - drawSeries  [phase 5]
+
+   function(plot, canvascontext, series)
+
+   Hook for custom drawing of a single series. Called just before the
+   standard drawing routine has been called in the loop that draws
+   each series.
+   
+ 
+ - draw  [phase 5]
+
+   function(plot, canvascontext)
+ 
+   Hook for drawing on the canvas. Called after the grid is drawn
+   (unless it's disabled or grid.aboveData is set) and the series have
+   been plotted (in case any points, lines or bars have been turned
+   on). For examples of how to draw things, look at the source code.
+   
+ 
+ - bindEvents  [phase 6]
+
+   function(plot, eventHolder)
+
+   Called after Flot has setup its event handlers. Should set any
+   necessary event handlers on eventHolder, a jQuery object with the
+   canvas, e.g.
+
+     function (plot, eventHolder) {
+         eventHolder.mousedown(function (e) {
+             alert("You pressed the mouse at " + e.pageX + " " + e.pageY);
+         });
+     }
+
+   Interesting events include click, mousemove, mouseup/down. You can
+   use all jQuery events. Usually, the event handlers will update the
+   state by drawing something (add a drawOverlay hook and call
+   triggerRedrawOverlay) or firing an externally visible event for
+   user code. See the crosshair plugin for an example.
+     
+   Currently, eventHolder actually contains both the static canvas
+   used for the plot itself and the overlay canvas used for
+   interactive features because some versions of IE get the stacking
+   order wrong. The hook only gets one event, though (either for the
+   overlay or for the static canvas).
+
+   Note that custom plot events generated by Flot are not generated on
+   eventHolder, but on the div placeholder supplied as the first
+   argument to the plot call. You can get that with
+   plot.getPlaceholder() - that's probably also the one you should use
+   if you need to fire a custom event.
+
+
+ - drawOverlay  [phase 7]
+
+   function (plot, canvascontext)
+
+   The drawOverlay hook is used for interactive things that need a
+   canvas to draw on. The model currently used by Flot works the way
+   that an extra overlay canvas is positioned on top of the static
+   canvas. This overlay is cleared and then completely redrawn
+   whenever something interesting happens. This hook is called when
+   the overlay canvas is to be redrawn.
+
+   "canvascontext" is the 2D context of the overlay canvas. You can
+   use this to draw things. You'll most likely need some of the
+   metrics computed by Flot, e.g. plot.width()/plot.height(). See the
+   crosshair plugin for an example.
+
+
+ - shutdown  [phase 8]
+
+   function (plot, eventHolder)
+
+   Run when plot.shutdown() is called, which usually only happens in
+   case a plot is overwritten by a new plot. If you're writing a
+   plugin that adds extra DOM elements or event handlers, you should
+   add a callback to clean up after you. Take a look at the section in
+   PLUGINS.txt for more info.
+
+   
+Plugins
+-------
+
+Plugins extend the functionality of Flot. To use a plugin, simply
+include its Javascript file after Flot in the HTML page.
+
+If you're worried about download size/latency, you can concatenate all
+the plugins you use, and Flot itself for that matter, into one big file
+(make sure you get the order right), then optionally run it through a
+Javascript minifier such as YUI Compressor.
+
+Here's a brief explanation of how the plugin plumbings work:
+
+Each plugin registers itself in the global array $.plot.plugins. When
+you make a new plot object with $.plot, Flot goes through this array
+calling the "init" function of each plugin and merging default options
+from the "option" attribute of the plugin. The init function gets a
+reference to the plot object created and uses this to register hooks
+and add new public methods if needed.
+
+See the PLUGINS.txt file for details on how to write a plugin. As the
+above description hints, it's actually pretty easy.
+
+
+Version number
+--------------
+
+The version number of Flot is available in $.plot.version.