Tutorials peakml.jar

The peakml Java library defines the common application programming interface for writing tools in the mzmatch framework and consists of many elements that ease development. In this tutorial an overview of the most important elements is given. For more information see the javadoc documentation.

This tutorial contains:


The peakml library can be downloaded from the files menu. The peakml.jar then needs to be linked to your project and it is ready for use (i.e. there exist no external dependencies).

I/O classes

In order to use the library, the most used classes need to be imported.

import peakml.*;
import peakml.io.*;
With the peakml.io package, all descriptive classes (like the header, sample description, etc.) are imported. These classes are required to retrieve the meta-information from the data files and are re-used by all the I/O classes as this task is generic enough.

The Header class contains the following elements:

PeakML files

Access to PeakML files is provided by the class PeakMLParser, which provides parse functions, and the class PeakMLWriter, which provides write functions. Both classes provide static functions to do the operations and do not need to be initialized. The example below loads a file, of which the contents is unknown. The second parameter indicates that the complete contents of the file needs to be loaded into memory. The class ParseResult will contain the two elements Header and Measurement. The measurement instance in the case of the PeakML files will always be an instance of IPeakSet.

ParseResult result = PeakMLParser.parse(new FileInputStream("[FILENAME].peakml"), true);
Header header = result.header;
IPeakSet<? extends IPeak> peakset = (IPeakSet<? extends IPeak>) result.measurement;
The type of the contents of the peakset can be determined by the following.
if (peakset.getContainerClass().equals(IPeakSet.class))
else if (peakset.getContainerClass().equals(BackgroundIon.class))
else if (peakset.getContainerClass().equals(MassChromatogram.class))
As a peakset can contain other peaksets, functionality is provided for unpacking the sets into a single vector of non-peakset instances.
java.util.Vector<? extends IPeak> unpacked = IPeak.unpack(peakset);
This is achieved by a recursive function.
public static void recursive(IPeak peak)
  Class<? extends IPeak> cls = peak.getClass();
  if (cls.equals(IPeakSet.class))
    for (IPeak p : (IPeakSet) peak)
  else if (cls.equals(MassChromatogram.class))
  else if (cls.equals(BackgroundIon.class))

For a complete overview of all the functions see the OpenPeakML snippet.

Thermo RAW files

Java programmatic access to Thermo RAW files is provided by the class IXRawfile, which uses the Microsoft Windows OLE specific mechanism for providing a 1-to-1 mapping to Thermo's IXRawfile.DLL. This means this class will only work on the windows platform with a valid installation of Xcalibur or the Thermo MSFileReader. Please note! this is truly a 1-to-1 mapping and the DLL does not implement a standardized scheme with regards to the indices. Read the documentation of the methods.

Before access to the raw files can be obtained, the instance needs to be initialized and the file opened. Do not forget to close and dispose the connection when you are done. Especially in cases where multiple files need to be opened, it's important to dispose every time because of a bug in the Thermo library, which will result in an error-message when opening over 9 files. This means it's a good idea to keep the needed data in memory.

IXRawfile raw = new IXRawfile();
  // do your operations
Now the connection has been opened, the controller of interest needs be selected. An overview of the available controllers can be found by the method getNumberOfControllersOfType, which returns the number of controllers of a given type (the types are defined in the class, prepended with CONTROLLER_). The method setCurrentController will set the controller.
int nrcontrollers = raw.getNumberOfControllersOfType(IXRawfile.CONTROLLER_MS);
for (int i=1; i<=raw.getNumberOfControllers(); ++i)
  raw.setCurrentController(IXRawfile.CONTROLLER_MS, i);
  // do your operations
Now the controller has been set, the data can be extracted. The example extracts some general information
System.out.println("Filename: " + raw.getFileName());
System.out.println("Created by: " + raw.getCreatorID());
System.out.println("File version: " + raw.getVersionNumber());
System.out.println("Created: " + raw.getCreationDate());
For a complete overview of all the functions see the OpenIXRawfile snippet.

Waters RAW files

Java programmatic access to Waters RAW files is provided by the classes in the package peakml.io.dac, which uses the Microsoft Windows OLE specific mechanism for providing a 1-to-1 mapping to Waters' Data Access Component. This means this class will only work on the windows platform with a valid installation of MassLynx.

The required library for setting up the link between the Waters DLL and peakml is automatically ejected from the peakml.jar upon first use. There is no need to take care of anything with this regard.

This package consists of the classes DACHeader, DACSpectrum, DACCalibrationInfo, DACScanStats, DACExScanStats, DACFunctionInfo, DACExperimentInfo, and DACProcessInfo which are direct mappings to the classes defined in the DAC DLL of Waters. The data is gathered by the 'dac.dll', which is integrated into the library and automatically exported outside the jar when needed. For each of the classes an instance needs to be created and then the method open(java.lang.String) called to fill the instance (analogous to the setup of Waters).

In the example below some header information is printed.

DACHeader hdr = new DACHeader();
In the file format different data streams can be stored (termed functions). In the example below the spectrum data of scan 120 of the first function is collected.
DACSpectrum spectrum = new DACSpectrum();
spectrum.open(filename, 1, 0, 120);
For a complete overview of all the functions see the OpenDAC snippet.


The class MassChromatogram contains the data points collected in a 2D setup (LC or GC), making up the chromatographic feature. In order to specify whether the chromatographic feature is built up out off profile or centroid data generics are used.

MassChromatogram mc;
Design based on the SWT pages. Get mzmatch at SourceForge.net. Fast, secure and Free Open Source software downloads