1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
<HTML>
<HEAD>
<TITLE>General introduction</TITLE>
<LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css">
<LINK HREF="style_ini.css" REL="stylesheet" TYPE="text/css">
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<A href="index.html">Home</A> ·
<A href="classes.html">Classes</A> ·
<A href="annotated.html">Annotated Classes</A> ·
<A href="modules.html">Modules</A> ·
<A href="functions_func.html">Members</A> ·
<A href="namespaces.html">Namespaces</A> ·
<A href="pages.html">Related Pages</A>
<HR style="height:1px; border:none; border-top:1px solid #c0c0c0;">
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">General introduction </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>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.</p>
<h1><a class="anchor" id="TOPP_fileformats"></a>
File formats</h1>
<p>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.</p>
<p>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.</p>
<p>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:</p>
<ul>
<li><b>mzML</b> The HUPO-PSI standard format for mass spectrometry data.</li>
<li><b>featureXML</b> The OpenMS format for quantitation results.</li>
<li><b>consensusXML</b> The OpenMS format for grouping features in one map or across several maps.</li>
<li><b>idXML</b> The OpenMS format for protein and peptide identification.</li>
</ul>
<p>Documented schemas of the OpenMS formats can be found at <code><a href="http://open-ms.sourceforge.net/schemas/">http://open-ms.sourceforge.net/schemas/</a></code> .</p>
<p><em>idXML</em> files and <em>consensusXML</em> 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/</em> folder of your OpenMS installation. <br/>
If you want to view the file on the computer with the OpenMS installation, you can just open it in your browser. <br/>
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 </p>
<div class="fragment"><div class="line"><?xml-stylesheet type=<span class="stringliteral">"text/xsl"</span> href=<span class="stringliteral">"file:///*PATH*idXML.xsl"</span>?></div>
</div><!-- fragment --><p> to the folder where the stylesheet resides.</p>
<hr/>
<h1><a class="anchor" id="TOPP_common_options"></a>
Common arguments of the TOPP tools</h1>
<p>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:</p>
<ul>
<li><b>-ini <file></b> Use the given TOPP INI file</li>
<li><b>-log <file></b> Location of the log file (default: 'TOPP.log')</li>
<li><b>-instance <n></b> Instance number in the TOPP INI file (default: '1')</li>
<li><b>-debug <n></b> Sets the debug level (default: '0')</li>
<li><b>-write_ini <file></b> Writes an example INI file</li>
<li><b>-no_progress</b> Disables progress logging to command line</li>
<li><b>–help</b> Shows a help page for the command line and INI file options</li>
</ul>
<hr/>
<h1><a class="anchor" id="TOPP_parameters"></a>
TOPP INI files</h1>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h2><a class="anchor" id="TOPP_parameter_documentation"></a>
Parameter documentation</h2>
<p>General documentation of a TOPP tool and documentation for the command line parameters, can be displayed using the command line argument <em>–help</em>.</p>
<p>Some TOPP tools also have subsections of parameters that are internally handed to an algorithm. The documentation of these subsections is not displayed with <em>–help</em>. It is however displayed in <b>INIFileEditor</b> (see next section).</p>
<h2><a class="anchor" id="TOPP_parameter_creation"></a>
Creating an INI file for a TOPP tool</h2>
<p>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</b>. </p>
<div class="image">
<img src="INIFileEditor.png" alt="INIFileEditor.png"/>
</div>
<p>In the <a class="el" href="TOPP_INIFileEditor.html">INIFileEditor</a>, the documentation of the parameters is displayed in the window at the bottom, once you click on the respective parameter.</p>
<h2><a class="anchor" id="TOPP_parameter_update"></a>
Updating an INI file for a TOPP tool or a whole TOPPAS pipeline</h2>
<p>If you have an old INI file which does not work for a newer <a class="el" href="namespaceOpenMS.html" title="Main OpenMS namespace. ">OpenMS</a> 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 <a class="el" href="UTILS_INIUpdater.html">INIUpdater</a> 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.</p>
<h2><a class="anchor" id="TOPP_parameter_structure"></a>
General structure of an INI file</h2>
<p>An INI file is always enclosed by the <em><PARAMETERS></em> tag. Inside this tag, a tree-like hierachy is created with <em><NODE></em> tags that represent sections and <em><ITEM></em> tags, each of which stores one of the parameters. The first two level of the hierarchy have a special meaning.</p>
<p><b>Example:</b> Below is the content of an INI file for <b>FileFilter</b>.</p>
<p>Several parameter sets for a TOPP tool can be specified in a <em>tool section</em>. The tool section is always named after the program itself, in this case "FileFilter".</p>
<ul>
<li>In order to make storing several parameter sets for the same tool in one INI file possible, the tool section contains one or several <em>numbered instance subsections</em> ('1', '2', ...). These numbers are the instance numbers which can be specified using the '-instance' command line argument. (Remember the default is '1'.)</li>
<li>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.</li>
<li>If a parameter is not found in the instance section, the <em>tool-specific common section</em> is considered.</li>
<li>Finally, we look if the <em>general common section</em> contains a value for the parameter.</li>
</ul>
<p>Imagine we call the <b>FileFilter</b> tool with the INI file given below and instance number '2'. The FileFilter parameters <em>rt</em> and <em>mz</em> are looked up by the tool. <em>mz</em> can be found in section <b>FileFilter</b> - <em>2</em>. <em>rt</em> is not specified in this section, thus the <em>common</em> - <b>FileFilter</b> section is checked first, where it is found in our example. When looking up the <em>debug</em> parameter, the tool would search the instance section and tool-specific common section without finding a value. Finally, the general <em>common</em> section would be checked, where the debug level is specified.</p>
<div class="fragment"><div class="line"><PARAMETERS></div>
<div class="line"></div>
<div class="line"> <NODE name=<span class="stringliteral">"FileFilter"</span>></div>
<div class="line"> <NODE name=<span class="stringliteral">"1"</span>></div>
<div class="line"> <ITEM name=<span class="stringliteral">"rt"</span> value=<span class="stringliteral">"0:1200"</span> type=<span class="stringliteral">"string"</span>/></div>
<div class="line"> </NODE></div>
<div class="line"> <NODE name=<span class="stringliteral">"2"</span>></div>
<div class="line"> <ITEM name=<span class="stringliteral">"mz"</span> value=<span class="stringliteral">"700:1000"</span> type=<span class="stringliteral">"string"</span>/></div>
<div class="line"> </NODE></div>
<div class="line"> </NODE></div>
<div class="line"></div>
<div class="line"> <NODE name=<span class="stringliteral">"common"</span>></div>
<div class="line"> <NODE name=<span class="stringliteral">"FileFilter"</span>></div>
<div class="line"> <ITEM name=<span class="stringliteral">"rt"</span> value=<span class="stringliteral">":"</span> type=<span class="stringliteral">"string"</span>/></div>
<div class="line"> <ITEM name=<span class="stringliteral">"mz"</span> value=<span class="stringliteral">":"</span> type=<span class="stringliteral">"string"</span>/></div>
<div class="line"> </NODE></div>
<div class="line"> <ITEM name=<span class="stringliteral">"debug"</span> value=<span class="stringliteral">"2"</span> type=<span class="stringliteral">"int"</span>/></div>
<div class="line"> </NODE></div>
<div class="line"></div>
<div class="line"></PARAMETERS></div>
</div><!-- fragment --> </div></div><!-- contents -->
<HR style="height:1px; border:none; border-top:1px solid #c0c0c0;">
<TABLE width="100%" border="0">
<TR>
<TD><font color="#c0c0c0">OpenMS / TOPP release 1.11.1</font></TD>
<TD align="right"><font color="#c0c0c0">Documentation generated on Thu Nov 14 2013 11:19:25 using doxygen 1.8.5</font></TD>
</TR>
</TABLE>
</BODY>
</HTML>
|
