How to Create Timeplots

Getting Started

Here are a few easy steps to create a simple timeplot. Open up your favorite text or HTML editor and start creating an HTML file.

Step 1. Link to the API

In your HTML code, link to Timeplot's Javascript API code as follows:

<html>
  <head>
    ...
    <script src="http://static.simile.mit.edu/timeplot/api/1.0/timeplot-api.js" 
       type="text/javascript"></script>
    ...
  </head>
  <body>
    ...
  </body>
</html>

Step 2. Create a DIV Element

Create a div element in your HTML code, e.g.

<div id="my-timeplot" style="height: 150px;"></div>
You should give it an ID as well as fix its height.

Step 3. Call Timeplot.create()

Add two event handlers, onload and onresize, to the body element:

  <body onload="onLoad();" onresize="onResize();">
    ...
  </body>
Then write the following code in a script block or a separate Javascript file:
var timeplot;

function onLoad() {
  var plotInfo = [
    Timeplot.createPlotInfo({
      id: "plot1"
    })
  ];
            
  timeplot = Timeplot.create(document.getElementById("my-timeplot"), plotInfo);
}

var resizeTimerID = null;
function onResize() {
    if (resizeTimerID == null) {
        resizeTimerID = window.setTimeout(function() {
            resizeTimerID = null;
            timeplot.repaint();
        }, 100);
    }
}
Note that if we put the code to construct the timeplot in the onload handler to make sure that when we start to use Timeplot's API, all its code has been loaded. That code creates an empty timeplot, as the one here below.

Step 4. Add Data

In order for the timeplot to plot, we need to indicate where is the data. Timeplot supports loading time series data from plain text files with one event per row (but that could have multiple values as columns).

To add data to the timeplot, we need to create an EventSource and load it with data from the data file:

function onLoad() {
  var eventSource = new Timeplot.DefaultEventSource();
  var plotInfo = [
    Timeplot.createPlotInfo({
      id: "plot1",
      dataSource: new Timeplot.ColumnSource(eventSource,1)
    })
  ];
  
  timeplot = Timeplot.create(document.getElementById("my-timeplot"), plotInfo);
  timeplot.loadText("data.txt", ",", eventSource);
}
Note how timeplot loads the entire dataset in the eventSource and we instruct the timeplot to use a Timeplot.ColumnSource to extract the time series used to draw the plot (here, we want to draw the first column). The result is below.

Take a look at the data file. You can see that the column values are comma-separated and that the first column must be a time (using ISO 8601 format). Timeplot considers lines that start with '#' as comments and ignores them. Note that you have to tell the Timeplot.loadText() function which string separator it should use to parse the data file (in this case a ",").

Step 5. Tune the plot range

By default, Timeplot automatically scales the plot to maximally fit the available real estate on the page, but this behavior can be modified. In our plot, we know that our data is a percentage so we would like to have the y axis be from 0 to 100. In order to do this, we need to explicitly create a ValueGeometry:

  var plotInfo = [
    Timeplot.createPlotInfo({
      id: "plot1",
      dataSource: new Timeplot.ColumnSource(eventSource,1),
      valueGeometry: new Timeplot.DefaultValueGeometry({
        min: 0,
        max: 100
      })
    })
  ];
which yields the result:

Step 6. Enable the value grid

Sometimes, it's useful to have a visual grid to help readers establish the scale of the plot. In order to achieve this, it's enough to indicate the gridColor to the ValueGeometry:

  var plotInfo = [
    Timeplot.createPlotInfo({
      id: "plot1",
      dataSource: new Timeplot.ColumnSource(eventSource,1),
      valueGeometry: new Timeplot.DefaultValueGeometry({
        gridColor: "#000000",
        axisLabelsPlacement: "left",
        min: 0,
        max: 100
      })
    })
  ];
so now timeplot takes care of finding out the most appropriate grid division to keep avoid visual clutter:

Step 7. Add labels to the time axis

You can tell Timeplot to add labels to the time axis by configuring the TimeGeometry just like we just did for the ValueGeometry:

  var plotInfo = [
    Timeplot.createPlotInfo({
      id: "plot1",
      dataSource: new Timeplot.ColumnSource(eventSource,1),
      valueGeometry: new Timeplot.DefaultValueGeometry({
        gridColor: "#000000",
        axisLabelsPlacement: "left",
        min: 0,
        max: 100
      }),
      timeGeometry: new Timeplot.DefaultTimeGeometry({
        gridColor: "#000000",
        axisLabelsPlacement: "top"
      })
    })
  ];
which results in:

Step 8. Change the plot colors

You can configure the stroke and fill color of your plot by setting parameters of the PlotInfo:

  var plotInfo = [
    Timeplot.createPlotInfo({
      id: "plot1",
      dataSource: new Timeplot.ColumnSource(eventSource,1),
      valueGeometry: new Timeplot.DefaultValueGeometry({
        gridColor: "#000000",
        axisLabelsPlacement: "left",
        min: 0,
        max: 100
      }),
      timeGeometry: new Timeplot.DefaultTimeGeometry({
        gridColor: new Timeplot.Color("#000000"),
        axisLabelsPlacement: "top"
      }),      
      lineColor: "#ff0000",
      fillColor: "#cc8080"
    })
  ];
which results in:

Step 9. Show Plot values on Mouse over

You can configure the plot so that going over it with your mouse will visualize the actual time represented by that location in the plot and the value of the plot at that time:


  var plotInfo = [
    Timeplot.createPlotInfo({
      id: "plot1",
      dataSource: new Timeplot.ColumnSource(eventSource,1),
      valueGeometry: new Timeplot.DefaultValueGeometry({
        gridColor: "#000000",
        min: 0,
        max: 100
      }),
      timeGeometry: new Timeplot.DefaultTimeGeometry({
        gridColor: new Timeplot.Color("#000000"),
        axisLabelsPlacement: "top"
      }),
      lineColor: "#ff0000",
      fillColor: "#cc8080",
      showValues: true
    })
  ];
which results in:

Step 10. Adding another plot over the current one

You can draw multiple plots in the same timeplot, either using the same geometry of another one or not, depending on what you want to achieve. If two plots share the same geometry object, they will be drawn on the same 'range' of time or values. If not, each one will use their own scale. Here we want to plot another column from the same data source, using the same geometries for both time and values so that they all overlap:

  var timeGeometry = new Timeplot.DefaultTimeGeometry({
    gridColor: new Timeplot.Color("#000000"),
    axisLabelsPlacement: "top"
  });

  var valueGeometry = new Timeplot.DefaultValueGeometry({
    gridColor: "#000000",
    min: 0,
    max: 100
  });

  var plotInfo = [
    Timeplot.createPlotInfo({
      id: "plot1",
      dataSource: new Timeplot.ColumnSource(eventSource,1),
      timeGeometry: timeGeometry,
      valueGeometry: valueGeometry,
      lineColor: "#ff0000",
      fillColor: "#cc8080",
      showValues: true
    }),
    Timeplot.createPlotInfo({
      id: "plot2",
      dataSource: new Timeplot.ColumnSource(eventSource,3),
      timeGeometry: timeGeometry,
      valueGeometry: valueGeometry,
      lineColor: "#D0A825",
      showValues: true
    })
  ];
which results in:

Step 11. Overlaying events over the plots

Timeplot can load Timeline events and overlay the over plots. Here is how to do it and note how we keep using the same geometries for both the plots and the events:

  var eventSource2 = new Timeplot.DefaultEventSource();

  var plotInfo = [
    Timeplot.createPlotInfo({
      id: "plot1",
      dataSource: new Timeplot.ColumnSource(eventSource,1),
      timeGeometry: timeGeometry,
      valueGeometry: valueGeometry,
      lineColor: "#ff0000",
      fillColor: "#cc8080",
      showValues: true
    }),
    Timeplot.createPlotInfo({
      id: "plot2",
      dataSource: new Timeplot.ColumnSource(eventSource,3),
      timeGeometry: timeGeometry,
      valueGeometry: valueGeometry,
      lineColor: "#D0A825",
      showValues: true
    }),
    Timeplot.createPlotInfo({
      id: "plot3",
      timeGeometry: timeGeometry,
      eventSource: eventSource2,
      lineColor: "#03212E"
    
  ];
  
  timeplot = Timeplot.create(document.getElementById("my-timeplot"), plotInfo);
  timeplot.loadText("data.txt", ",", eventSource);
  timeplot.loadXML("events.xml", eventSource2);
which results in: