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://api.simile-widgets.org/timeplot/1.1/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); timeplots.loadXML("events.xml", eventSource2);which results in: