humble software development

About

HumbleFinance is an HTML5 data visualization tool similar to the Flash tool on http://finance.google.com/. The tool is written entirely in JavaScript, using the Prototype and Flotr libraries.

Though this tool lends itself well to the display of financial data, it can be used to display any two 2d data sets which share an axis. Please write me with any neat examples of data.

Requirements

Prototype 1.6.1+ (http://prototypejs.org/)
Flotr 2.0 (modified)
FireFox, Safari, Chromium, or IE6+

Note: performance depends on browser, processor, and data size. For best results, avoid IE :-)

Installation

To install HumbleFinance, copy HumbleFinance.js to your JavaScript folder and include the file in your web page.

<script type="text/javascript" src="path/to/source/HumbleFinance.js"></script>

Usage

Using HumbleFinance requires three steps. First create a div for HumbleFinance to live in and give it an id, for example <div id="financeID">. Second, build some data and store it in JavaScript variables. Finally, call the HumbleFinance init function.

Data:

HumbleFinance can be used to display any two 2d sets of numeric data which share an axis. All data is should be stored within JavaScript variables as an array of [x, y] points.

var data = [[0, 1],[1, 1],[1, 0]];

In total, three data parameters must be set:

priceData
volumeData
summaryData

The first two are the two sets sharing an axis. The third, summaryData, is a set which will be displayed all at once, used to provide a useful visual cue for interacting with the other data. This set must also share the same axis and should span the range of the other two sets. In general it will be a summary, 100 or so points, from either priceData or volumeData.

For example, from the demo:

priceData is stock closing price vs. time
volumeData is stock volume traded vs. time
summaryData is 100 points from priceData

Init:

To display the tool, call HumbleFinance.init. This function takes four parameters:

id - container div id.
priceData - the first set of data.
volumeData - the second set of data.
summaryData - the set of summary data.

This function must be called after the container div element has been loaded, preferably after the entire DOM has been loaded. This can be done using Prototype as follows:

Event.observe(document, 'dom:loaded', function() {
    HumbleFinance.init('financeID', priceData, volumeData, summaryData);
});

Extension

HumbleFinance was written to provide three basic methods extendibility: Flotr events, tick and track formatters, and a zoom function. Each of these techniques is used in the demo (this is by design, not my own laziness or short-sightedness, as this is a small library). Additionally, this software is under the MIT License so you can alter and adulter HumbleFinance manually to suit your needs.

Flotr Events

After the init function has been called, Flotr event observers can be attached to the HumbleFinance.containers to provide additional functionality. For documentation on specific Flotr events, consult the Flotr documentation and source code.

The following example watches the summary chart for selection changes and updates a div with the id dateRange, displaying the date range of the selection. This example uses an extra set of metadata stored in the variable jsonData, a good method for attaching richer or non-numeric data to points on the graphs.

Event.observe(HumbleFinance.containers.summary, 'flotr:select', function (e) {
        
    var area = e.memo[0];
    xmin = Math.floor(area.x1);
    xmax = Math.ceil(area.x2);
    
    var date1 = jsonData[xmin].date;
    var date2 = jsonData[xmax].date;
    
    $('dateRange').update(jsonData[xmin].date + ' - ' + jsonData[xmax].date);
});

Tick and Track Formatters

HumbleFinance uses two tick formatters and one track formatter. These are functions which format the data displayed along axis ticks or, in the case of the track formatter, data displayed when a data point is moused over. For specific details regarding formatters consult the Flotr documentation and source code.

The following example sets the mouse track formatter. This displays the date, price, and volume traded of the stock at the point selected again pulling data from jsonData.

HumbleFinance.trackFormatter = function (obj) {
    
    var x = Math.floor(obj.x);
    var data = jsonData[x];
    var text = data.date + " Price: " + data.close + " Vol: " + data.volume;
    
    return text;
};

Zooming

A zoom function, HumbleFinance.zoom, lets you manually select a section of the of the summary. It accepts one parameter, the length of the range to be selected. Selection starts either at the right selection hook, or if there is no existing selection, the right side of the chart.

The following example displays a list of links which zoom the chart.

<div id="time">
    <a onclick="HumbleFinance.zoom(5);">1w</a>
    <a onclick="HumbleFinance.zoom(21);">1m</a>
    <a onclick="HumbleFinance.zoom(65);">3m</a>
    <a onclick="HumbleFinance.zoom(127);">6m</a>
    <a onclick="HumbleFinance.zoom(254);">1y</a>
    <a onclick="HumbleFinance.zoom(1265);">5y</a>
</div>