 |
OpenMS
2.5.0
|
This tutorial will give you a brief overview of the most important TOPP tools. First, we explain some basics that you will need for every TOPP tool, then we show several example pipelines.
The TOPP tools use the HUPO-PSI standard format mzML 1.1.0 as input format. In order to convert other open formats (mzData, mzXML, DTA, ANDI/MS) to mzML, a file converter is provided by TOPP.
Proprietary MS machine formats are not supported. If you need to convert these formats to mzML, mzData or mzXML, please have a look at the SASHIMI project page or contact your MS machine vendor.
mzML covers only the output of a mass spectrometry experiment. For further analysis of this data several other file formats are needed. The main file formats used by TOPP are:
Documented schemas of the OpenMS formats can be found at http://www.openms.de/schemas/ .
idXML files and consensusXML files created by OpenMS can be visualized in a web browser directly. XSLT stylesheets are used to transform the XML to HTML code. The stylesheets are contained in the OpenMS/share/OpenMS/XSLT/ folder of your OpenMS installation.
If you want to view the file on the computer with the OpenMS installation, you can just open it in your browser.
If you copy the file to another computer, you have must copy the XSLT stylesheet to that computer and change the second line in the XML file. The following example shows how to change the stylesheet location for an idXML file. You simply have to change the *PATH* in the line
to the folder where the stylesheet resides.
The command line and INI file parameters of the TOPP tools vary due to the different tasks of the TOPP tools. However, all TOPP tools share this common interface:
Each TOPP tool has its own set of parameters which can be specified at the command line. However, a more convenient (and persistent) way to handle larger sets of parameters is to use TOPP INI files. TOPP INI files are XML-based and can contain the configuration of one or several TOPP tools.
The following examples will give an overview of how TOPP tools can be chained in order to create analysis pipelines. INI files are the recommended way to store all settings of such a pipeline in a single place.
Note that the issue of finding suitable parameters for the tools is not addressed here. If you encounter problems during the execution of the example pipelines on your data, you probably have to adapt the parameters. Have a look at the documentation of the corresponding TOPP tool in that case.
General documentation of a TOPP tool and documentation for the command line parameters, can be displayed using the command line flag –help.
Some TOPP tools also have subsections of parameters that are internally handed to an algorithm. The documentation of these subsections is not displayed with –help. It is however displayed in INIFileEditor (see next section), or when using –helphelp (which also shows advanced parameters).
The easiest way of creating an INI file is to advise the corresponding TOPP tool to write its default configuration file using the argument '-write_ini' on the command line. Now the INI file can be adapted to your needs using INIFileEditor.
In the INIFileEditor, the documentation of the parameters is displayed in the window at the bottom, once you click on the respective parameter.
If you have an old INI file which does not work for a newer OpenMS version (due to renamed/removed or new) parameters, you can rescue parameters whose name did not change into the new version by using our INIUpdater tool by calling it with (a list of) outdated INI and/or TOPPAS files. See the INIUpdater tool description for details. This will remove invalid parameters and add new parameters (if available) while retaining values for unchanged parameters. As an alternative to the INIUpdater, you can use the commandline by calling the TOPP tool from which the ini originated and combining '-write_ini' and '-ini'. E.g.
This will transfer all values of parameters from 'old_fi.ini' which are still valid to the 'fi.ini'.
An INI file is always enclosed by the <PARAMETERS> tag. Inside this tag, a tree-like hierarchy is created with <NODE> tags that represent sections and <ITEM> tags, each of which stores one of the parameters. The first two level of the hierarchy have a special meaning.
Example: Below is the content of an INI file for FileFilter.
Several parameter sets for a TOPP tool can be specified in a tool section. The tool section is always named after the program itself, in this case "FileFilter".
Imagine we call the FileFilter tool with the INI file given below and instance number '2'. The FileFilter parameters rt and mz are looked up by the tool. mz can be found in section FileFilter - 2. rt is not specified in this section, thus the common - FileFilter section is checked first, where it is found in our example. When looking up the debug parameter, the tool would search the instance section and tool-specific common section without finding a value. Finally, the general common section would be checked, where the debug level is specified.
1.8.16
