annotate dimet_enrichment_plot.xml @ 2:2de209fb390b draft

planemo upload for repository https://github.com/galaxyproject/tools-iuc/tree/master/tools/DIMet commit 30fe10acdf65c6917856a0eae21dc91abd2f609f

<tool id="dimet_@EXECUTABLE@" name="dimet @TOOL_LABEL@" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@" profile="20.05">
    <description>
        Figures of mean enrichment by metabolite, as line-plots (by DIMet)
    </description>
    <macros>
        <token name="@TOOL_LABEL@">enrichment plot</token>
        <token name="@EXECUTABLE@">enrichment_plot</token>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements"/>
    <command detect_errors="exit_code"><![CDATA[
    @INIT_CONFIG@
    @INIT_ENRICHMENT_PLOT@
    @INIT_PLOT_CONDITIONS@
    @INIT_TIMEPOINTS@
    @INIT_ENRICHMENT_METABOLITES@
    HYDRA_FULL_ERROR=1 python -m dimet
        -cp '$__new_file_path__/config'
        '++hydra.run.dir=mean_enrichment_line_plot'
        '++figure_path=figures'
        '++table_path=tables'
        '++analysis={
            metabolites:${metabolites},
            dataset:{
                _target_:dimet.data.DatasetConfig,
                name: "Galaxy DIMet run"
            },
            method:{
                _target_: dimet.method.MeanEnrichmentLinePlotConfig,
                label: mean_enrichment_line_plot,
                name: "Generate mean enrichment line plots",
                palette_condition: ${output_options.palette},
                palette_metabolite: auto_multi_color,
                xaxis_title: ${output_options.xaxis_title},
                alpha: ${output_options.alpha},
                plot_grouped_by_dict: null,
                color_lines_by: '${output_options.color_lines_by}',
                height_subplot: ${output_options.height_subplot},
                figure_format:${output_options.figure_format},
                as_grid:${output_options.as_grid}
            },
            width_subplot: '${output_options.width_subplot}',
            label: enrich_lineplot
        }'
        '++analysis.dataset.label='
        '++analysis.timepoints=${timepoints}'
        '++analysis.dataset.subfolder='
        '++analysis.dataset.conditions=${conditions}'

        #if $metadata_path:
             '++analysis.dataset.metadata=metadata'
        #end if
        #if $me_or_frac_contrib_file:
            '++analysis.dataset.mean_enrichment=me_or_frac_contrib'
        #end if
    @REMOVE_CONFIG@
    ]]></command>
    <inputs>
        <expand macro="input_parameters_enrichment"/>
        <expand macro="plot_factor_list"/>
        <expand macro="timepoint"/>
        <expand macro="compartments_enrichment"/>
        <expand macro="enrichment_metabolites_list"/>
        <section name="output_options" title="Output options">
            <param name="figure_format" type="select" value="pdf" display="radio" label="Select output figure format" help="Please enter at max 1 format">
                <option value="pdf">Pdf</option>
                <option value="svg">Svg</option>
            </param>
            <expand macro="palette"/>
            <param name="color_lines_by" type="select" value="condition" display="radio" label="Select color for lines" help="Please enter at max 1 format">
                <option value="condition">Condition</option>
                <option value="metabolite">Metabolite</option>
            </param>
            <param name="alpha" type="float" min="0.0" max="1.0" value="1.0" label="alpha of subfig plots"
                   help="Default value is 1."/>
            <param name="height_subplot" type="float" min="1.0" max="15.0" value="6.4" label="height of subfig plots"
                   help="Default value is 3."/>
            <param name="width_subplot" type="float" min="1.0" max="15.0" value="4.0" label="width of subfig plots"
                   help="Default value is 3."/>
            <param name="as_grid" type="boolean" value="false" label="plot as grid"
                   help="Default value is false."/>
            <param name="xaxis_title" type="text" value="Time" optional="false" label="xaxis_title to add to output files" >
            <sanitizer invalid_char="">
                <valid initial="string.ascii_letters,string.digits">
                    <add value="_" />
                </valid>
            </sanitizer>
        </param>
        </section>
    </inputs>

    <outputs>
        <collection name="report" type="list">
            <discover_datasets pattern="__designation_and_ext__" directory="figures"/>
        </collection>
    </outputs>
    <tests>
        <test>
            <param name="me_or_frac_contrib_file" ftype="tabular" value="FracContribution_C.csv"/>
            <param name="metadata_path" ftype="tabular" value="example2_metadata.csv"/>
            <repeat name="plot_factor_list">
                <param name="condition" value="Control"/>
            </repeat>
            <repeat name="plot_factor_list">
                <param name="condition" value="L-Cycloserine"/>
            </repeat>
            <param name="timepoint" value='T0,T2h'/>
            <param name="compartments" value='cell,med'/>
            <param name="metabolites_list" value="Fumaric_acid,Glycine,L-Proline"/>
            <section name="output_options">
                <param name="alpha" value="1.0"/>
                <param name="height_subplot" value="6.4"/>
                <param name="width_subplot" value="4.0"/>
                <param name="xaxis_title" value="Time"/>
                <param name="color_lines_by" value="condition"/>
                <param name="figure_format" value="svg"/>
            </section>

            <output_collection name="report" type="list" count="6">
                <element file="mean_enrichment-cell-Fumaric_acid.svg"  name="mean_enrichment-cell-Fumaric_acid" ftype="svg" compare="sim_size" delta="100"/>
                <element file="mean_enrichment-cell-Glycine.svg" name="mean_enrichment-cell-Glycine" ftype="svg" compare="sim_size" delta="100"/>
                <element file="mean_enrichment-cell-L-Proline.svg" name="mean_enrichment-cell-L-Proline" ftype="svg" compare="sim_size" delta="100"/>
                <element file="mean_enrichment-med-Fumaric_acid.svg"  name="mean_enrichment-med-Fumaric_acid" ftype="svg" compare="sim_size" delta="100"/>
                <element file="mean_enrichment-med-Glycine.svg" name="mean_enrichment-med-Glycine" ftype="svg" compare="sim_size" delta="100"/>
                <element file="mean_enrichment-med-L-Proline.svg" name="mean_enrichment-med-L-Proline" ftype="svg" compare="sim_size" delta="100"/>
            </output_collection>
        </test>
    </tests>
    <help><![CDATA[
This module is part of DIMet: Differential analysis of Isotope-labeled targeted Metabolomics data (https://pypi.org/project/DIMet/).

DIMet enrichment plot performs line-plot figures for visualization of the (stable isotope) mean enrichment across all the time points present in your data, for each metabolite. All (or selected) metabolites are processed automatically.

The figures in .pdf format are of publication quality, and as they are vectorial images you can open them and customize aesthetics with a professional image software such as Inkscape, Adobe Illustrator, Sketch,  CorelDRAW, etc.


    **Input data files**

For running DIMet @EXECUTABLE@ you need the following .csv files :

- The mean **enrichment** file, and

- The metadata file, a unique file with the description of the samples. This file is compulsory (see section **Metadata File Information**).


The mean enrichment file must be organized as a matrix:

- The first column must contain Metabolite IDs that are unique (not repeated) within the file.

- The rest of the columns correspond to the samples

- The rows correspond to the metabolites

- The values must be tab separated, with the first row containing the sample/column labels.


Example - mean **enrichment** or labeled fractional contributions:

    =============== ================== ================== ================== ================== ================== ==================
    ID              **MCF001089_TD01** **MCF001089_TD02** **MCF001089_TD03** **MCF001089_TD04** **MCF001089_TD05** **MCF001089_TD06**
    =============== ================== ================== ================== ================== ================== ==================
    2_3-PG          0.9711             0.968              0.9909             0.991              0.40               0.9
    2-OHGLu         0.01719            0.0246             0.554              0.555              0.73               0.68
    Glc6P           0.06               0.66               2683               0.06               2068               2172
    Gly3P           0.06               0.06               0.06               1                  5                  3
    IsoCit          0.06               1                  0.49               0.36               6                  10
    =============== ================== ================== ================== ================== ================== ==================



**Metadata File Information**

Provide a tab-separated file that has the names of the samples in the first column and one header row.
Column names must be exactly in this order:

   name_to_plot
   condition
   timepoint
   timenum
   compartment
   original_name


Example **Metadata File**:


    ==================== =============== ============= ============ ================ =================
    **name_to_plot**     **condition**   **timepoint** **timenum**  **compartment**   **original_name**
    -------------------- --------------- ------------- ------------ ---------------- -----------------
    Control_cell_T0-1    Control         T0            0            cell             MCF001089_TD01
    Control_cell_T0-2    Control         T0            0            cell             MCF001089_TD02
    Control_cell_T0-3    Control         T0            0            cell             MCF001089_TD03
    Tumoral_cell_T0-1    Tumoral         T0            0            cell             MCF001089_TD04
    Tumoral_cell_T0-2    Tumoral         T0            0            cell             MCF001089_TD05
    Tumoral_cell_T0-3    Tumoral         T0            0            cell             MCF001089_TD06
    Tumoral_cell_T24-1   Tumoral         T24           24           cell             MCF001089_TD07
    Tumoral_cell_T24-2   Tumoral         T24           24           cell             MCF001089_TD08
    Tumoral_cell_T24-3   Tumoral         T24           24           cell             MCF001090_TD01
    Control_med_T24-1    Control         T24           24           med              MCF001090_TD02
    Control_med_T24-2    Control         T24           24           med              MCF001090_TD03
    Tumoral_med_T24-1    Tumoral         T24           24           med              MCF001090_TD04
    Tumoral_med_T24-2    Tumoral         T24           24           med              MCF001090_TD05
    Control_med_T0-1     Control         T0            0            med              MCF001090_TD06
    Tumoral_med_T0-1     Tumoral         T0            0            med              MCF001090_TD07
    Tumoral_med_T0-2     Tumoral         T0            0            med              MCF001090_TD08
    ==================== =============== ============= ============ ================ =================


The column **original_name** must have the names of the samples as given in your data.

The column **name_to_plot** must have the names as you want them to be (or set identical to original_name if you prefer). To set names that
are meaningful is a better choice, as we will take them to display the results.

The column **timenum** must contain only the numeric part of the timepoint, for example 2,0, 10, 100 (this means, without letters ("T", "t", "s", "h" etc)
nor any other symbol). Make sure these time numbers are in the same units (but do not write the units here!).

The column **compartment** is an abbreviation, coined by you, for the compartments. This will be used for the results' files names: the longer the
compartments names are, the longer the output files' names! Please pick short and clear abbreviations to fill this column.


**Running the analysis**


You can precise how you want your analysis to be executed, with the parameters:

- **conditions**: the conditions present in your data, exactly in the ORDER you want them to appear in the legend of each figure.

- **width_subplot** : the desired width (in inches) for the the individual metabolites' figures

There exist hints on use that will guide you, next to the parameters.

Note that this plot makes sense when you dispose of two or more time-points. If your setup is not a time-series, you may rather use our metabologram integration with the differential mean enrichment (comparing the conditions of your choice).

The output consists of line-plot figures, one by each metabolite.

**Available data for testing**

You can test our tool with the data from our manuscript https://zenodo.org/record/10579862 (the pertinent
files for you are located in the subfolders inside the data folder).
You can also use the minimal data examples from https://zenodo.org/record/10579891

 ]]>
    </help>
    <expand macro="citations"/>
</tool>