annotate NmrNormalization_xml.xml @ 6:221cbd549c40 draft default tip

planemo upload for repository https://github.com/workflow4metabolomics/normalization commit 4bbd4d65e954192aff1a4d210001deb625667136

<tool id="normalization" name="Normalization" version="1.0.7">

    <description> Normalization of (preprocessed) spectra </description>

    <requirements>
          <requirement type="package" version="1.1_4">r-batch</requirement>
    </requirements>

      <stdio>
        <exit_code range="1:" level="fatal" />
    </stdio>

    <command><![CDATA[
        Rscript $__tool_directory__/NmrNormalization_wrapper.R

            ## Data matrix of bucketed and integrated spectra
            dataMatrix $dataMatrix

            ## Normalization method
            scalingMethod $scalingMethod.method
            #if $scalingMethod.method == "PQN":
                ## Sample metadata matrix
                sampleMetadata $scalingMethod.sampleMetadata

                ## Biological factor of interest (column number in samplemetadata)
                factor $scalingMethod.factor

                ## Reference class
                controlGroup $scalingMethod.controlGroup
            #end if
            #if $scalingMethod.method == "QuantitativeVariable":
                ## Sample metadata matrix
                sampleMetadata $scalingMethod.sampleMetadata

                ## Biological factor of interest (column number in samplemetadata)
                factor $scalingMethod.factor
            #end if

            ## Spectra representation
            graphType $graphType

            ## Outputs
            logOut $logOut
            dataMatrixOut $dataMatrixOut
            graphOut $graphOut
    ]]></command>

    <inputs>
        <param name="dataMatrix" type="data" label="Data matrix of preprocessed data" help="" format="tabular" />

        <conditional name="scalingMethod" >
            <param name="method" label="Normalization method" type="select" help="Default method is total intensity" >
                <option value="None">None normalization</option>
                <option value="Total">Total intensity</option>
                <option value="PQN">Probabilistic Quotient Normalization</option>
                <option value="QuantitativeVariable">Quantitative variable</option>
            </param>
            <when value="None" />
            <when value="Total" />
            <when value="PQN">
                <param name="sampleMetadata" type="data" label="Sample metadata matrix" help="" format="tabular" />
                <param name="factor" label="Name of the column of the biological factor of interest (for PQN method)" type="text" />
                <param name="controlGroup" label="Name of reference level for PQN normalization" type="text" help=""/>
            </when>
            <when value="QuantitativeVariable">
                <param name="sampleMetadata" type="data" label="Sample metadata matrix" help="" format="tabular" />
                <param name="factor" label="Name of the column of the numerical variable for normalization (weight, osmolality, ...)" type="text" />
            </when>
        </conditional>

        <param name="graphType" label="Spectra representation" type="select" help="Select 'None' for no representation,'Overlay' to overlay all spectra on a unique chart and 'One per individual' to generate an individual chart for each observation">
            <option value="None"> none </option>
            <option value="Overlay"> Overlay </option>
            <option value="One_per_individual"> One_per_individual </option>
        </param>
    </inputs>


    <outputs>
        <data format="txt" name="logOut" label="${tool.name}_log" />
        <data format="tabular" name="dataMatrixOut" label="${tool.name}_dataMatrix" />
        <data format="pdf" name="graphOut" label="${tool.name}_spectra" >
            <filter> graphType != "None" </filter>
        </data>
    </outputs>

  <tests>
        <test>
            <param name="dataMatrix" value="MTBLS1_bucketedData.tabular.tsv" ftype="tabular" />
            <conditional name="scalingMethod" >
                <param name="method" value="Total" />
            </conditional>
            <param name="graphType" value="Overlay" />
            <output name="dataMatrixOut" file="MTBLS1_bucketedData_normalized.tabular" />
        </test>
    </tests>

    <help>

.. class:: infomark

**Authors** Marie Tremblay-Franco ([e-mail]) and Marion Landi ([e-mail])
  MetaboHUB: The French National Infrastructure for Metabolomics and Fluxomics (https://www.metabohub.fr/home.html)

---------------------------------------------------

.. class:: infomark

**Please cite**

F. Dieterle, A. Ross, G. Schlotterbeck, and H. Senn (2006). Probabilistic Quotient Normalization as Robust Method to Account for Dilution of Complex Biological Mixtures. Application in 1H NMR Metabonomics.
Analytical Chemistry 78(13): 4281-4290.

---------------------------------------------------

===============
 Normalization
===============

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

Normalization (operation applied on each (preprocessed) individual spectrum) of preprocessed data

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

**Upstream tools**

+----------------------+------------------------------------+---------+-------------+
| Name                 | output file                        | format  | parameter   |
+======================+====================================+=========+=============+
| NMR_Bucketing        | Normalization_bucketedData.tsv     | tabular | Ions Matrix |
+----------------------+------------------------------------+---------+-------------+




**Downstream tools**

+---------------------------+----------------------+--------+
| Name                      | Output file          | Format |
+===========================+======================+========+
|Univariate                 | variableMetadata.tsv | Tabular|
+---------------------------+----------------------+--------+
|Multivariate               | sampleMetadata.tsv   | Tabular|
+---------------------------+----------------------+--------+
|                           | variableMetadata.tsv | Tabular|
+---------------------------+----------------------+--------+


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

+---------------------------+------------+
| Parameter : num + label   |   Format   |
+===========================+============+
| DataMatrix                |   Tabular  |
+---------------------------+------------+

**DataMAtrix**

    | variable x sample dataMatrix tabular separated file containing (preprocessed) spectra, with . as decimal, and NA for missing values


----------
Parameters
----------

DataMatrix
    | see "Input files" section above
    |

Normalization method
    | normalization to apply on each spectrum:

+---------------------------+--------------------------------------+
| Name                      | Normalization                        |
+===========================+======================================+
|None                       | No                                   |
+---------------------------+--------------------------------------+
|Total                      | Total intensity                      |
+---------------------------+--------------------------------------+
|PQN                        | Probabilistic Quotient Normalization |
+---------------------------+--------------------------------------+
|QuantitativeVariable       | Weight, osmolality, ...              |
+---------------------------+--------------------------------------+


sampleMetadata
    | sample x metadata **sample** tabular separated file of the numeric and/or character sample metadata, with . as decimal and NA for missing values
    | Mandatory for "PQN" or "Quantitative" normalization method
    | The row names must be identical to the column names of the dataMatrix file
    |


Spectra representation:
    | Graphical chart of bucketed and integrated raw files
    | If "Overlay": the n (sample number) spectra are overlaid on the same figure
    | If "One_per_individual": pdf file includes n pages (1 per sample)
    |


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


dataMatrix.tsv
    | tabular output
    | Data matrix with p rows (variable) and n columns (samples) containing the intensities
    |

spectra.pdf
    | pdf output
    | Graphical chart of bucketed and integrated data
    |


---------------------------------------------------

---------------
Working example
---------------


.. class:: warningmark

Under construction

.. image:: ./static/images/Mth_Travaux.png
        :width: 100


---------------------------------------------------

--------------
Changelog/News
--------------
**Version 1.0.7 - 25/09/2018**

- Bug fixing for PQN normalization in case of zero's

**Version 1.0.3 - 30/01/2017**

- BUGFIX: Fix a bug: stack overflow for integers

**Version 1.0.2 - 22/10/2016**

- NEW: this tool was previously named NMR Normalization. It had been generalize to deal with all kind of preprocessed data

**Version 1.0.1 - 14/04/2016**

- TEST: refactoring to pass planemo test using conda dependencies

**Version 2015-01-28 - 28/01/2015**

   </help>
    <citations>
        <citation type="doi">10.1093/bioinformatics/btu813</citation>
    </citations>
</tool>