The JSpecView Project: an Open Source Java viewer and converter for JCAMP-DX, and XML spectral data files

Abstract

The JSpecView Open Source project began with the intention of providing both a teaching and research tool for the display of JCAMP-DX spectra. The development of the Java source code commenced under license in 2001 and was released as Open Source in March 2006. The scope was then broadened to take advantage of the XML initiative in Chemistry and routines to read and write AnIML and CMLspect documents were added.

JSpecView has the ability to display the full range of JCAMP-DX formats and protocols and to display multiple spectra simultaneously. As an aid for the interpretation of spectra it was found useful to offer routines such that if any part of the spectral display is clicked, that region can be highlighted and the (x, y) coordinates returned. This is conveniently handled using calls from JavaScript and the feedback results can be used to initiate links to other applets like Jmol, to generate a peak table, or even to load audio clips providing helpful hints.

Whilst the current user base is still small, there are a number of sites that already feature the applet. A tutorial video showing how to examine NMR spectra using JSpecView has appeared on YouTube and was formatted for replay on iPods and it has been incorporated into a chemistry search engine.

Background

The introduction of open standards by IUPAC (International Union of Pure and Applied Chemistry) and ASTM International (originally known as the American Society for Testing and Materials) has greatly enhanced the ability to transfer data between spectroscopic instruments of different origin, regardless of their application software and operating systems. In particular, the publication and successful implementation of the JCAMP-DX (Joint Committee on Atomic and Molecular Spectroscopy – Data Exchange) protocols have made it possible to transfer and archive infrared and Raman spectroscopy [1], nuclear magnetic resonance spectroscopy [2], mass spectrometry [3], ion mobility spectroscopy [4] and electron magnetic resonance spectroscopy [5] data sets.

The JCAMP-DX protocols (including drafts of forthcoming protocols) are available on the JCAMP-DX web site [6] and are based on standard ASCII to ensure maximum compatibility and longevity of the data. They utilize encoding routines that, depending on the software, make it possible to produce data exchange files with no loss of precision, and the compression algorithms can often yield files that are smaller than the original binary (and often proprietary) spectrometer files, again with no loss of precision in the data. These protocols were written without reference to any particular software package and IUPAC has not released code to either read or write JCAMP-DX data files.

One of the first readily available viewers for JCAMP-DX data files was released in 1996 by MDL (now Symyx) as part of their Windows version of the plug-in Chime [7]. This was based on code developed at UWI, Jamaica and licensed by them. Up until 2005, when the development of our JCAMP-DX routines in Chime ceased, it was estimated that over 2 million copies of the free version were downloaded from the MDL web site [8]. The source code was never made Open Source.

In 2001, a major rewrite of the JCAMP-DX routines used in Chime was initiated using JAVA instead of C++. This new code was again licensed to MDL, but in 2006 they agreed to relinquish all rights to the code. Following this decision, the Java source code for the JSpecView project was made available on the Sourceforge web site in March 2006 as Open Source [9].

The cross-platform JSpecView project was originally intended to provide a JAVA applet and application that could serve as viewers for spectral data saved in the JCAMP-DX protocols. This was later extended to XML documents (AnIML [10] and CMLspect [11]) and the application (JSVApp.jar) can read and write files and thus act as a converter between these formats.

Implementation

The list below highlights some of the features of JSpecView, many of which are either new or have been extensively expanded from those available in Chime.

The features

• Load any data file in JCAMP-DX format (with limited support for beta version 6)

• Import AnIML (protocols still in draft form) and CMLspec files.

• Highlight portions of the spectrum.

• Many levels of zooming in and out.

• Print the Spectrum.

• Reverse the plot.

• Display a grid on the spectrum.

• Show the coordinates as the mouse moves over the plot.

• Convert between Absorbance and Transmittance (for UV/Vis and IR)

• Integrate H NMR spectra.

• Four views or interfaces for compound files: single, overlay, tab or tile.

• View the header or properties of the spectrum.

• Javascripting and Live Connect support *

• Export different JCAMP-DX compression formats *

• Export as AnIML, CML, JPG, PNG or SVG *

* Applets do not normally have permission to write to the hard disk so these functions will not work unless the appropriate permissions are set. A self-signed JSpecView applet is available that alleviates this problem and this is not an issue with the standalone application.

Parameters

To simplify the design of web pages that are to be read by different browsers running on different platforms it was decided to initially call a set of JavaScript functions since these can determine the browser type and which version is being used and then apply the appropriate instructions to the applet. The parameters that can be used to change the initial display are passed as a semi-colon separated list using a script call. The allowed parameters in the list and their description follow:

• load To open a spectrum, the name of the JCAMP-DX file must be given. Note that the file must be in the class path of the applet or the full path to the file given.

The forward slash can be used as a path separator '/' or else escape the backslash using a double backslash '\\ '. This is the only parameter that is required.

for example load filename.dx; or load c:/jcamp-dx/filename.dx; or load c:\\ jcamp-dx\\ filename.dx;

• import To import a spectrum stored in AnIML or CML format. Note that the file must be in the class path of the applet or the full path to the file given.

for example import filename.aml; or import c:/XML/filename.aml; or import c:\\ XML\\ filename.aml;

If the extension is .xml the file is interrogated to see what is present in the namespace schema location. This determines whether routines for AnIML or CML are used for reading and parsing the information.

• gridon Specifies whether the grid should be displayed

true or false

• coordinateson Specifies whether the coordinates should be displayed

true or false

• reverseplot Specifies whether the plot should be displayed with scale reversed. (This is the reverse of the order of the points in the file)

true or false

• startindex Used along with endindex to display only a segment of the spectrum. startindex is the index of the starting data point of the segment that should be displayed. If this is specified and endindex isn't, then a segment starting from startindex to the last data point is displayed.

0,1,2,3...

• endindex the index of the last data point of the spectrum to be displayed.

for example 32765

• menuon Specifies whether the menus should be displayed.

If this is set to false then only the Aboutmenu is enabled. This means that zooming is disabled as well.

To enable zoom, set enablezoom true.

• compoundmenuon Specifies whether the menu that enables the user to choose which spectrum to display (in single interface mode) is enabled.

true or false

• enablezoom Specifies whether zooming is enabled. Enabling zoom effectively enables the zoom menu and vice versa.

true or false

• spectrumnumber For Ntuple and Block files, this specifies the spectrum that should be initially displayed when the applet is loaded.

1,2,3...

• interface This parameter applies to Ntuple or Block files only. This changes the GUI (Graphical User Interface) of the applet.

single One spectrum is displayed (default is spectrum number 1). A Ntuple or Block menu is added to the popup menu to navigate to the other spectra in the file.

tab All spectra are displayed and may be navigated with tabs

tile A maximum of 10 spectra are displayed and tiled. If there are more than 10 spectra in the file then the interface defaults to single.

overlay The spectra are displayed overlaid.

single, tab, tile, overlay

• coordcallbackfunctionname a string, e.g. MyCoordCB, default null (see scripting below)

• peakcallbackfunctionname a string, e.g. MyPeakCB, default null (see scripting below)

• titlecolor The color of the title. All Colors must be specified by an rgb value or as a hexadecimal value. eg. black would be "0, 0, 0" or "#000000". Note that the # is required for hexadecimal format and rgb values must be comma separated.

default is black (#000000)

• gridcolor The color of the grid

default is grey (#808080)

• unitscolor The color of the units

default is red (#FF0000)

• scalecolor The color of the scale

default is black (#000000)

• coordinatescolor The color of the coordinates

default is red (#FF0000)

• plotareacolor The color of the plot area

default is white (#FFFFFF)

• plotcolor The color of the plot line

(NB. When spectra are overlaid, the first eight colors are: blue, green, yellow, orange, red, magenta, pink and cyan. After that the colors are chosen at random.)

default is blue (#0000FF)

• backgroundcolor The color of the background

default is grey (#808080)

Scripting and Live Connect

Certain methods in the applet may be called from JavaScript. The following descriptions of the methods and the arguments or return values are given below:

• setFilePath and setXMLPath for example c:/jcamp-dx/filename.dx or c:\\ jcamp-dx\\ filename.xml

Allows the loading of a new JCAMP-DX or importing of a XML file, specified from JavaScript. Note that the file must be in the class path of the applet or the full path given. The forward slash can be used as a path separator '/' or else escape the backslash using a double backslash '\\ '.

• getCoordinate returns space separated values, e.g. "3220 0.41".

Used to return the coordinates of a point when it is clicked on the applet display

toggleGrid none

Toggles the grid on/off

toggleCoordinate none

Toggles the x, y coordinate display

reversePlot none

Reverses the plot

setSpectrumNumber 1, 2, ...

For Ntuple and Block files, this specifies the spectrum that should be initially displayed.

addHighlight x1– starting x coordinate, x2– ending x coordinate, r– red value of rgb color scheme, g– green value, b– blue value. Numbers from 0–255. a– alpha value or transparency. Number from 0 – 255.

Add a highlight to the region specified by x1 and x2 with the color and transparency specified by r, g, b and α.

removeHighlight x1– starting x coordinate, x2– ending x coordinate

Removes the highlight at the position specified by x1 and x2. There must be a highlight specified by x1 and x2 exactly for this method to work.

removeAllHighlights none

Removes all highlights from the display.

JSpecView may call a JavaScript function in response to mouse clicks in the plot area of the spectrum display if the coordcallbackfunctionname or peakcallbackfunctionname parameter is specified. In the first case it gets passed the values of the x and y position as two floating point numbers. In the second case in addition to these values, it returns the closest actual x, y values from the dataset and the value of the spectrum number, if a Block or Ntuple file is open.

The second JavaScript function must be implemented with the name given by the peakcallbackfunctionname parameter and take as its argument four floating point values for the two sets of x and y coordinates and an integer for the spectrum number. For example, if the value of the peakcallbackfunctionname parameter is MyPeakClicked, then a JavaScript method might look like this:

function MyPeakClicked(x1, y2, x2, y2, SNum){

   alert("You Clicked: " + x1 + ", " + y1);

   alert("The nearest datapoint was at : " + x2 + ", " + y2);

}

From this it is possible to record a series of mouse click positions to generate a peak table list.

Discussion

One of the features new to JSpecView is the ability to load and display multiple spectra simultaneously, when viewing JCAMP-DX Block files with similar X-axis ranges. This can be used to display kinetic runs or a series of related spectra. The display options include showing the spectra superimposed, tiled or as separate tabbed pages (see additional file 1 and Figures 1, 2). A routine for generating Block files from individual NMR spectra has been developed from the project code [12].

Figure 1

Screen dump showing the simultaneous display of multiple spectra in the Java application.

Figure 2

Screen dumps showing the display of multiple spectra in the applet (Tabbed or overlaid).

Other new features are the ability to convert between Absorbance and Transmittance for IR and UV/Vis spectra as well as perform a simple integration of H NMR spectra (see additional file 1 and Figure 3).

Figure 3

Screen dump showing Transmittance/Absorbance and Integration menus.

Over the past two years, Jmol [13] and JSpecView have become a replacement for MDL Chime, which is no longer in development, and together include much of its functionality. For web developers this has necessitated a rewrite of pages that used Chime since the calls to the Java applets are quite different and the requirements are not equivalent. Chime required the user to have previously downloaded and installed the plug-in for their browser (and to display spectra this required a Windows platform).

The requirement for the user now is that they have installed the Sun Java Run Time Environment (JRE) and since JSpecView uses features only released in 1.5, earlier JRE's will not work. This is not envisaged as a major problem since often the JRE's have been set to automatically update when new releases are available. This is not a restriction for Jmol, which by design is coded to run with the full range of JVM (Java Virtual Machines) and JRE's.

Some of the examples provided to promote JSpecView show how the two applets can interact. For infrared spectroscopy [14] (see additional file 1 and Figure 4) this can be demonstrated by having the spectrum hyperlinked to vibrational mode animations such that if the user clicks on a peak in the IR spectrum then that area is highlighted and the Jmol display changes to show the bonds "vibrating". For H and C NMR [15] (see additional file 1 and Figure 5) the interaction can be made bidirectional so that if the user clicks on an H or C atom then the peak in the NMR spectrum is highlighted, or if they click on a peak in the NMR spectrum the appropriate atom is highlighted as well. For simple mass spectra [16] (see additional file 1 and Figure 6) JavaScripts can be used to analyze the connectivity within the molecule and then if the user clicks on a peak in the spectrum the Jmol display shows where the cleavage has occurred and the mass fragments that result.

Figure 4

Screen dump showing interaction with Jmol for IR interpretation.

Figure 5

Screen dump showing interaction with Jmol for NMR interpretation.

Figure 6

Screen dump showing interaction with Jmol for interpretation of simple Mass Spectra.

One of the earliest examples of using chemical MIME types for spectra on the web was a display mimicking a GC/MS experiment on the headspace of coffee [17]. Clicking on a peak in the GC display would cause Chime to load a molecular display or spectrum. Using JSpecView and Jmol this has been updated [18] so that three displays are seen on screen: the GC trace, a display of a MS and a Jmol display. Clicking on a peak in the GC loads the MS and molecular display for the component that gave rise to that band (see additional file 1 and Figure 7).

Figure 7

Screen dump showing a simulation of a GC/MS.

Conclusion

So far over two thousand files have been downloaded from the Sourceforge project site. Some of the biggest users, apart from developments here in Jamaica, have come from the Bradley Research group at Drexel University [19] and by the Spinney group at Ohio State University for use as a teaching tool [20]. The chemistry search engine, ChemSpider [21] has started accepting spectral depositions that can be displayed by JSpecView as well. Eventually it is hoped that chemical information collected by ChemSpider can be searched based on a name, synonym, Smiles string, InChI or InChI key or even by structure or substructure and physical properties information returned as well as a display of any spectral information deposited.

Availability and requirements

• Project name: JSpecView project

• Project home page: http://jspecview.sourceforge.net

• Operating system(s): Platform independent

• Programming language: Java

• Other requirements: e.g. Java 1.5 or higher

• License: GNU Library or Lesser General Public License (LGPL)

Some of the routines used in JSpecView were developed by the Apache group and licensed under the Apache License 2.0 These include Velocity and Xerces.

The Streaming API for XML (StAX) JSR173 is a Java based API for pull-parsing XML and the Sun Java Streaming XML Parser (SJSXP) is licensed under the Binary Code License Agreement.

The MDIDesktop routines that add Multiple Document Interface (MDI) functionality were published by Gerald Nunn and distributed free and without warranty.

• Any restrictions to use by non-academics: none