comparison vkmz.xml @ 6:35b984684450 draft

planemo upload for repository https://github.com/HegemanLab/VKMZ commit 5ef8d2b36eb35ff5aad5d5e9b78c38405fc95c1a

5:04079c34452a

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

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

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

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

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

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

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

6:35b984684450

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

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

    --error $prediction.error
    --database $prediction.database_type.database
    #if $prediction.unique=="True":
      --unique
    #end if
    --directory $__tool_directory__/
  ]]></command>

  <inputs>
    <conditional name="mode">

      <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="Force the polarity of all samples">
        <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="10.0" min="0" help="Set according to expected 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>

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

        <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="10" />
      <param name="database" value="databases/bmrb-light.tsv" />
      <output name="output">
        <assert_contents>
          <has_text text="0.00016357" />
        </assert_contents>

    <test>
      <conditional name="mode">
        <param name="mode_selector" value="tsv" />
        <param name="input" value="tabular.tabular" />
      </conditional>
      <param name="error" value="10" />
      <conditional name="database_type">
        <param name="database" value="databases/bmrb-light.tsv" />
      </conditional>
      <output name="output">
        <assert_contents>

    </test>

  </tests>

  <help><![CDATA[
==========
VKMZ 1.2.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] or tabular data 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*. Set this if input does not contain the correct polarity information. This option should not be used if data contains both positive and negative polarity.

*Disable mass adjustment* prevents converting charged masses to neutral masses.

**Prediction Options**

For each feature VKMZ attempts to predict a molecular formula by comparing the feature's uncharged mass to a database of known formula masses. A prediction is made when a known mass is within a mass error of observed, uncharged, mass. VKMZ finds all predictions for an observed mass within a specified 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.
 
*Mass error* sets the mass error in parts per million. Mass error will be specific to your mass spectrometer, calibration and other methods. Mass error can be approximated by running similar methods with targeted standards with a range in mass.

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

*Unique matches* removes features from the output which have multiple predictions. High mass molecules are affected by this filter more than low mass molecules. This is due to the increased number of possible elemental combinations at a higher mass.

**Tabular Output**

Tabular output contians the columns: sample_id, polarity, mz, rt (retentnion time), intensity, predictions (list of list-elements which contains: predicted mz, predicted formula, and predicted delta), hc (hydrogen to carbon ratio), oc, nc.

**HTML Output**

The HTML web page is an interactive van Krevelen diagram for exploring data.

Predicted features are plotted as circle symbols.

*Min Size* and *Max Size* sets the minimal and maximum area of symbols (absolute scaling).

The *Sizer* dropdown sets the algorithm to size each symbol.

  * *Uniform* sets the symbols of all features to the *Max Size*.
  * *Relative Intensity* sets the symbol size of each feature by the feature's intensity divided by the maxium intensity in the dataset mutiplied by the *Maxium Symbol Size*.
  * *Relative Log Intensity* sets the symbol size of each feature by the feature's log intensity divided by the maxium log intensity in the dataset mutiplied by the *Maxium Symbol Size*.

*Threshold* is a slider which removes low-intensity features. The slider exponentially scales.

  * Setting the slider to 50% removes features with intensities lower than 25% of the maximum inensity.
  * Setting the slider to 75% removes features with intensities lower than 50% of the maximum inensity.

*x-axis* and *y-axis* allow setting axis to alternate elemental ratios.

*Opacity* sets the opacity of feature symbols.

*Visible Samples* sets the visibility of features from given sample IDs. Checked samples are visible. By default all samples are visible.
 
  ]]></help>

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