annotate vkmz.xml @ 5:04079c34452a draft

planemo upload for repository https://github.com/HegemanLab/VKMZ commit 3e37abe007f126480b9b748ad5322755445ac95b-dirty

<tool id="VKMZ" name="VKMZ" version="1.1.1">

  <description>metabolomics formula prediction and van Krevelen diagram generation</description>
  
  <requirements>
    <requirement type="package" version="2.7">python</requirement>
    <requirement type="package">pandas</requirement>
    <requirement type="package">plotly</requirement>
  </requirements>
  
  <stdio>
    <exit_code range="1:" level="fatal" />
  </stdio>

  <command detect_errors="aggressive"><![CDATA[
    python $__tool_directory__/vkmz.py
    #if str( $mode.mode_selector ) == "xcms":
      xcms
      --data-matrix $mode.datamatrix
      --sample-metadata $mode.samplemetadata
      --variable-metadata $mode.variablemetadata
    #elif str( $mode.mode_selector ) == "tsv":
      tsv
      --input $mode.input
    #end if
    #if $advanced_input.polarity=="negative":
      --polarity negative
    #else if $advanced_input.polarity=="positive":
      --polarity positive
    #end if
    #if $advanced_input.no_adjustment=="True":
      --no-adjustment
    #end if
    --output vkmz
    --error $prediction.error
    --database $prediction.database_type.database
    #if $prediction.unique=="True":
      --unique
    #end if
    --size $diagram.size
    --size-algorithm $diagram.sizealgorithm
    --directory $__tool_directory__/
  ]]></command>

  <inputs>
    <conditional name="mode">
      <param name="mode_selector" type="select" label="Input Data">
        <option value="xcms">xcms</option>
        <option value="tsv">tsv</option>
      </param>
      <when value="xcms">
        <param name="datamatrix" label="XCMS Data Matrix" type="data" format="tabular" help="Select XCMS data matrix" />
        <param name="samplemetadata" label="XCMS Sample Metadata" type="data" format="tabular" help="Select XCMS sample metadata" />
        <param name="variablemetadata" label="XCMS Variable Metadata" type="data" format="tabular" help="Select XCMS variable metadata" />
      </when>
      <when value="tsv">
        <param name="input" label="Tabular input" type="data" format="tabular" help="Select tabular data" />
      </when>
    </conditional>
    <section name="advanced_input" title="Advanced Input Options" expanded="false">
      <param name="polarity" label="Override polarity" type="select" help="Set polarity for all samples ignoring input files">
        <option value="NA">No override</option>
        <option value="negative">Negative</option>
        <option value="positive">Positive</option>
      </param>
      <param name="no_adjustment" label="Disable polarity based mass adjustment" type="boolean" truevalue="True" help="Use this option if data contains neutral masses." />
    </section>
    <section name="prediction" title="Prediction Options" expanded="true">
      <param name="error" label="Mass Error (PPM)" type="float" value="3.0" min="0" help="Set according to mass spectrometer's mass error in parts-per-million" />
      <conditional name="database_type">
        <param name="database_type_selector" type="select" label="Database Type">
          <option value="heuristic">Heuristically Generated</option>
          <option value="custom">Custom</option>
        </param>
	<when value="heuristic">
          <param name="database" label="Database" type="select" help="Select heuriestically generated database">
            <option value="databases/bmrb-light.tsv">Monoisotopic</option>
            <option value="databases/bmrb-heavy_carbon.tsv">C13 Labeled</option>
            <option value="databases/bmrb-heavy_nitrogen.tsv">N15 Labeled</option>
            <option value="databases/bmrb-heavy.tsv">C13 and C15 Labeled</option>
          </param>
        </when>
        <when value="custom">
          <param name="database" label="Database" type="data" format="tabular" help="Select a custom tabular database" />
        </when>
      </conditional>
      <param name="unique" label="Unique matches" type="boolean" truevalue="True" help="Only output features with a single prediction" />
    </section>
    <section name="diagram" title="Diagram Options" expanded="true">
      <param name="size" label="Minimum Maker Size" type="integer" value="5" min="0" help="Set the base size of diagram's markers" />
      <param name="sizealgorithm" label="Marker Size Algorithm" type="select" help="Select algorithm to change marker sizes. 1.) Set all markers to the base size, 2.) Marker sizes are relative to feature's log intensity">
        <option value="0">Uniform</option>
        <option value="1">Relative Log Intensity</option>
      </param>
    </section>
  </inputs>

  <outputs>
    <data format="tabular" name="output" from_work_dir="vkmz.tsv" label="${tool.name}_${mode.mode_selector}_tabular" />
    <data format="html" name="output_html" from_work_dir="vkmz.html" label="${tool.name}_${mode.mode_selector}_html" />
  </outputs>

  <tests>
    <test>
      <conditional name="mode">
        <param name="mode_selector" value="xcms" />
        <param name="datamatrix" value="datamatrix.tabular" />
        <param name="samplemetadata" value="sampleMetadata.tabular" />
        <param name="variablemetadata" value="variableMetadata.tabular" />
      </conditional>
      <param name="error" value="3" />
      <param name="database" value="databases/bmrb-light.tsv" />
      <output name="output">
        <assert_contents>
          <has_text text="0.00016357" />
        </assert_contents>
      </output>
    </test>
    <test>
      <conditional name="mode">
        <param name="mode_selector" value="tsv" />
        <param name="input" value="tabular.tabular" />
      </conditional>
      <param name="error" value="3" />
      <conditional name="database_type">
        <param name="database" value="databases/bmrb-light.tsv" />
      </conditional>
      <output name="output">
        <assert_contents>
          <has_text text="0.00016357" />
        </assert_contents>
      </output>
    </test>

  </tests>

  <help><![CDATA[
========
VKMZ 1.0
========

VKMZ is a metabolomics prediction and vizualization tool which creates van Krevelen diagrams from mass spectrometry data. A van Krevelen diagram (VKD) plots a molecule on a scatterplot by the molecules oxygen to carbon ratio (O:C) against it's hydrogen to carbon ratio (H:C). Classes of metabolites cluster together on a VKD [0]. Plotting a complex mixture of metabolites on a VKD briefly conveys untargeted metabolomics data.

=============
Documentation
=============

**Input Data**

VKMZ is designed to use XCMS [1] data as input. Tabular data can also be used as input.

*XCMS* mode requires three files which XCMS generates: the data matrix, sample metadata, and variable metadata files.

*Tabular* mode requires a tab delimited file with the first five columns being: sample_id, polarity, mz, retention_time, and intensity.

**Advanced Input Options**

*Override polarity* allows users to set the polarity of all features to either positive or negative. This option should not be used if data contains both polarity types.

*Disable mass adjustment* prevents converting charged masses to neutral masses. If you are using neutral mass data this option should be used.

**Prediction Options**

For each feature in the data VKMZ attempts to predict a molecular formula by comparing the feature's mass to a database of known formula masses. A prediction is made when a known mass is within a mass error of the observed mass. VKMZ finds all predictions for an observed mass within the mass error. The prediction with the lowest delta, absolute difference between observed and known mass, is plotted. Features without predictions are discarded. Using low resolution data may result in finding too many predictions per feature to be useful, especially for large mass metabolites.
 
Set *Mass error* to the mass error, in parts per million, of the mass spectrometer which collected the data. 

*Database* can be set to heuristically generated databases for unlabeled and labeled chemcials [2] or to a custom database.

*Unique matches* removes features from the output which have multiple predictions. Low mass molecules are less affected by this filter than high mass molecules.

**Diagram Options**

Predicted features are plotted as markers. The size of each marker is determined by the minimum marker size and a marker size algorithm. The marker size algorithms use minimum marker size as a variable. 
  ]]></help>

  <citations>
    <citation type="doi">10.1007/s11306-018-1343-y</citation>
    <citation type="doi">10.1021/ac051437y</citation>
    <citation type="doi">10.1021/ac070346t</citation>
  </citations>

</tool>