annotate univariate_config.xml @ 2:09799fc16bc6 draft

planemo upload for repository https://github.com/workflow4metabolomics/univariate.git commit 2c0d4d97c208edca1ada2035a7b7af9c4eb31afe

<tool id="Univariate" name="Univariate" version="2.1.4">
  <description>Univariate statistics</description>
  
  <requirements>
    <requirement type="package" version="3.2.2">R</requirement>
    <requirement type="package">r-batch</requirement>
    <requirement type="package">r-PMCMR</requirement>
  </requirements>

  <stdio>
    <exit_code range="1:" level="fatal" />
  </stdio>
  
  <command><![CDATA[
  Rscript $__tool_directory__/univariate_wrapper.R

  dataMatrix_in "$dataMatrix_in"
  sampleMetadata_in "$sampleMetadata_in"
  variableMetadata_in "$variableMetadata_in"
  
  facC "$facC"
  tesC "$tesC"
  adjC "$adjC"
  thrN "$thrN"	  
  
  variableMetadata_out "$variableMetadata_out"
  information "$information"
  ]]></command>
  <inputs>
    <param name="dataMatrix_in" label="Data matrix file" type="data" format="tabular" help="variable x sample, decimal: '.', missing: NA, mode: numerical, sep: tabular" />
    <param name="sampleMetadata_in" label="Sample metadata file" type="data" format="tabular" help="sample x metadata, decimal: '.', missing: NA, mode: character and numerical, sep: tabular" />
    <param name="variableMetadata_in" label="Variable metadata file" type="data" format="tabular" help="variable x metadata, decimal: '.', missing: NA, mode: character and numerical, sep: tabular"  />
    <param name="facC" label="Factor of interest" type="text" help="Name of the column of the sample metadata table corresponding to the qualitative or quantitative variable"/>
    <param name="tesC" label="Test" type="select" help="">
      <option value="ttest">ttest (qualitative, 2 levels)</option>
      <option value="wilcoxon">Wilcoxon test (qualitative, 2 levels)</option>      
      <option value="anova">Analysis of variance (qualitative, more than 2 levels)</option>
      <option value="kruskal">Kruskal-Wallis rank test (qualitative, more than 2 levels)</option>
      <option value="pearson">Pearson correlation test (quantitative)</option>
      <option value="spearman">Spearman correlation rank test (quantitative)</option>
    </param>
    <param name="adjC" label="Method for multiple testing correction" type="select" help="">
      <option value="fdr">fdr</option>
      <option value="BH">BH</option>
      <option value="bonferroni">bonferroni</option>
      <option value="BY">BY</option>
      <option value="hochberg">hochberg</option>
      <option value="holm">holm</option>
      <option value="hommel">hommel</option>
      <option value="none">none</option>
    </param>
    <param name="thrN" type="float" value="0.05" label="(Corrected) p-value significance threshold" help="Must be between 0 and 1"/>
  </inputs>
  
  <outputs>
    <data name="variableMetadata_out" label="${tool.name}_${variableMetadata_in.name}" format="tabular" ></data>
    <data name="information" label="${tool.name}_information.txt" format="txt"/>
  </outputs>
  
  <tests>
    <test>
      <param name="dataMatrix_in" value="dataMatrix.tsv"/>
      <param name="sampleMetadata_in" value="sampleMetadata.tsv"/>
      <param name="variableMetadata_in" value="variableMetadata.tsv"/>
      <param name="facC" value="ageGroup"/>
      <param name="tesC" value="kruskal"/>
      <param name="adjC" value="fdr"/>
      <param name="thrN" value="0.05"/>
      <output name="variableMetadata_out" file="output-variableMetadata.tsv"/>
    </test>
  </tests>
  
  <help>

.. class:: infomark

| **Tool update: See the 'NEWS' section at the bottom of the page**

---------------------------------------------------

.. class:: infomark

**Authors**

| **Marie Tremblay-Franco ([e-mail])** and **Etienne Thevenot ([e-mail])** wrote this wrapper of R univariate statistical tests.
| MetaboHUB: The French National Infrastructure for Metabolomics and Fluxomics (http://www.metabohub.fr/en)

---------------------------------------------------

.. class:: infomark

**Please cite**

R Core Team (2013). R: A language and Environment for Statistical Computing. http://www.r-project.org

---------------------------------------------------

.. class:: infomark

**References**

| Benjamini Y. and Hochberg Y. (1995). Controlling the false discovery rate: a practical and powerful approach for multiple testing. Journal of the Royal Statistical Society. Series B (Methodological), 57:289-300.
| Dalgaard P. (2002). Introductory statistics with R. Springer.
| Kvam P. and Vidakovic B. (2007). Nonparametric statistics with applications to science and engineering. Wiley.
| Van Belle G., Fisher L., Heagerty P. and Lumley T. (2004). Biostatistics - a methodology for the health sciences. Wiley.
| Pohlert T. (2015). PMCMR: Calculate pairwise multiple comparisons of mean rank sums. R package on CRAN.

---------------------------------------------------

=====================
Univariate statistics
=====================

-----------
Description
-----------

| The module performs two sample tests (t-test and Wilcoxon rank test), analysis of variance and Kruskal-Wallis rank test, and correlation tests (by using either the pearson or the spearman correlation)

-----------------
Workflow position
-----------------

.. image:: univariate_workflowPositionImage.png
        :width: 584

-----------
Input files
-----------

+------------------------------+------------+
| File                         |   Format   |
+==============================+============+
| 1)  Data matrix              |   tabular  |
+------------------------------+------------+
| 2)  Sample metadata          |   tabular  |
+------------------------------+------------+
| 3)  Variable metadata        |   tabular  |
+------------------------------+------------+

----------
Parameters
----------
	  
Data matrix file
	| variable x sample **dataMatrix** tabular separated file of the numeric data matrix, with . as decimal, and NA for missing values; the table must not contain metadata apart from row and column names; the row and column names must be identical to the rownames of the sample and variable metadata, respectively (see below)
	|

Sample metadata file
	| sample x metadata **sampleMetadata** tabular separated file of the numeric and/or character sample metadata, with . as decimal and NA for missing values
	|
	
Variable metadata file
	| variable x metadata **variableMetadata** tabular separated file of the numeric and/or character variable metadata, with . as decimal and NA for missing values
	|

Factor
	| Column of the sample metadata table to be used as qualitative factor (t-test, Wilcoxon test, Analysis of variance, Kruskal-Wallis test) or quantitative variable (correlation)
	|

Test
	| Depending on the factor of interest (qualitative with 2 or more levels, or quantitative), and on the normality of the sample values (determining whether a parametric or nonparametric test is required), you can choose one of the 6 tests available:


+---------------------------+------------------+----------------------+----------------------+
| Factor to be tested       | Number of levels |    Parametric test   |  Nonparametric test  |
+===========================+==================+======================+======================+
| Qualitative               |         2        |       t-test         |    Wilcoxon test     |
+                           +------------------+----------------------+----------------------+
|                           |        > 2       | Analysis of variance |    Kruskal-Wallis    |
+---------------------------+------------------+----------------------+----------------------+
| Quantitative              |                  | Pearson correlation  | Spearman correlation |
+---------------------------+------------------+----------------------+----------------------+

Method for multiple testing correction
	| The 7 methods implemented in the 'p.adjust' R function are available and documented as follows:
	| "The adjustment methods include the Bonferroni correction ("bonferroni") in which the p-values are multiplied by the number of comparisons. Less conservative corrections are also included by Holm (1979) ("holm"), Hochberg (1988) ("hochberg"), Hommel (1988) ("hommel"), Benjamini and Hochberg (1995) ("BH" or its alias "fdr"), and Benjamini and Yekutieli (2001) ("BY"), respectively. A pass-through option ("none") is also included. The set of methods are contained in the p.adjust.methods vector for the benefit of methods that need to have the method as an option and pass it on to p.adjust. The first four methods are designed to give strong control of the family-wise error rate. There seems no reason to use the unmodified Bonferroni correction because it is dominated by Holm's method, which is also valid under arbitrary assumptions. Hochberg's and Hommel's methods are valid when the hypothesis tests are independent or when they are non-negatively associated (Sarkar, 1998; Sarkar and Chang, 1997). Hommel's method is more powerful than Hochberg's, but the difference is usually small and the Hochberg p-values are faster to compute. The "BH" (aka "fdr") and "BY" method of Benjamini, Hochberg, and Yekutieli control the false discovery rate, the expected proportion of false discoveries amongst the rejected hypotheses. The false discovery rate is a less stringent condition than the family-wise error rate, so these methods are more powerful than the others."
	|

(Corrected) p-value significance threshold
	|
	|


------------
Output files
------------
	
variableMetadata_out.tabular
	| **variableMetadata** file identical to the file given as argument, except that (at least) three columns have been added:
	| 1) [factor]_[test]_[class'a']-[class'b']_dif or [factor]_[test]_cor: difference of the means (ttest) or the medians (wilcoxon) between the two classes, or 'pearson' or 'spearman' correlations
	| 2) [factor]_[test]_[class'a']-[class'b']_[method] or [factor]_[test]_[method]: adjusted p-values
	| 3) [factor]_[test]_[class'a']-[class'b']_sig or [factor]_[test]_sig: significance (coded as '1' if below the threshold and '0' otherwise)
	| In the case of 'anova' and 'kruskal', the columns 2) and 3) appear first to give the results from the ANOVA or Kruskal Wallis test, and, when these tests are significant, the results of the pairwise comparisons are reported in additional columns (otherwise NA in these columns): in the case of ANOVA, the Tukey HSD post-hoc analysis is used (for each comparison, the difference between means, p value, and significance are provided); in the case of Kruskal Wallis, the Nemenyi is performed (PMCMR package) (for each pairwise comparison, the difference between medians, p value and significance are provided)
	|
	
information.txt
	| File with all messages and warnings generated during the computation
	|

---------------------------------------------------

---------------
Working example
---------------

.. class:: infomark

See the **W4M00001a_sacurine-subset-statistics**, **W4M00001b_sacurine-subset-complete**, **W4M00002_mtbls2**, **W4M00003_diaplasma** shared histories in the **Shared Data/Published Histories** menu (https://galaxy.workflow4metabolomics.org/history/list_published)

---------------------------------------------------

----
NEWS
----

CHANGES IN VERSION 2.1.4
========================

NEW FEATURE

Level names are now separated by '.' instead of '-' previously in the column names of the output variableMetadata table (e.g., 'jour_ttest_J3.J10_fdr' instead of 'jour_ttest_J3-J10_fdr' previously)

INTERNAL MODIFICATIONS

Minor internal changes for toolshed export

CHANGES IN VERSION 2.1.2
========================

INTERNAL MODIFICATIONS

Minor internal changes for toolshed export

CHANGES IN VERSION 2.1.1
========================

INTERNAL MODIFICATIONS

Internal handling of 'NA' p-values (e.g. when intensities are identical in all samples)

CHANGES IN VERSION 2.0.1
========================

NEW FEATURE

(corrected) p-value threshold can be set to any value between 0 and 1


</help>

<citations>
  <citation type="bibtex">@Manual{,
  title = {R: A Language and Environment for Statistical Computing},
  author = {{R Core Team}},
  organization = {R Foundation for Statistical Computing},
  address = {Vienna, Austria},
  year = {2016},
  url = {https://www.R-project.org/},
  }</citation>
  <citation type="bibtex">@Article{Thevenot2015,
   Title                    = {Analysis of the human adult urinary metabolome variations with age, body mass index and gender by implementing a comprehensive workflow for univariate and OPLS statistical analyses},
   Author                   = {Thevenot, Etienne A. and Roux, Aurelie and Xu, Ying and Ezan, Eric and Junot, Christophe},
   Journal                  = {Journal of Proteome Research},
   Year                     = {2015},
   Note                     = {PMID: 26088811},
   Number                   = {8},
   Pages                    = {3322-3335},
   Volume                   = {14},
   
   Doi                      = {10.1021/acs.jproteome.5b00354},
   Url                      = {http://pubs.acs.org/doi/full/10.1021/acs.jproteome.5b00354}
   }</citation>
   <citation type="doi">10.1093/bioinformatics/btu813</citation>
 </citations>



Input files
===========

| **To generate the "dataMatrix", "sampleMetadata" and "variableMetadata" files:**
|   **1) copy/paste the values below in three distinct .txt files**
|   **2) use the "Get Data" / "Upload File" in the "Tools" (left) panel from the Galaxy / ABiMS page by choosing:**
|     **a) File Format: 'tabular'**
|     **b) Convert spaces to tabs: 'Yes'**
| 

**dataMatrix file**::

	dataMatrix HU_017 HU_021 HU_027 HU_032 HU_041 HU_048 HU_049 HU_050 HU_052 HU_059 HU_060 HU_066 HU_072 HU_077 HU_090 HU_109 HU_110 HU_125 HU_126 HU_131 HU_134 HU_149 HU_150 HU_173 HU_179 HU_180 HU_182 HU_202 HU_204 HU_209
	HMDB01032 2569204.92420381 6222035.77434915 17070707.9912636 1258838.24348419 13039543.0754619 1909391.77026598 3495.09386434063 2293521.90928998 128503.275117713 81872.5276382213 8103557.56578035 149574887.036181 1544036.41049333 7103429.53933206 14138796.50382 4970265.57952158 263054.73056162 1671332.30008058 88433.1944958815 23602331.2894815 18648126.5206986 1554657.98756878 34152.3646391152 209372.71275317 33187733.370626 202438.591636003 13581070.0886437 354170.810678102 9120781.48986975 43419175.4051586
	HMDB03072 3628416.30251025 65626.9834353751 112170.118946651 3261804.34422417 42228.2787747563 343254.201250707 1958217.69317664 11983270.0435677 5932111.41638028 5511385.83359531 9154521.47755199 2632133.21209418 9500411.14556502 6551644.51726592 7204319.80891836 1273412.04795188 3260583.81592376 8932005.5351622 8340827.52597275 9256460.69197759 11217839.169041 5919262.81433556 11790077.0657915 9567977.80797097 73717.5811684739 9991787.29074293 4208098.14739633 623970.649925847 10904221.2642849 2171793.93621067
	HMDB00792 429568.609438384 3887629.50527037 1330692.11658995 1367446.73023821 844197.447472453 2948090.71886592 1614157.90566884 3740009.19379795 3292251.66531919 2310688.79492013 4404239.59008605 3043289.12780863 825736.467181043 2523241.91730649 6030501.02648005 474901.604069803 2885792.42617652 2955990.64049134 1917716.3427982 1767962.67737699 5926203.40397675 1639065.69474684 346810.763557826 1054776.22313737 2390258.27543894 1831346.37315857 1026696.36904362 7079792.50047866 4368341.01359769 3495986.87280275

	
**sampleMetadata file**::

	sampleMetadata age ageGrp
	HU_017 41 experienced
	HU_021 34 junior
	HU_027 37 experienced
	HU_032 38 experienced
	HU_041 28 junior
	HU_048 39 experienced
	HU_049 50 senior
	HU_050 30 junior
	HU_052 51 senior
	HU_059 81 senior
	HU_060 55 senior
	HU_066 25 junior
	HU_072 47 experienced
	HU_077 27 junior
	HU_090 46 experienced
	HU_109 32 junior
	HU_110 50 senior
	HU_125 58 senior
	HU_126 45 experienced
	HU_131 42 experienced
	HU_134 48 experienced
	HU_149 35 experienced
	HU_150 49 experienced
	HU_173 55 senior
	HU_179 33 junior
	HU_180 53 senior
	HU_182 43 experienced
	HU_202 42 experienced
	HU_204 31 junior
	HU_209 17.5 junior

	
**variableMetadata file**::

	variableMetadata name
	HMDB01032        Dehydroepiandrosterone sulfate
	HMDB03072        Quinic acid
	HMDB00792        Sebacic acid

	
Parameters
==========

**Factor of interest:** "ageGroup"

**Test:** "Kruskal-Wallis rank test (qualitative, > 2 levels)"
 
**Method for multiple testing correction:** "fdr"

**(Corrected) p-value significance threshold:** 0.05


Output files
============

+------------------------------+------------+
| File                         |   Format   |
+==============================+============+
| 1)  dataMatrix               |   tabular  |
+------------------------------+------------+
| 2)  sampleMetadata           |   tabular  |
+------------------------------+------------+
| 3)  variableMetadata         |   tabular  |
+------------------------------+------------+
| 4)  information              |    text    |
+------------------------------+------------+


---------------------------------------------------


</tool>