Flot Plugins – Easy Time Series Navigation

Over the last two summer breaks I have been working on projects that make use of the flot javascript plotting library.

Part of these projects required a bunch of extra functionality to be added to the standard flot release. I modulated some of the functionality in to flot plugins. By the end of my time playing around with flot I had a bunch of different plugins and have just made all of those public on github to stop them collecting dust!

Plugins developed (in order of interest):

Over a series of blog posts I am going to describe what each plugin is and how it works and hopefully it comes in use for people at some stage.

Easy Time Series Navigation

Github Code
Live Example

The first plugin I am going to explain is the easy time series navigation plugin. The code can be found on github here.

It is developed for use with time series navigation graphs. By that, I mean graphs that can be dragged forward and back in time by clicking and dragging the mouse. This dragging capability is added using the navigation plugin that is included with the standard flot package.

The plugin makes it to trivial to snap to a current range in time. A time range can be either: hour, day, week, month or year. Moving forward and back in time for the given time range is also possible. This is useful if say, we wanted to view the next or previous week from the current graph position.

Here is a screenshot of a flot graph showing latency over time between Maxnet and Auckland University. A single week is shown because I clicked the ‘now’ button. Clicking ‘Week>>’ or ‘<<week’ would move forward and back in time respectively.

Flot Time Snapping Functionality

The plugin just adds the functionality for flot to alter the xaxis position based on the given range and axis number. The actual UI controls are up to you to implement 🙂

There are four public functions added to the flot API to bind your buttons to. I am just going to copy and paste the documentation from the script itself here to explain those.

* This plugin adds four public functions to the flot API
* > nextRange, prevRange, now and snapTo
*
* Each of these function take two of the same parameters: range and xNum.
*
* xNum = the xaxis number (0, 1, 2, …)
* in most cases this will be 0 unless you have multiple xaxis’
*
* range = the time range for snapping.
* possible values are: hour, day, week, month or year
*
* eg.
* nextRange(“week”, 0) – will move the xaxis time range to
* one week in the future.
*
* now(“day”, 0) – will snap the time range to the start
* of the current day (midnight).
*/

The plugin does a bunch of funky time handling stuff that you won’t want to do yourself. The open source javascript date library, datejs, comes with some handy methods that make the code very clean.

Lets take snapping to a given year as an example. If it is not January then we need to move the time to the previous years January.  The Datejs ‘last’ method makes this trivial.

Then we need to move to the first day of January. There is conveniently a ‘moveToFirstDayOfMonth’ method. Finally, the end of the range needs to be one year after January 1st.

case "year":
  if (!startDate.is().january()) startDate.last().january();

  startDate.moveToFirstDayOfMonth().clearTime();
  end = 365 * MS_1DAY;
  break;

There are similar case blocks for the other range types. Then, the xaxis minimum value is set to the start date timestamp and the maximum is set to that value plus the end.

Note that it is possible to specify a time zone offset in the xaxis options.

// don't allow navigating beyond the current time
if (startDate.compareTo(new Date()) > 0) return { min: axis.min, max: axis.max  };

axis.min = startDate.getTime() + plot.getAxes().xaxis.options.tzOffset;
axis.max = axis.min + end;

plot.setupGrid();
plot.draw();

return { min: axis.min, max: axis.max };

Edit: I have added a basic example to show how the API could be included in your code. See the github examples folder.

Published by

oughton

Senior software engineer with extensive experience in enterprise software development targeting wholesale financial organisations and cloud solution providers.

6 thoughts on “Flot Plugins – Easy Time Series Navigation”

  1. So I came across your snap.js file while I was looking for a way to do exactly what you were doing in your example. I’m trying to integrate it into my website, but it isn’t quite working. Could you possibly email me/upload the code behind your UI example?

  2. currently digging into your example code…hard enough as a newbie to javascripting.
    however, I really like what you have done shown in the screenshot…would it be possible to add to github the GUI code Snap Range….? Would be great!
    Many thx in advance!

    Michael

  3. I’m looking for the ability to draw a very simple time-series heatmap with flot and came across your plugins. Have you documented your heatmap plugin anywhere or do I just need to read the code to figure out how to use it

    1. Hi Jeremy,

      Unfortunately I haven’t written a basic example for the heat map plugin and it is one of the less trivial ones to work out!

      Give it a read and a go, and let me know if you can’t work it out.

Leave a Reply

Your email address will not be published. Required fields are marked *