annotate metams_lcms_pick_and_group.xml @ 49:f772a5caa86a

Added more options and better documentation. Added MsClust support for parsing XCMS alignment results. Improved output reports for XCMS wrappers. New tools.

<tool id="metams_lcms_pick_and_group" name="METAMS-LC/MS Pick, Align and Group"  version="0.0.4">
	<description> Runs metaMS process for LC/MS feature picking, aligning and grouping</description>
	<requirements>
		<requirement type="package" version="3.1.1">R_bioc_metams</requirement>
	</requirements>	
	<command interpreter="Rscript">
		metaMS_cmd_pick_and_group.r 
	    $data_files
	    $customMetaMSsettings
	    $outputFile 
	    $xsetOut
	    $htmlReportFile
	    $htmlReportFile.files_path
	    $outputLog
	</command>
<inputs>
	<param name="data_files" type="data" format="prims.fileset.zip" label="Data files (.zip file with CDF, mzML or mzXML files)" help=".zip file containing the CDF, mzML or mzXML files of the new measurements"/>
	
	<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"/><!-- TODO - let user choose this -->
	
	
	<!-- ===========NB : if peak picking, alignment OR CAMERA settings have to be reused for runGC wrapper in the future, we can use Galaxy macro expansions here
	                     to avoid defining these parameters again in the runGC wrapper ========================= -->
	<conditional name="peakPicking">
		<param name="method" type="select" size="30" label="PEAK PICKING method ====================================================="
		help="matchedFilter=Feature detection in the chromatographic time domain ; centWave=Feature detection for high resolution LC/MS data">
			<option value="matchedFilter" selected="true">matchedFilter</option>
			<option value="centWave" >centWave</option>
		</param>
		<when value="matchedFilter">	
			<param name="fwhm" type="integer" size="10" value="20" label="fwhm" 
			help="full width at half maximum of matched filtration gaussian model peak. Only used to calculate the actual sigma" />
			<param name="sigma_denom" type="float" size="10" value="2.3548" label="sigma_denominator" 
			help="denominator for standard deviation (width) of matched filtration model peak (e.g. sigma = fwhm/2.3548)" />
			<param name="max" type="integer" size="10" value="50" label="max" 
			help="maximum number of peaks per extracted ion chromatogram" />
			<param name="snthresh" type="integer" size="10" value="4" label="snthresh" 
			help="signal to noise ratio cutoff" />
			<param name="step" type="float" size="10" value="0.05" label="step" 
			help="step size to use for profile generation"/>
			<param name="steps" type="integer" size="10" value="2" label="steps" 
			help="number of steps to merge prior to filtration"/>
			<param name="mzdiff" type="float" size="10" value="0.8" label="mzdiff" 
			help="minimum difference in m/z for peaks with overlapping retention times"/>
		</when>
		<when value="centWave">
			<param name="ppm" type="integer" size="10" value="25" label="ppm" 
			help="maxmial tolerated m/z deviation in consecutive scans, in ppm" />
			<param name="peakwidth" type="text" size="10" value="20,50" label="peakwidth" 
			help="Chromatographic peak width, given as range (min,max) in seconds" />
			<param name="snthresh" type="integer" size="10" value="10" label="snthresh" 
			help="signal to noise ratio cutoff" />			
			<param name="prefilter" type="text" size="10" value="3,100" label="prefilter=c(k,I)" 
				help="Prefilter step for the first phase. Mass traces are only retained if 
				they contain at least k peaks with intensity &gt; = I" />			
			<param name="mzCenterFun" type="select" size="30" label="mzCenterFun" 
				help="Function to calculate the m/z center of the feature: wMean intensity weighted mean of the 
				feature m/z values, mean mean of the feature m/z values, apex use m/z value at peak apex, 
				wMeanApex3 intensity weighted mean of the m/z value at peak apex and the m/z value left and 
				right of it, meanApex3 mean of the m/z value at peak apex and the m/z value left and right of it">
				<option value="wMean" selected="true">wMean</option>
				<option value="mean" >mean</option>
				<option value="apex" >apex</option>
				<option value="wMeanApex3" >wMeanApex3</option>
				<option value="meanApex3" >meanApex3</option>
			</param>
			<param name="integrate" type="select" size="30" label="integrate" 
				help="Integration method. If =1 peak limits are found through descent 
				on the mexican hat filtered data, if =2 the descent is done on the real data. 
				Method 2 is very accurate but prone to noise, while method 1 is more robust to noise but less exact">
				<option value="1" selected="true">1</option>
				<option value="2" >2</option>
			</param>
			<param name="mzdiff" type="float" size="10" value="-0.001" label="mzdiff" 
				help="minimum difference in m/z for peaks with overlapping retention times, can be negative to allow overlap" />
			<param name="fitgauss" type="integer" size="10" value="20" label="fitgauss" 
				help="logical, if Yes: a Gaussian is fitted to each peak" >
				<option value="TRUE" selected="true">Yes</option>
				<option value="FALSE" >No</option>
			</param>
			<param name="noise" type="integer" size="10" value="0" label="noise" 
				help="optional argument which is useful for data that was centroided without any intensity
				 threshold, centroids with intensity &lt; noise are omitted from ROI detection" />
		</when>
	</conditional>

	
	<param name="min_class_fraction" type="float" size="10" value="0.3" label="ALIGNMENT min.class.fraction =====================================================" 
		    help="Minimum fraction of samples necessary in the alignment to make it a valid alignment/group"/>
	<param name="min_class_size" type="integer" size="10" value="3" label="min.class.size" 
			help="Minimum number of samples necessary in the alignment to make it a valid alignment/group. The lowest criteria
			between this and min.class.fraction will be used." />
	<param name="mzwid" type="float" size="10" value="0.1" label="mzwid" 
			help="width of overlapping m/z slices to use for creating peak density chromatograms and grouping peaks across samples"/>
	<param name="bws" type="text" size="10" value="30,10" label="bws" 
			help="bandwidth (standard deviation or half width at half maximum) of gaussian smoothing kernel 
			to apply to the peak density chromatogram. Fill in two values separated by comma. First value is used for 
			first grouping round, seccond value is used for last grouping/alignment round after retention time
			correction. "/>
	
	<conditional name="retcor">
		<param name="retcormethod" type="select" size="30" label="retcormethod" 
			help="retention time correction method. 'peakgroups' is the default density based approach, 'obiwarp' is 
			  alignment data by Ordered Bijective Interpolated Warping ">
			<option value="peakgroups" selected="true">peakgroups</option>
			<option value="obiwarp" >obiwarp</option>
		</param>
		<when value="peakgroups">
			<param name="retcorfamily" type="select" size="30" label="retcorfamily" 
				help="retention time correction method type/family">
				<option value="symmetric" selected="true">symmetric</option>
				<option value="gaussian">gaussian</option>
			</param>
			<param name="smooth" type="select" size="30" label="smooth" 
				help="either 'loess' for non-linear alignment or 'linear' for linear alignment">
				<option value="linear" selected="true">linear</option>
				<option value="loess">loess (TODO - waiting for metaMS to add/parse this option)</option>
			</param>
			<param name="missingratio" type="float" size="10" value="0.2" label="missingratio" 
				help="ratio of missing samples to allow in retention time correction groups"/>
			<param name="extraratio" type="float" size="10" value="0.1" label="extraratio" 
				help="ratio of extra peaks to allow in retention time correction correction groups"/>
		</when>
		<when value="obiwarp">
			<param name="profStep" type="integer" size="10" value="1" label="profStep" 
				help="step size (in m/z) to use for profile generation from the raw data files" />
		</when>
	</conditional>
		
	<param name="fillPeaks" type="select" size="30" label="fillPeaks" 
		help="Fill missing peaks in peak groups/alignments that do not include peaks from every sample. 
		This method produces intensity values for those missing samples by integrating raw data in peak group region.">
		<option value="TRUE" selected="true">Yes</option>
		<option value="FALSE">No</option>
	</param>
	<param name="perfwhm" type="float" size="10" value="0.6" label="CAMERA perfwhm =====================================================" 
		help="percentage of FWHM width"/>
	<param name="cor_eic_th" type="float" size="10" value="0.7" label="cor_eic_th" 
		help="correlation threshold (0..1)" />
	<param name="ppm" type="float" size="10" value="5.0" label="ppm" 
		help="General ppm error" />
	
	<param name="groupCorr_graphMethod" type="select" size="30" label="(groupCorr)graphMethod" 
		help="Method selection for grouping peaks after correlation analysis into pseudospectra.">
		<option value="hcs" selected="true">hcs</option>
	</param>
		
	<param name="groupCorr_pval" type="float" size="10" value="0.05" label="(groupCorr)pval" 
		help="significant correlation threshold" />	

	<param name="groupCorr_calcCiS" type="select" size="30" label="(groupCorr)calcCiS" 
		help="Use correlation inside samples for peak grouping">
		<option value="TRUE" selected="true">Yes</option>
		<option value="FALSE">No</option>
	</param>
	
	<param name="groupCorr_calcIso" type="select" size="30" label="(groupCorr)calcIso" 
		help="Use isotopic relationship for peak grouping">
		<option value="TRUE" >Yes</option>
		<option value="FALSE" selected="true">No</option>
	</param>
	
	<param name="groupCorr_calcCaS" type="select" size="30" label="(groupCorr)calcCaS" 
		help="Use correlation across samples for peak grouping">
		<option value="TRUE" >Yes</option>
		<option value="FALSE" selected="true">No</option>
	</param>
	
	
	<param name="findIsotopes_maxcharge" type="integer" size="10" value="3" label="(findIsotopes)maxcharge" 
			help="max. ion charge" />
			
	<param name="findIsotopes_maxiso" type="integer" size="10" value="4" label="(findIsotopes)maxiso" 
			help="max. number of expected isotopes" />	
			
	<param name="findIsotopes_minfrac" type="float" size="10" value="0.5" label="(findIsotopes)minfrac" 
		help="The ratio for the number of samples, which must satisfy the C12/C13 rule for isotope annotation" />					
	
	<param name="findAdducts_polarity" type="select" size="30" label="(findAdducts)polarity" 
		help="Which polarity mode was used for measuring of the ms sample">
		<option value="positive" selected="true">positive</option>
		<option value="negative" >negative</option>
	</param>

	<param name="findAdducts_multiplier" type="integer" size="10" value="3" label="(findAdducts)multiplier" 
			help="If no ruleset is provided, calculate ruleset with max. number n of [nM+x] clusterions" />


	
</inputs>
<configfiles>

<configfile name="customMetaMSsettings">## ====================================
		## metaMS process settings
		customMetaMSsettings &lt;- metaMSsettings(protocolName = "${protocolName}",
                            chrom = "LC",
                            PeakPicking = list(
                              method = "${peakPicking.method}",
							#if $peakPicking.method == "matchedFilter"  
								fwhm = ${peakPicking.fwhm},
								sigma = ${peakPicking.fwhm}/${peakPicking.sigma_denom},
								max = ${peakPicking.max},
								snthresh = ${peakPicking.snthresh},
								step = ${peakPicking.step},
								steps = ${peakPicking.steps},
								mzdiff = ${peakPicking.mzdiff}),
							#else 
								ppm = ${peakPicking.ppm},
								peakwidth = c(${peakPicking.peakwidth}),
								snthresh = ${peakPicking.snthresh},
								prefilter = c(${peakPicking.prefilter}),
								mzCenterFun = "${peakPicking.mzCenterFun}",
								integrate = ${peakPicking.integrate},
								mzdiff = ${peakPicking.mzdiff},
								fitgauss = ${peakPicking.fitgauss},
								noise = ${peakPicking.noise}),
							#end if
                            Alignment = list(
                              min.class.fraction = ${min_class_fraction},
                              min.class.size = ${min_class_size},
                              mzwid = ${mzwid},
                              bws = c(${bws}),
                              retcormethod = "${retcor.retcormethod}",
							#if $retcor.retcormethod == "peakgroups"
                           		smooth = "${retcor.smooth}",
                            	missingratio = ${retcor.missingratio},
                            	extraratio = ${retcor.extraratio},
                            	retcorfamily = "${retcor.retcorfamily}",            
							#else
								##repeating the method as workaround/ backwards compatibility (can remove this one after fix from metaMS):
								method = "${retcor.retcormethod}", 
								profStep = ${retcor.profStep},
							#end if								                             
                              fillPeaks = ${fillPeaks}),
                            CAMERA = list(
                              perfwhm = ${perfwhm},
                              cor_eic_th = ${cor_eic_th},
                              ppm= ${ppm},
                              graphMethod= "${groupCorr_graphMethod}",
                              pval= ${groupCorr_pval},
                              calcCiS= ${groupCorr_calcCiS},
                              calcIso= ${groupCorr_calcIso},
                              calcCaS= ${groupCorr_calcCaS},
                              maxcharge= ${findIsotopes_maxcharge},
                              maxiso= ${findIsotopes_maxiso},
                              minfrac= ${findIsotopes_minfrac},
                              polarity= "${findAdducts_polarity}",
                              multiplier= ${findAdducts_multiplier}
                              ))</configfile>

</configfiles>

<outputs>
	<data name="outputFile" format="tabular" label="${tool.name} on ${on_string} - peaks table (TSV)"/>
	<data name="outputLog" format="txt" label="${tool.name} on ${on_string} - LOG" hidden="True"/>
	<data name="xsetOut" format="rdata" label="${tool.name} on ${on_string} - xcmsSet (RDATA)"/>
	<data name="htmlReportFile" format="html" label="${tool.name} on ${on_string} - report (HTML)"/>
</outputs>
<tests>
	<test>
	</test>
</tests>
<help>

.. class:: infomark
  
Runs metaMS process for LC/MS feature feature picking, aligning and grouping. 
This part of the metaMS process makes use of the XCMS and CAMERA tools and algorithms.
CAMERA is used for automatic deconvolution/annotation of LC/ESI-MS data.
The figure below shows the main parts of the metaMS process. 

.. image:: $PATH_TO_IMAGES/metaMS.png 


**References**

If you use this Galaxy tool in work leading to a scientific publication please
cite the following papers:

Wehrens, R.; Weingart, G.; Mattivi, F. (2014). 
metaMS: an open-source pipeline for GC-MS-based untargeted metabolomics. 
Journal of chromatography B: biomedical sciences and applications, 996 (1): 109-116. 
doi: 10.1016/j.jchromb.2014.02.051 
handle: http://hdl.handle.net/10449/24012

Wrapper by Pieter Lukasse.


  </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>