annotate README @ 1:b02af8eb8e6e draft

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

# VKMZ version 1.0 

VKMZ is a metabolomics vizualization tool which creates van Krevelen diagrams from mass spectrometry data. A van Krevelen diagram (VKD) plots a molecule on a scatterplot based on the molecule's 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 can be used to briefly convey untargeted metabolomics data.

VKMZ can be used as a standalone tool or on the Galaxy Project web platform [1].
## Using VKMZ

VKMZ is designed to use XCMS [2] data as input. Tabular data can also be used as input. For each feature in the data VKMZ attempts to predict it's molecular formula by comparing the features mass to a database of known formula masses. Heristically generated databases for unlabeled and labeled data is included with VKMZ. Users can define their own database. A VKD is created from formulas with predictions and outputed as a webpage and tabular file.

### Input modes

VKMZ has three modes:
  1. `tsv` mode reads a specially formatted tabular file
  2. `xcms` mode reads features in [XCMS](https://bioconductor.org/packages/release/bioc/html/xcms.html) data
  3. `plot` mode replots VKMZ tabular data

Select a mode by declaring it as the first argument to `vkmz.py`.

> **Example:**
> ```
> python vkmz.py xcms [options]
> ```

Different modes take different parameters.

All modes require an output parameter:
  * `--output [FILENAME]`
    * A `.tsv` and/or `.html` will be generated by VKMZ with this paraameter as the file name.
    * A `.tsv` and `.html` files generated by VKMZ are named by this option

All modes allow these options:
  * `--plot-type [scatter-2d]`
  * `--size [INTEGER]`
    * Set base size of marker dots of the VKD
  * `--size-algorithm [{1,2}]`
    * Choose algorithm to modify marker size
      1. Uniform base size
      2. Intensity relative size

#### xcms and tsv modes

Both xcms and tsv mode require the mass error, in parts-per-million, of the mass spectrometer which generated the data:
  * `--error [PPM_ERROR_NUMBER]`

There are several options for xcms and tsv modes:
  * `--database [DATABASE_FILE]`
    * default is BMRB's monoisotopic heuristically generated database [3]
  * `--directory [TOOL_PATH]`
    * define tool directory
  * `--no-plot`
    * disable html plot generation

#### xcms mode

xcms mode requires tabular files generated by XCMS:
  * `--data-matrix [XCMS_DATA_MATRIX_FILE]`
  * `--sample-metadata [XCMS_SAMPLE_METADATAFILE]`
  * `--variable-metadata [XCMS_VARIABLE_METADATAFILE]`

##### xcms mode example:
```
python vkmz.py xcms --data-matrix test-data/datamatrix.tabular --sample-metadata test-data/sampleMetadata.tabular --variable-metadata test-data/variableMetadata.tabular --output report --error 3
```

#### tsv mode

tsv mode requires a tabular file of a specific format as input.
  * `--input [TSV FILE]`

The first five columns of the input tabular file must be:

| sample ID | polarity | mz | retention time | intensity |
|-----------|----------|----|----------------|-----------|

#### plot mode

plot mode reads previously generated VKMZ tabular files to create VKD html files. 

Specifying the VKMZ tabular file is required:
  * `--input [VKMZ_TSV_FILE]`

## Citations

0. Brockman et al. [doi:10.1007/s11306-018-1343-y](https://doi.org/10.1007/s11306-018-1343-y)
1. Galaxy Project [Galaxy](https://github.com/galaxyproject/galaxy)
2. Giacomoni et al. [doi:10.1093/bioinformatics/btu813](https://doi.org/10.1093/bioinformatics/btu813)
3. Hegeman et al. [doi:10.1021/ac070346t](https://doi.org/10.1021/ac070346t)