annotate vkmz.xml @ 0:0b8ddf650752 draft

planemo upload for repository https://github.com/HegemanLab/VKMZ commit 7c299d22bdce251ce599cd34df76919d297a7007-dirty

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

  <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 $no_adjustment=="True":
      --no-adjustment
    #end if
    --output vkmz
    --error $prediction.error
    --database $prediction.database_type.database
    --size $diagram.size
    --size-algorithm $diagram.sizealgorithm
    --directory $__tool_directory__/
  ]]></command>

  <inputs>
    <conditional name="mode">
      <param name="mode_selector" type="select" label="Input data type">
        <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>
    <param name="no_adjustment" label="Turn off mass adjustment" type="boolean" truevalue="True" help="Turn off polarity based mass adjustment. No adjustment should always be selected if reprocessing data generated by VKMZ." />
    <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>
    </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 Modes**

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.

**Mass adjustment**

To calculate a features nominal mass VKMZ adjusts masses by removing or adding the mass of a proton based on polarity.

Mass adjustment should be turned off if using nominal mass data. VKMZ tabular output contains nominal masses.

**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 the mass error option to the mass error, in parts per million, of the mass spectrometer which collected the initial data. 

Heuristically generated databases for unlabeled and labeled formulas are included with VKMZ [2]. Custom database can also be set.

**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>