How journalists can use Flot to turn numbers into visual stories

From building apps to backgrounding stories, reporters work with numerical data in all kinds of ways. It’s a practice that will no doubt increase in the future as more data becomes available all the time.

But as anyone who’s tried to work numbers into a story knows, it’s difficult to convey the meaning of too many numbers to people without a visual. Even a simple line chart can help in a city budget story, for instance, while more in-depth subjects like school report cards and our nation’s budget require charts if they are to be understood.

Interactivity can be a huge boon for understanding (though it should only be used when necessary, as it can quickly create clutter). Both of those examples were created with a JavaScript library called Flot, which makes it easier to plot data on charts. If you’re comfortable with CSS, HTML and a little jQuery, you should be able to create simple charts with Flot’s defaults fairly easily.

Flot is a powerful library. It comes with an assortment of plugins and can be extended to do a lot of different things. (For example, this chart uses Flot’s “fill between” plugin to create the color fill between the lines, and required a little hacking to get it to act just right when the lines crossed.) In this example, I’ll go over how to get started with the basics. I’m going to go through a couple of simple examples to show you how to use Flot, but first, let me explain how the code is set up. (You can grab the code in its entirety here.)

The HTML file has in its head several scripts. The first is excanvas.js. Because Flot relies on HTML5’s tag, older versions of Internet Explorer won’t display your chart without some help. Excanvas is a JavaScript script that mimics the canvas tag functionality for older browsers. You’ll notice it’s enclosed in comment tags so that it’s only applied for browsers that need it.

There are two excanvas files included with the Flot download. The version I’m using here is the minified one. “Minified” files have been run through an optimizer, which removes all whitespace and other unnecessary characters. This also makes the file nigh impossible for a human to read, so if you want to dive into how a script itself is written, look at the non-minified version.

Next, we have jQuery, included from the Google Libraries API, and then the Flot library itself. Lastly comes the Javascript file we’ve written to control what appears on our Flot chart. I’m calling it graph.js to keep things simple.

The body of this page is a single div:

<div style="width:300px;height:300px"></div>

This div must have 1.) an ID, and 2.) Inline CSS that defines its width and height (or Flot will hiccup). Our graph.js file will hold our data and plot it directly into this chart. So let’s go ahead and set that file up:

var $ = jQuery.noConflict();  $(document).ready(function(){  	var some_data = [];  	$.plot($("#graph"), [ some_data ]);  });

The first line ensures that we can use the $ to write our jQuery. Otherwise, it’s possible another JS script on the page will break our code.

The second line is a function that will run when the page is finished loading. Everything we’re going to write will go inside this function. The first thing inside it is our variable and the jQuery for plotting the data. This says, “Get the CSS element with the ‘graph’ ID and plot our variable’s values in it.”

The “magic” of Flot happens when you call the $.plot object. The simplest possible configuration for this is:

$.plot($("#id_of_graph_div"), [[30, 27], [41, 15]]);  // the bracketed numbers are your X and Y coordinates, respectively

I like to store my data in variables to make my code easier to read:

var some_data = [[30, 27], [41, 15]];  $.plot($("#id_of_graph_div"), [ some_data ]);

The $.plot object can become much more complex when you’re heavily customizing things, however. For reference, here are a few of the configuration options I use most.

Notice the information specific to the dataset goes within the square brackets, while the information that applies to the entire chart is in another set of curly braces. You can have a look at the complete set of options in Flot’s API docs.

For this and the following examples, I’m using some data on California teacher misassignment from 2009. (Basically, this is the number of teachers teaching subjects they aren’t authorized to teach in the lowest 3 percent of California schools.) I had this information in an Excel spreadsheet and did a little pivot table magic on it.

Then I ran it through my favorite data formatting tool, Mr. Data Converter. You can just copy and paste your data from Excel into the top box. Make sure to uncheck “First row is the header row” on the left, or you may end up missing your first row of data. For Flot, use the “JSON – Row Array” format.

First, a really simple example: the number of teachers per decile:

var some_data = [        [1,6152],        [2,3799],        [3,3011]  ];

Open graph.html in a browser, and voila!

But wait. That’s not a very accurate representation of our data. It makes it look like we have the number of misassignments at any given percentage of a decile. We don’t really know, for instance, that schools in the bottom 1.5 percentile had 5,000 misassignments.

To change the display of the graph, we need to change things up a little:

$.plot($("#graph"), [         {             data: some_data,             bars: { show: true }         }  ]);

So now, instead of just the “some_data” variable, we’ve got an array of variables. This is where Flot’s real power kicks in. The specific variable we’ve added here is an array itself. It allows you to specify points, bars, lines or a combination. While we’re at it, let’s get rid of the decimal points along the X axis, center the bars along their tick marks and add a legend. We’re going to need to do a little reformatting:

$.plot($("#graph"),  	[{ label: "Number of misassignments",      data: misassignments_per_decile }],      { series: {              points: {                  bars: true,                  barWidth: 5              }          },          xaxis: {              show: true,              ticks: 3,              min: 1,              max: 3,              tickDecimals: 0          },          yaxis: {              show: true,              ticks: 5,              min: 2000,              max: 7000          }      });

Not bad, but also not very interesting. I’ve written up one more example using something that might be a little more appealing. This next chart looks at the five subjects that had the most teacher misassignments in 2009 and plots them in the context of the previous six years. The variables look like this:

    var science = [[2009, 940], [2008, 446], [2007, 88], [2006, 93], [2005, 227], [2004, 122]];      var english = [[2009, 687], [2008, 790], [2007, 140],[2006, 340],[2005, 313],[2004, 192]];

I’ve added the code to the HTML page, so I can have both graphs on the same page. Here’s what the JavaScript object looks like:

$.plot($("#subjects"),              [                  { label: "Science",                  data: science },                  {  label: "English",                  data: english },                  { label: "Math",                  data: math },                  { label: "Social Studies",                  data: social_studies},                  { label: "ELD",                  data: eld }],              {                  xaxis: {                      tickDecimals: 0                  }              });

One of Flot’s most useful features is its tooltip. In this case, I think it would be handy to have some information displayed as you hover over the different points. So, add a comma after the X axis array, and then add the following code before the closing brackets (again, remember you can see all this code on GitHub):

grid: {          hoverable: true,          clickable: true  }

The tooltip is basically just a div that we will show and hide with jQuery. You can make the tooltip by putting this into your Javascript file:

function showTooltip(x, y, contents, color) {              $('  
' + contents + '
  ').css( {                  position: 'absolute',                  width: '140px',                  display: 'none',                  'font-family': 'sans-serif',                  'font-size': '12px',                  top: y + 5,                  left: x + 5,                  'border-width': '2px',                  'border-style': 'solid',                  'border-color': color,                  padding: '4px',                  'background-color': "#eee",                  opacity: 0.90              }).appendTo("body").fadeIn(200);          }

All this function does is create the data for drawing the tooltip. You can customize it to your whim. The only required rules are display: none, position: absolute, and the top and left values.

We’ll call the tooltip function in the next bit of code:

$("#subjects").bind("plothover", function (event, pos, item){               if (item) {                      if (previousPoint != item.dataIndex) {                          previousPoint = item.dataIndex;                            $("#tooltip").remove();                            var x = item.datapoint[0];                          var y = item.datapoint[1];                            var label = "In " + x + ", there were " + y + " misassigned teachers in " + item.series.label;                            showTooltip(item.pageX, item.pageY, label, item.series.color);                      }                  }                    else {                      $("#tooltip").remove();                      previousPoint = null;                  }          });

Take a look at the chart again. Not a bad start.

Once you’re feeling comfortable, have a dig through the Flot API and start playing with plugins. You can find some examples of what Flot is capable of here (though be forewarned, some of the example code is difficult to understand at first). Go forth and plot data.

This story is part of a Poynter Hacks/Hackers series featuring How To’s that focus on what journalists can learn from emerging trends in technology and new tech tools.