<tool id="abims_CAMERA_combinexsAnnos" name="CAMERA.combinexsAnnos" version="2.0.1">

    <description>Wrapper function for the combinexsAnnos CAMERA function. Returns a dataframe with recalculated annotations.</description>
    
    <requirements>
        <requirement type="package" version="3.1.2">R</requirement>
        <requirement type="binary">Rscript</requirement>
        <requirement type="package" version="1.44.0">xcms</requirement>
        <requirement type="package" version="1.22.0">camera</requirement>
        <requirement type="package" version="2.1">camera_w4m_script</requirement>
    </requirements>

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

    <command>
        CAMERA.r 
        xfunction combinexsAnnos image_pos $image_pos image_neg $image_neg
        pos $pos tol $tol ruleset $ruleset convert_param $convert_param keep_meta $keep_meta &amp;&amp; (
        mv variableMetadata.tsv $variableMetadata);
        cat xset.log
    </command>

    <inputs>
        <param name="image_pos" type="data" label="Positive RData ion mode" format="rdata.camera.positive,rdata" help="output file from CAMERA.annotate using a positive polarity mode" />
        <param name="image_neg" type="data" label="Negative RData ion mode" format="rdata.camera.negative,rdata" help="output file from CAMERA.annotate using a positive negative mode" />
    
        <param name="pos" type="select" label="Returned peaklist polarity mode">
            <option value="TRUE" selected="true">positive</option>
            <option value="FALSE" >negative</option>
        </param>

        <param name="tol" type="integer" value="2" label="Retention time window in seconds" help="[pos] As first step it searches for pseudospectra from the positive and the negative sample within a retention time window" />
        <param name="ruleset" type="text" value="1,1" label="Matrix of matching rules" help="[ruleset] Matrix of matching rules. By default, the matrix (1,1) would create the M+H/M-H rule, since the first rule of xsa.pos@ruleset and xsa.neg@ruleset is M+H respectively M-H. Only rules with identical charge can be combined!" />
        <param name="convert_param" type="boolean" checked="false" truevalue="TRUE" falsevalue="FALSE" label="Convert retention time (seconds) rtmed, rtmin and rtmax into minutes"/>
        <param name="keep_meta" type="boolean" checked="true" truevalue="TRUE" falsevalue="FALSE" label="Keep only the metabolites which match a difference "/>

    </inputs>

    <outputs>
        <data name="variableMetadata" format="tabular" label="${image_pos.name[:-6]}.combinexsAnnos.variableMetadata.tsv" />
        <!--
        <data name="rdata" format="rdata" label="${image_pos.name[:-6]}.combinexsAnnos.Rdata" />
        -->
    </outputs>

    <tests>
        <test>
            <!-- TODO: generer des vrais dataset pos et neg-->
            <param name="image_pos" value="xset.group.retcor.group.fillPeaks.annotate.positive.Rdata"/>
            <param name="image_neg" value="xset.group.retcor.group.fillPeaks.annotate.negative.Rdata"/>
            <param name="pos" value="TRUE"/>
            <param name="tol" value="2"/>
            <param name="ruleset" value="1,1"/>
            <output name="variableMetadata" file="xset.group.retcor.group.fillPeaks.annotate.positive.combinexsAnnos.variableMetadata.tsv" />
        </test>
    </tests>
    
    
    <help>

.. class:: infomark

**Authors** Carsten Kuhl ckuhl@ipb-halle.de, Ralf Tautenhahn rtautenh@scripps.edu, Steffen Neumann sneumann@@ipb-halle.de

.. class:: infomark

**Galaxy integration** ABiMS TEAM - UPMC/CNRS - Station biologique de Roscoff and Yann Guitton yann.guitton@univ-nantes.fr - part of Workflow4Metabolomics.org [W4M]

 | Contact support@workflow4metabolomics.org for any questions or concerns about the Galaxy implementation of this tool.

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



=======================
Xcms.combinexsAnnos
=======================

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

**What it does?**

This function check annotations of ion species with the help of a sample from opposite ion mode.
As first step it searches for pseudospectra from the positive and the negative sample within a reten-
tion time window. For every result the m/z differences between both samples are matched against
specific rules, which are combinations from pos. and neg. ion species. As example M+H and M-H
with a m/z difference of 2.014552. If two ions matches such a difference, the ion annotations are
changed (previous annotation is wrong), confirmed or added. Returns the peaklist from one ion
mode with recalculated annotations.

**Details**

Both xsAnnotate object should be full processed (grouping and annotation). Without previous anno-
tation the resulting peaklist only includes annotation with matches peaks from both mode according
to the rule(s). With ruleset=NULL the function only looks for M+H/M-H pairs. The ruleset is
a two column matrix with includes rule indices from the rule table of both xsAnnotate objects.
A ruleset (1,1) would create the M+H/M-H rule, since the first rule of xsa.pos@ruleset and
xsa.neg@ruleset is M+H respectively M-H. Only rules with identical charge can be combined!



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


**Upstream tools**

========================= ======================= ===================== ==========
Name                      Output file             Format                Parameter
========================= ======================= ===================== ==========
xcms.annotatediffreport   xset.annotate_POS.RData rdata.camera.positive RData file        			
------------------------- ----------------------- --------------------- ----------
xcms.annotatediffreport   xset.annotate_NEG.RData rdata.camera.positive RData file
========================= ======================= ===================== ==========
  
**Downstream tools**

+---------------------------+-----------------------------------------+--------+
| Name                      | Output file                             | Format |
+===========================+=========================================+========+
|Batch_correction           |xset.combinexsAnnos.variableMetadata.tsv | Tabular|
+---------------------------+-----------------------------------------+--------+
|Filters                    |xset.combinexsAnnos.variableMetadata.tsv | Tabular|
+---------------------------+-----------------------------------------+--------+
|Univariate                 |xset.combinexsAnnos.variableMetadata.tsv | Tabular|
+---------------------------+-----------------------------------------+--------+
|Multivariate               |xset.combinexsAnnos.variableMetadata.tsv | Tabular|
+---------------------------+-----------------------------------------+--------+



The output file **xset.annotateDiffreport.variableMetadata.tsv** is a tabular file. You can continue your analysis using it in the following tools:
    | Batch_correction
    | Filters
    | Univariate
    | Multivariate PCA, PLS and OPLS


**General schema of the metabolomic workflow**

.. image:: combinexsannos_workflow.png


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

+---------------------------+----------------------------+
| Parameter : label         |   Format                   |
+===========================+============================+
| Positive RData ion mode   |   rdata.camera.positive    |
+---------------------------+----------------------------+
| Negative RData ion mode   |   rdata.camera.negative    |
+---------------------------+----------------------------+

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

xset.combinexsAnnos.variableMetadata.tsv

    | A tabular file which is similar to the diffreport result , within additional columns containing the annotation results.
    | For each metabolite (row) :
    | the value of the intensity in each sample, fold, tstat, pvalue, anova, mzmed, mzmin, mzmax, rtmed, rtmin, rtmax, npeaks, isotopes, adduct, pcgroup and neg (or pos). Mode 

xset.combinexsAnnos.Rdata

    | Rdata file, that be used outside Galaxy in R.
    

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

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

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

    | Positive RData ion mode -> **POS.xset.annotateDiffreport.RData**
    | Negative RData ion mode -> **NEG.xset.annotateDiffreport.RData**

Parameters
----------

    | pos -> **positive**
    | tol -> **2 (default)**
    | ruleset -> **1,1 (default)**

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

**Example of an xset.combinexsAnnos.variableMetadata.tsv output:**

.. image:: combinexsannos_variableMetadata.png

    </help>

    <citations>
        <citation type="doi"> 10.1021/ac202450g</citation>
        <citation type="doi">10.1093/bioinformatics/btu813</citation>
    </citations>


</tool>