annotate NmrPreprocessing_xml.xml @ 2:5e64657b4fe5 draft

planemo upload for repository https://github.com/workflow4metabolomics/nmr_preprocessing commit 22ca8782d7c4c0211e13c95b425d4f29f53f995e

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

    <macros>
        <import>macros.xml</import>
    </macros>

    <expand macro="requirements">
        <requirement type="package" version="1.9_12">r-ptw</requirement>
        <requirement type="package" version="1.2_12">r-matrix</requirement>
    </expand>

    <expand macro="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"/>
            <section name="GDC">
                <param name="FirstOPCGraph" value="NO"/>
            </section>
            <section name="SS">
                <param name="lambda" value="1000000" />
                <param name="SSGraph" value="NO"/>
            </section>
            <section name="Apod">
                <conditional name="apodizationMethod">
                    <param name="method" value="exp" />
                    <param name="expLB" value="1"  />
                </conditional>
                <param name="ApodGraph" value="NO"/>
            </section>
            <section name="FT">
                <param name="FTGraph" value="NO"/>
            </section>
            <section name="ZOPC">
                <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"/>
            </section>
            <section name="SR">
                <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"/>
            </section>
            <section name="BC">
                <param name="lambdaBc" value="100000.0" />
                <param name="pBc" value="0.05" />
                <param name="epsilon" value="0.00000001"/>
                <param name="BCGraph" value="NO"/>
            </section>
            <section name="NZ">
                <param name="NegativetoZero" value="YES" />
            </section>
            <param name="FinalGraph" value="YES" />
            <output name="dataMatrix" value="NMR_Preprocessing_dataMatrix.tabular" />
        </test>
    </tests>

    <help>

@HELP_AUTHORS@


=====================
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_CHANGELOG@

    </help>

    <expand macro="citation" />

</tool>