Home  · Classes  · Annotated Classes  · Modules  · Members  · Namespaces  · Related Pages
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
General introduction
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.

File formats

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 <a href="http://sashimi.sourceforge.net" target="blank_">SASHIMI project page</a>
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:
- @b mzML The HUPO-PSI standard format for mass spectrometry data.
- @b featureXML The %OpenMS format for quantitation results.
- @b consensusXML The %OpenMS format for grouping features in one map or across several maps.
- @b idXML The %OpenMS format for protein and peptide identification.

Documented schemas of the %OpenMS formats can be found at
<tt>http://open-ms.sourceforge.net/schemas/</tt> .

@em IdXML files and @em 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 @em OpenMS/share/OpenMS/XSLT/ folder of your %OpenMS installation.
@n If you want to view the file on the computer with the %OpenMS installation, you can just open it in your
browser. 
@n If you copy the file to another computer, you have must copy the XSLT stylesheet to that coputer 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
<?xml-stylesheet type="text/xsl" href="file:///*PATH*IdXML.xsl"?>

to the folder where the stylesheet resides.


Common arguments of the TOPP tools

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:
- <b>-ini &lt;file&gt;</b> Use the given TOPP INI file
- <b>-log &lt;file&gt;</b> Location of the log file (default: 'TOPP.log')
- <b>-instance &lt;n&gt;</b> Instance number in the TOPP INI file (default: '1')
- <b>-debug &lt;n&gt;</b> Sets the debug level (default: '0')
- <b>-write_ini &lt;file&gt;</b> Writes an example INI file
- <b>-no_progress</b> Disables progress logging to command line
- <b>--help</b> Shows a help page for the command line and INI file options

TOPP INI files

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
adressed 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.

Parameter documentation

  General documentation of  a TOPP tool and documentation for the command line parameters,
  can be displayed using the command line argument @a --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 @a --help.
  It is however displayed in @b INIFileEditor (see next section).

Creating an INI file for a TOPP tool

  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 @b INIFileEditor.
INIFileEditor.png
  In the @subpage TOPP_INIFileEditor, the documentation of the parameters is displayed
  in the window at the bottom, once you click on the respective parameter.

Updating an INI file for a TOPP tool or a whole TOPPAS pipeline

  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 parameter's
  whose name did not change into the new version by using our @subpage UTILS_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.

General structure of an INI file

An INI file is always enclosed by the @a &lt;PARAMETERS&gt; tag. Inside this tag, a tree-like hierachy
is created with @a &lt;NODE&gt; tags that represent sections and @a &lt;ITEM&gt; tags, each of which stores one of the
parameters.  The first two level of the hierarchy have a special meaning.

<b>Example:</b> Below is the content of an INI file for @b FileFilter.

 Several parameter sets for a TOPP tool can be specified in a <i>tool section</i>.
  The tool section is always named after the program itself, in this case "FileFilter".
- In order to make storing several parameter sets for the same tool in one
  INI file possible, the tool section contains one or several
  <i>numbered instance subsections</i> ('1', '2', ...). These numbers are
  the instance numbers which can be specified using the  '-instance' command
  line argument. (Remember the default is '1'.)
- Within each instance section, the actual parameters of the TOPP tool are given.
  INI files for complex tools can contain nested subsections in order to
  group related parameters.
- If a parameter is not found in the instance section, the <i>tool-specific
  common section</i> is considered.
- Finally, we look if the <i>general common section</i> contains a value
  for the parameter.

Imagine we call the @b FileFilter tool with the INI file given below and instance number '2'.
The FileFilter parameters @a rt and @a mz are looked up by the tool.
@a mz can be found in section @b FileFilter - @a 2. @a rt is not specified in this section,
thus the @a common - @b FileFilter section is checked first, where it is found in our example.
When looking up the @a debug parameter, the tool would search the instance section and tool-specific common
section without finding a value. Finally, the general @a common section would be checked, where the debug
level is specified.
<PARAMETERS>
<NODE name="FileFilter">
<NODE name="1">
<ITEM name="rt" value="0:1200" type="string"/>
</NODE>
<NODE name="2">
<ITEM name="mz" value="700:1000" type="string"/>
</NODE>
</NODE>
<NODE name="common">
<NODE name="FileFilter">
<ITEM name="rt" value=":" type="string"/>
<ITEM name="mz" value=":" type="string"/>
</NODE>
<ITEM name="debug" value="2" type="int"/>
</NODE>
</PARAMETERS>

OpenMS / TOPP release 1.9.0 Documentation generated on Tue May 28 2013 12:41:58 using doxygen 1.8.3.1