annotate nmr_preprocessing/NmrPreprocessing_xml.xml @ 2:7304ec2c9ab7 draft

Uploaded

<tool id="NMR_Preprocessing" name="NMR_Preprocessing" version="1.2.0">
	<description> Preprocessing of 1D NMR spectra </description>

    <stdio>
        <exit_code range="1:" level="fatal" />
    </stdio>
	
  	<command>
  	    ## Wrapper
        Rscript $__tool_directory__/NmrPreprocessing_wrapper.R

	## Data matrix of FID spectra
		dataMatrixFid $dataMatrixFid
			## Sample metadata matrix
		sampleMetadataFid $sampleMetadataFid
		
		
		## First order phase correction
			## Graphical display
		FirstOPCGraph $GDC.FirstOPCGraph
		
		## Water and / or solvents suppression
		    ## Smoothing parameter
        lambda $SS.lambda

			## Graphical display
		SSGraph $SS.SSGraph
		
		
		## Apodization
				## Graphical display
		ApodGraph $Apod.ApodGraph
	
	    apodizationMethod $Apod.apodizationMethod.method
		    #if $Apod.apodizationMethod.method == "exp":
			    ## Line broadening for the exponential window
			    expLB $Apod.apodizationMethod.expLB 
		    #end if
		    #if $Apod.apodizationMethod.method == "cos2":
			    ## Phase
			    phase $Apod.apodizationMethod.phase
		    #end if
		    #if $Apod.apodizationMethod.method == "hanning":
			    ## Phase
			    phase $Apod.apodizationMethod.phase
		    #end if
		    #if $Apod.apodizationMethod.method == "hamming":
			    ## Phase
			    phase $Apod.apodizationMethod.phase
		    #end if
		    #if $Apod.apodizationMethod.method == "blockexp":
			    ## Proportion of signal in the window
			    rectRatio $Apod.apodizationMethod.rectRatio
			    expLB $Apod.apodizationMethod.expLB 
		    #end if			
		    #if $Apod.apodizationMethod.method == "blockcos2":
			    ## Proportion of signal in the window
			    rectRatio $Apod.apodizationMethod.rectRatio
		    #end if			
		    #if $Apod.apodizationMethod.method == "gauss":
			    ## Line broadening for the gaussian window
			    gaussLB $Apod.apodizationMethod.gaussLB 
		    #end if
	
		## Fourier transform
			## Graphical display
			FTGraph $FT.FTGraph
		
		
		
		
		## Zero order phase correction
		## Graphical display
			ZeroOPCGraph $ZOPC.ZeroOPCGraph
			
		zeroOrderPhaseMethod $ZOPC.zeroOrderPhaseMethod
		
		excludeZoneZeroPhase.choice ${ZOPC.excludeZoneZeroPhase.choice}
        #if str($ZOPC.excludeZoneZeroPhase.choice) == "YES":
            #for $i in $ZOPC.excludeZoneZeroPhase.conditions:
                excludeZoneZeroPhase_left ${i.excludeZoneZeroPhase_left}
                excludeZoneZeroPhase_right ${i.excludeZoneZeroPhase_right}
            #end for
        #end if		

    ## Shift referencing
  			## Graphical display
  			SRGraph $SR.SRGraph
  		
  			## Definition of the search zone
  			shiftReferencingRange $SR.shiftReferencingRange.method
  			#if $SR.shiftReferencingRange.method == "nearvalue":
  				pctNearValue $SR.shiftReferencingRange.pctNearValue
  			#end if
  			#if $SR.shiftReferencingRange.method == "window":
  				#for $i in $SR.shiftReferencingRange.conditions:
                 	 	shiftReferencingRangeLeft ${i.shiftReferencingRangeLeft}
                 	 	shiftReferencingRangeRight ${i.shiftReferencingRangeRight}
                 	 #end for
  			#end if
  			shiftHandling $SR.shiftHandling
  			ppmvalue $SR.ppmvalue 
		
		## Baseline correction
		## Graphical display
			BCGraph $BC.BCGraph
			
		  lambdaBc $BC.lambdaBc
		  pBc $BC.pBc
		  epsilon $BC.epsilon
		
		excludeZoneBC.choice ${BC.excludeZoneBC.choice}
        #if str($BC.excludeZoneBC.choice) == "YES":
            #for $i in $BC.excludeZoneBC.conditions:
                excludeZoneBC_left ${i.excludeZoneBC_left}
                excludeZoneBC_right ${i.excludeZoneBC_right}
            #end for
        #end if		

		
		## sets negative intensities to zero
		NegativetoZero $NZ.NegativetoZero
				
		## final spectra
		## Graphical display
			FinalGraph $FinalGraph
			
			
        ## Outputs
        dataMatrix $dataMatrix
        variableMetadata $variableMetadata
		    graphOut $graphOut
		    logOut $logOut
		
	</command>
		
  	<inputs>
		<param name="dataMatrixFid" type="data" label="Data matrix of FIDs" help="" format="tabular" />
		<param name="sampleMetadataFid" type="data" label="Sample metadata matrix" help="" format="tabular" />
		

		<section name="GDC" title="Group Delay Correction" expanded="true">
			<param name="FirstOPCGraph" label="Display the FIDs after 1st order phase correction?" type="select" help="Select 'YES' to display the spectra or 'NO' to not display them ">
					<option value="NO"> NO </option>
					<option value="YES"> YES </option>
			</param>
		</section>
    
    
    <section name="SS" title="Solvent Suppression" expanded="true">
		  <param name="lambda" label="Solvent Suppression: Smoothing parameter" type="float" value="1000000" help="Default value is 1e6"/>
		       	  
  		<param name="SSGraph" label="Display the FIDs after solvent suppression?" type="select" help="Select 'YES' to display the spectra or 'NO' to not display them ">
  				<option value="NO"> NO </option>
  				<option value="YES"> YES </option>
  		</param>
    </section>
    

    <section name="Apod" title="Apodization" expanded="true">
  		<conditional name="apodizationMethod" >
  			<param name="method" label="Apodization: method" type="select" help="Default method is Decreasing Exponential signal. See details below" >
  				<option value="exp"  />
  				<option value="cos2" />
  				<option value="hanning" />
  				<option value="hamming" />
  				<option value="blockexp" />
  				<option value="blockcos2" />
  				<option value="gauss" />
  			</param>
  			<when value="exp">
  				<param name="expLB" type="float" label="Line broadening" value="1" help="Default value is 1" />
  			</when>			
  			<when value="cos2">
  				<param name="phase" type="float" label="Phase" value="0" help="Default value is 0" />
  			</when>
  			<when value="hanning">
  				<param name="phase" type="float" label="Phase" value="0" help="Default value is 0" />
  			</when>
  			<when value="hamming">
  				<param name="phase" type="float" label="Phase" value="0" help="Default value is 0" />
  			</when>
  			<when value="blockexp">
  				<param name="rectRatio" type="float" label="Proportion of signal in the window" value="0.5" help="Default value is 0.5" />
  				<param name="expLB" type="float" label="Line broadening" value="1" help="Default value is 1" />
  			</when>		
  			<when value="blockcos2">
  				<param name="rectRatio" type="float" label="Proportion of signal in the window" value="0.5" help="Default value is 0.5" />
  			</when>		
  			<when value="gauss">
  				<param name="gaussLB" type="float" label="Line broadening" value="0.3" help="Default value is 0.3" />
  			</when>		
  		</conditional>		
  		
  		<param name="ApodGraph" label="Display the FIDs after Apodization?" type="select" help="Select 'YES' to display the spectra or 'NO' to not display them ">
  				<option value="NO"> NO </option>
  				<option value="YES"> YES </option>
  		</param>
		</section>

    <section name="FT" title="Fourier Transform" expanded="true">
  		<param name="FTGraph" label="Display the Fourier transformed spectra?" type="select" help="Select 'YES' to display the spectra or 'NO' to not display them ">
  				<option value="NO"> NO </option>
  				<option value="YES"> YES </option>
  		</param>
  	</section>				

		<section name="ZOPC" title="Zero Order Phase Correction" expanded="true">
  		<param name="zeroOrderPhaseMethod" type="select" label="Zero Order Phase Correction: method" help="Method used to select the angles to rotate the spectra" >
  					<option value="rms" selected="yes"> rms </option>
  					<option value="max" > max </option>
  		</param>
  
  		<conditional name="excludeZoneZeroPhase">
  			<param name="choice" type="select" label="Zero Order Phase Correction: exclusion area(s)" help="Choose if you want to exclude particular zone(s)" >
  				<option value="YES" selected="true" > YES </option>
  				<option value="NO" > NO </option>
  			</param>
  			<when value="YES">
  				<repeat name="conditions" title="Exclusion_zone" min="1">
  					<param name="excludeZoneZeroPhase_left" label="Excusion zone: left border" type="float" value="5.1" />
  					<param name="excludeZoneZeroPhase_right" label="Excusion zone: right border" type="float" value="4.5" />
  				</repeat>
  			</when>
  			<when value="NO">
  			</when>
  		</conditional>		
  
  		<param name="ZeroOPCGraph" label="Display the spectra after the Zero Order Phase Correction?" type="select" help="Select 'YES' to display the spectra or 'NO' to not display them ">
  				<option value="NO"> NO </option>
  				<option value="YES"> YES </option>
  		</param>
  		</section>

    	<section name="SR" title="Shift Referencing" expanded="true">
  		<conditional name="shiftReferencingRange" >
  					<param name="method" label="Shift Referencing: definition of the search zone" type="select" help="Definition of the search zone" >
  						<option value="nearvalue" />
  						<option value="all"  />
  						<option value="window" />
  					</param>
  					
  					<when value="all" />
  					<when value="nearvalue">
  						<param name="pctNearValue" type="float" label="percentage of the ppm axis around the ppm value to look for the reference compound peak" value="0.02" help="Default value is 0.02" />
  					</when>
  					<when value="window">
  						<repeat name="conditions" title="Search_zone">
  						<param name="shiftReferencingRangeLeft" label="Search zone: left border" type="float" value="1" />
  						<param name="shiftReferencingRangeRight" label="Search zone: right border" type="float" value="-1" />
  						</repeat>
  					</when>					
  		</conditional>
  		
  		<param name="shiftHandling" type="select" label="Shift Referencing: shiftHandling" help="How to deal with shifts between spectra on their left and right sides" >
  					<option value="zerofilling" selected="yes"> zerofilling </option>
  					<option value="cut" > cut </option>
  					<option value="circular" > circular </option>
  		</param>
  		
  		<param name="ppmvalue" type="float" label="Shift Referencing: the value of the reference peak in ppm" value="0" help="Default value is 0" />
  		
  			
  		<param name="SRGraph" label="Display the spectra after Shift Referencing?" type="select" help="Select 'YES' to display the spectra or 'NO' to not display them ">
  				<option value="NO"> NO </option>
  				<option value="YES"> YES </option>
  		</param>
    </section>
    
    
		<section name="BC" title="Baseline Correction" expanded="true">
    	<param name="lambdaBc" type="float" label="Baseline Correction: smoothing parameter" value="100000.0" help="Smoothing parameter, generally 1e5 – 1e8. Default value is 100000" />
  		<param name="pBc" type="float" label="Baseline Correction: asymmetry parameter" value="0.05" help="Asymmetry parameter. Default value is 0.05" />
  		<param name="epsilon" type="float" label="Baseline Correction: numerical precision for convergence when estimating the baseline" value="0.00000001" help="Numerical precision for convergence when estimating the 	baseline. Default value is 1e-8" />
  		
  		<conditional name="excludeZoneBC">
  			<param name="choice" type="select" label="Baseline Correction: exclusion area(s)" help="Choose if you want to exclude particular zone(s)" >
  				<option value="YES" > YES </option>
  				<option value="NO" selected="true" > NO </option>
  			</param>
  			<when value="YES">
  				<repeat name="conditions" title="Exclusion_zone" min="1">
  					<param name="excludeZoneBC_left" label="Excusion zone: left border" type="float" value="5.1" />
  					<param name="excludeZoneBC_right" label="Excusion zone: right border" type="float" value="4.5" />
  				</repeat>
  			</when>
  			<when value="NO">
  			</when>
  		</conditional>
  		
  		<param name="BCGraph" label="Display the spectra after Baseline Correction?" type="select" help="Select 'YES' to display the spectra or 'NO' to not display them ">
  				<option value="NO"> NO </option>
  				<option value="YES"> YES </option>
  		</param>
  	</section>		
		
		<section name="NZ" title="Negative intensities to Zero" expanded="true">
  		<param name="NegativetoZero" label="Set negative intensities to zero?" type="select" help="If YES, sets negative intensities to zero">
  			<option value="NO"> NO </option>
  			<option value="YES" selected="yes"> YES </option>
  		</param>
		</section>

		<param name="FinalGraph" label="Display the final spectra?" type="select" help="Select 'YES' to display the spectra or 'NO' to not display them ">
			<option value="YES"> YES </option>		
			<option value="NO"> NO </option>
		</param>
		
		</inputs>	
	
	<outputs>
		<data format="tabular" name="dataMatrix" label="${tool.name}_dataMatrix" />
		<data format="tabular" name="variableMetadata" label="${tool.name}_variableMetadata" />
		<data format="txt" name="logOut" label="${tool.name}_log" />
		<data format="pdf" name="graphOut" label="${tool.name}_graph" />
	</outputs>


 	<tests>
        <test> 
          <param name="dataMatrixFid" value="NMR_ReadFids_dataMatrix.tabular"/>
          <param name="sampleMetadataFid" value="sampleMetadata.tabular"/>
          
          <param name="FirstOPCGraph" value="NO"/>
          
          <param name="lambda" value="1000000" />
        	<param name="SSGraph" value="NO"/>
          
          <conditional name="apodizationMethod">
            <param name="method" value="exp" />
            <param name="expLB" value="1"  />
          </conditional>
          <param name="ApodGraph" value="NO"/>
          
          <param name="FTGraph" value="NO"/>
          
          <param name="zeroOrderPhaseMethod" value="rms" />
            
          <conditional name="excludeZoneZeroPhase" >
            <param name="choice" value="YES" />
            <param name="conditions_0|excludeZoneZeroPhase_left" value="5.1" />
            <param name="conditions_0|excludeZoneZeroPhase_right" value="4.5" />
          </conditional>
          <param name="ZeroOPCGraph" value="NO"/>
          
          <conditional name="shiftReferencingRange">
            <param name="method" value="nearvalue"/>
            <param name="pctNearValue" value="0.02"/> 
          </conditional>
          <param name="shiftHandling" value= "zerofilling"/> 
          <param name="ppmvalue" value="0" />
          <param name="SRGraph"	value="NO"/>	
          
          <param name="lambdaBc" value="100000.0" />
          <param name="pBc" value="0.05" />
          <param name="epsilon" value="0.00000001"/>
          <param name="BCGraph" value="NO"/>
            
          <param name="NegativetoZero" value="YES" />
          
          <param name="FinalGraph" value="YES" />
  
          <output name="dataMatrix" value="NMR_Preprocessing_dataMatrix.tabular" />
  
        </test>
  </tests>
  




	<help>

.. class:: infomark

**Authors** 

Manon Martin ([e-mail]) and Marie Tremblay-Franco ([e-mail]; Galaxy integration)


.. class:: infomark




=====================
Spectra preprocessing
=====================

-----------
Description
-----------

These steps correspond to the following steps in the PEPS-NMR R library (https://github.com/ManonMartin/PEPSNMR):

* Group Delay suppression (First order phase correction)
* Removal of solvent residuals signal from the FID
* Apodization to increase the Signal-to-Noise ratio of the FID
* Fourier transformation
* Zero order phase correction
* Shift referencing to calibrate the spectra with internal compound referencing
* Baseline correction
* Setting of negatives values to 0


-----------------
Workflow position
-----------------

**Upstream tools**

+---------------------------+-------------------------+--------+
| Name                      | Output file             | Format |
+===========================+=========================+========+
|NMR_Read                   | NMR_Read_dataMatrix     | Tabular|
+---------------------------+-------------------------+--------+
|NMR_Read                   | NMR_Read_sampleMetadata | Tabular|
+---------------------------+-------------------------+--------+



**Downstream tools**

+---------------------------+----------------------+--------+
| Name                      | Output file          | Format |
+===========================+======================+========+
|NMR_Alignement             | dataMatrix           | Tabular|
+---------------------------+----------------------+--------+
|NMR_Bucketing              | dataMatrix           | Tabular|
+---------------------------+----------------------+--------+
|Normalization              | dataMatrix           | Tabular|
+---------------------------+----------------------+--------+
|Univariate                 | variableMetadata     | Tabular|
+---------------------------+----------------------+--------+
|Multivariate               | sampleMetadata       | Tabular|
+---------------------------+----------------------+--------+
|                           | variableMetadata     | Tabular|
+---------------------------+----------------------+--------+


-----------
Input files
-----------


+--------------------------------+-----------------+
| File                           |   Format        |
+================================+=================+
|1 : dataMatrix                  |   tabular       |
+--------------------------------+-----------------+
|2 : sampleMetadata              |   tabular       |
+--------------------------------+-----------------+
 
| 
 
**dataMatrix file**
sample x variable matrix with tabular separations and "." as decimal; the table must not contain metadata apart from row and column names; the row names must be identical to the rownames of the sample metadata.


**sampleMetadata file**
sample x metadata matrix with tabular separations and "." as decimal for numeric metadata and NA for missing values.


----------------------
  Steps parameters 
----------------------

**Solvent Suppression**
-----------------------------------

**Smoothing parameter** lambda: The higher lambda is, the smoother the estimated solvent signal will be


**Apodization**
----------------------

The **types of apodization** are:

* exp: The signal is multiplied by a decreasing exponential exp(-t/LineBroadening).

* cos2: The signal is multiplied by the value of a cosinus squared from 0 (where its value is 1) until pi/2 (where its value is 0).

* blockexp: The first part of the signal (described by the proportion of signal in the window) is left unchanged and the second is multiplied by exp(-t/LineBroadening) starting at value 1.

* blockcos2: The first part is left unchanged as with blockexp and the second part is multiplied by a cosinus squared where its value starts at 1 at the end of the block and ends at 0 at the end of the signal.

* gauss: The signal is multiplied by a gaussian window centered at the beginning of the FID and with sigma=1/LineBroadening.

* hanning: The signal is multiplied by a hanning window : 0.5 + 0.5 cos.

* hamming: The signal is multiplied by a hamming window : 0.54 + 0.46 cos.




**Zero Order Phase Correction**
-----------------------------------

**Zero Order Phase correction method**:

* rms: A positiveness criterion is applied on the spectrum with a quantile probability parameter to trim the values.

* max: Optimization of the maximal spectral intensity.


**Exclusion area(s) for the Zero Order Phase Correction**: enables to optimize the criterion with excluded spectral window(s), by default the water region is excluded.


**Shift Referencing**
----------------------

The **searching window** can be adapted:

* nearvalue: the search concentrates around the value of the reference peak in ppm.

* all: search accross the whole ppm axis.

* window: the search is operated in the windows defined by the Search_zone bounds.


**shiftHandling**: spectra can be shifted differently, we can handle misalignment of the left and right of the spectrum by different ways:

* zerofilling: The extremities at which a spectrum is not defined are replaced by 0. It makes sense since in practice the spectrum is close to zero at the extremities.

* NAfilling: The extremities at which a spectrum is not defined are replaced by NA. 

* circular: The spectra are shifted circularly which means that the end of a spectrum is reproduced at the beginning. 

* cut: The ppm values for which some spectra are not defined are removed.


**value of the reference peak**: the value in ppm of the reference peak. By default the value is 0 ppm.



**Baseline Correction**
----------------------------

**Smoothing parameter**: the larger it is, the smoother the estimated baseline will be.

**Asymmetry parameter**:  the smaller it is, the less the estimated baseline will try to follow peaks when it is under the spectrum and the more it will try to be under the spectrum.

**numerical precision**:  numerical precision for convergence when estimating the baseline. 

**Exclusion area(s) for the Baseline Correction**: enables to optimize the criterion with excluded spectral window(s), by default the water region is excluded.



**Negative intensities to Zero**
------------------------------------
**Set negative intensities to zero**: the set of negative intensities to zero is optional.


------------
Output files
------------

NMR_Preprocessing_dataMatrix
	| tabular output
	| Data matrix with n rows (descriptors) and p columns (samples) containing the preprocessed spectra.
	|

NMR_Preprocessing_variableMetadata
	| tabular output
	| Data matrix with 1 row (ppm value) and p columns (descriptors).
	|
	
NMR_Preprocessing_log
	| text output
	| Contains warnings and the input parameters
	|
	
NMR_Preprocessing_graph.pdf
	| pdf output
	| line plots of preprocessed spectra
	|

   </help>
    
   <citations>
     
     <citation type="bibtex">@PhDThesis{Rousseau2011,
      title = {Statistical contribution to the analysis of metabonomics data in $^1$H NMR spectroscopy},
      author = {Rousseau, R.},
      school = {Institut de Statistique, Biostatistique et Sciences Actuarielles, Universit{\'e} catholique de Louvain},
      year = {2011}}
      </citation>
      
    </citations>
 
</tool>