SpeckTackle is written in the interpreted programming language JavaScript. JavaScript is a powerful scripting language to develop cross-browser compatible software libraries. In combination with HTML5 in modern browsers, JavaScript is the language of choice to ensure portability and wide applicability interactive web-facing tools [9,10].
SpeckTackle depends on the D3 (Data Driven Documents [11]) and JQuery JavaScript libraries, which are used in many websites. D3 simplifies the manipulation of the DOM (Document Object Model) and provides visualisation components, which form the base of the SpeckTackle charting library. JQuery is primarily used for HTML traversal and Ajax handling. Both libraries are assumed to be defined globally within the website as it is typically the case.
The charting library has been tested on recent versions of all major modern web browsers (Firefox, Internet Explorer, Opera, Chrome, and Safari) that adhere to HTML5 and SVG web standards, which in case of SVG have a global usage of about 90% (http://caniuse.com/#feat=svg). Compatibility to older browsers such as Internet Explorer 9 has been sacrificed in favour of source code comprehensibility and maintainability.
The project – including extensive documentation and example charts – is available online on the project repository BitBucket and a Mini-website is provided that is browsable from within the full text HTML version of the article [Additional file 1]. The source code is released under GNU LGPL version 3 to encourage uptake and reuse.
Library development
The SpeckTackle library consists of several files to structure the project and simplify development. The library can be built using a Make script. Modules required for building and ‘minifying’ the project are listed in the online documentation. The SpeckTackle CSS (st.css) is required in addition to the library (st.min.js) to control the style and layout of charts.
SpeckTackle provides pre-defined chart types for IR, MS, NMR (1D and 2D) and general time series data. The layout and mouse behaviour of each chart type is defined by de facto standards and concern the x- and y-axes (placement/direction), zoom behaviour (box/range-zoom), color schemes, and representation of data points (impulse/line/point). One example for a typical mouse behaviour is resetting the zoom by double-clicking on the chart.
A custom chart type extends the base chart, which defines a two dimensional Cartesian coordinate system and box-zooming as default mouse behaviour. At a minimum, a custom chart needs to implement three functions that describe how data is to be drawn (1) and how the x- and y-values (2,3) are scaled, e.g. linear or logarithmic. Further customisation to the base chart are achieved by extending or overriding existing base chart functions.
Expected options such as a chart title, x- and y-labels, an interactive legend, chart margins, and signal labels can be set on chart creation in a cascading fashion before a data set is assigned to the chart.
SpeckTackle accepts input in JSON format either directly or through Ajax. Similar to the pre-defined chart types, data handlers are implemented to reduce library set up to a minimum. A data handler is used to describe the structure of input data and to deal with data load and removal events after the data handler is associated (bound) to the chart. It should be pointed out that the library is stateless, i.e. files are reloaded and the library is reset when the user navigates away from the website.
As a general rule, all interaction between a chart and raw data is mediated through a data handler, which keeps track of added data series and their properties. Multiple data series (overlays) are supported with the ability to highlight an individual data series via its legend key. Figure 1 illustrates the above described concepts and relationships. A detailed description of the individual functions is provided in the online documentation.
The JavaScript code listing below provides a minimalistic, commented example of steps required to set up a chart for mass spectra and load data. Cysteine [MTBLC15356] from the MetaboLights website is used as example.
A data handler also controls how data is binned: for larger data series, e.g. NMR spectra with >60,000 points, the visualisation of all data points is unnecessary and slows down response times of a chart. Instead, a data handler can bin data series by their minimum, e.g. for IR spectra, or maximum signal intensities, e.g. for NMR spectra, for a given bin width – typically one pixel – and x-axis scale. Binning is carried out on data load and can be adjusted – or turned off – in the library. The default of one pixel, which typically provides enough resolution to show the shape of a data set, is controlled by the variablebinwidth in the bin method in its respective data object. The chart type defines whether data is binned by minimum or maximum.
Annotations and tooltips for data point selection events are supported through the concept of annotation types. Implemented annotation types encompass textual annotations that are drawn onto the chart and textual/structural tooltip annotations. Whereas textual annotations are simply drawn besides their target data points, tooltip annotations are specified as key-value pairs
In the first case, the key-value pairs are character strings that are displayed as list in the form ‘ <key>: <value>’.
In the second case, the value of each pair is treated as URL to a MDL Molfile, which contains the molecular structure to be displayed, and resolved accordingly. SpeckTackle provides its own internal MDL Molfile parser and draws molecules as SVG directly from the file.
The following two code listings demonstrate the concept. Annotation type names and the function name annotationColumn have been abbreviated in the interested of space. The structure of the annotation JSON file is defined in the data handler before data can be loaded.
The annotation JSON file contains two required columns by default: the first column defines the group. Multiple groups are permitted and are listed for selection on data load. The second column defines the lookup value in the x-domain. Subsequent columns must match the structure described to the data handler.
