<tool id="metams_lcms_annotate" name="METAMS-LC/MS Annotate"  version="0.0.4">
	<description> Runs metaMS process for LC/MS feature annotation</description>
	<requirements>
		<requirement type="package" version="3.1.1">R_bioc_metams</requirement>
	</requirements>	
	<command interpreter="Rscript">
		metaMS_cmd_annotate.r 
	    $constructed_db
	    $xsetData
	    $customMetaMSsettings
	    $outputFile 
	    #if $mzTol.mzTolType == "fixed"  
			0
		#else
            "$mzTol.mass_error_function"
		#end if
	    $htmlReportFile
	    $htmlReportFile.files_path
	    $outputLog
	</command>
<inputs>
	<param name="constructed_db" type="select" label="Constructed DB" help="Reference annotation database generated from matching measurements of a mixture of chemical standards
	against a manually validated reference table which contains the key analytical information for each standard." 
      		 dynamic_options='get_directory_files("tool-data/shared/PRIMS-metabolomics/metaMS")'/>
	
	<param name="xsetData" type="data" format="rdata" label="xcmsSet data file (xset RDATA)" help="E.g. output data file resulting from METAMS 'feature picking, aligning and grouping' run"/>
	
	<param name="protocolName" type="text" size="30" label="protocolName" value="e.g. Synapt.QTOF.RP" 
		help="Choose a name to give for the specific settings in the parameters below"/>
	
	<param name="rtdiff" type="float" size="10" value="1.5" label="rtdiff" help="(Annotation) Allowed rt difference (in minutes)"/>
	
	<conditional name="mzTol">
		<param name="mzTolType" type="select" size="30" label="(Annotation) m/z tolerance type">
			<option value="fixed" selected="true">Fixed tolerance</option>
			<option value="adaptive" >Adaptive tolerance</option>
		</param>
		<when value="fixed">
			<param name="mzdiff" type="float" size="10" value="0.005" label="mzdiff" help="(Annotation) Fixed mass tolerance" />
		</when>
		<when value="adaptive">
			<param name="ppm" type="float" size="10" value="5.0" label="ppm" help="(Annotation) Tolerance in ppm" />
			<param name="mass_error_function" type="text" area="true" size="3x70" label="(Annotation) Mass error function"/>
		</when>
	</conditional>

	<param name="rtval" type="float" size="10" value="0.1" label="(max)rtval" help="(Validation) Group items are clustered once more with hierarchical clustering ('complete' method)
	          based on their rt distances. Here one can specify the rt threshold for removing the items that have too diverging rt (the ones with rt difference 
	          larger than rtval). " />
	<param name="minfeat" type="integer" size="10" value="2" label="minfeat" 
	           help="(Validation) Threshold for the minimum number of features a 
	           cluster/group should have (after rtval filtering above). Other clusters/groups are filtered out." />
	
</inputs>
<configfiles>

<configfile name="customMetaMSsettings">## start comment
		## metaMS process settings
		customMetaMSsettings &lt;- metaMSsettings(protocolName = "${protocolName}",
                            chrom = "LC")
metaSetting(customMetaMSsettings, "match2DB") &lt;- list(
            rtdiff = ${rtdiff},
            rtval = ${rtval},
		#if $mzTol.mzTolType == "fixed"  
			mzdiff = ${mzTol.mzdiff},
		#else
            ppm = ${mzTol.ppm},
		#end if
            minfeat = ${minfeat})</configfile>

</configfiles>

<outputs>
	<data name="outputFile" format="tabular" label="${tool.name} on ${on_string} - metaMS annotated file (TSV)"/>
	<data name="outputLog" format="txt" label="${tool.name} on ${on_string} - metaMS LOG" hidden="True"/>
	<data name="htmlReportFile" format="html" label="${tool.name} on ${on_string} - metaMS report (HTML)"/>
</outputs>
<tests>
	<test>
	</test>
</tests>
<code file="../match_library.py" /> <!-- file containing get_directory_files function used above-->
<help>

.. class:: infomark
  
Runs metaMS process for LC/MS feature annotation based on matching to an existing 'standards' DB.  
The figure below shows the main parts of this metaMS process.

.. image:: $PATH_TO_IMAGES/metaMS_annotate.png 


.. class:: infomark

The implemented annotation strategy can be broken down in the following steps:

1. *Feature wise Annotation:* Each feature detected by runLC is matched against the database. If
the mass error function is provided, the appropriate m/z tolerance is calculated, otherwise a fixed
tolerance is used (mzdiff). The retention time tolerance is fixed and should be selected on the
bases of the characteristics of each chromatographic method (rtdiff). Multiple annotations - i.e.
features which are associated to more than one compound - are possible. This outcome does not
indicate a problem per se, but is an inherent drawback of co-elution.

2. *Annotation Validation:* The annotated features are organized in 'pseudospectra' collecting all
the experimental features which are assigned to a specific compound. A specific annotation is
confirmed only if more than minfeat features which differ in retention time less than rtval are
present in a pseudospectrum. As a general rule rtval should be narrower than rtdiff. The
latter, indeed, accounts for shifts in retention time between the injection of the standards and the
metabolomics experiment under investigation. This time can be rather long, considering that the
standards are not commonly re-analyzed each time. On the other hand, rtval represents the shift
between the ions of the same compound within the same batch of injections and therefore it has
only to account for the smaller shifts occurring during peak picking and alignment.


  </help>
  <citations>
        <citation type="doi">10.1016/j.jchromb.2014.02.051</citation> <!-- example 
        see also https://wiki.galaxyproject.org/Admin/Tools/ToolConfigSyntax#A.3Ccitations.3E_tag_set
        -->
   </citations>
</tool>