annotate CorrTable/Corr.xml @ 0:b22c453e4cf4 draft

Uploaded

<tool id="corrtable" name="Between-table Correlation" version="0.0.0">
	<description>Correlation table between two tables and graphic representation </description>
	  <requirements>
			<requirement type="package" version="1.1_4">r-batch</requirement>
			<requirement type="package" version="3.0.0">r-ggplot2</requirement>
			<requirement type="package" version="1.4.3">r-reshape2</requirement>
	</requirements>
	<command interpreter="Rscript">
	
		Corr_wrap.r
		
		tab1_in "$tab1_in"
		tab2_in "$tab2_in"
		
		tab1_samples "$tab1_samples"
		tab2_samples "$tab2_samples"
		
		corr_method "$corr_method"
		
		test_corr "${filter_section.testcorr_cond.test_corr}"
		#if str($filter_section.testcorr_cond.test_corr) == 'yes' :
			correct_multi "${filter_section.testcorr_cond.correct_multi}"
			risk_alpha "${filter_section.testcorr_cond.risk_alpha}"
		#end if
		
		filter "${filter_section.filter_cond.filter}"
		#if str($filter_section.filter_cond.filter) == 'yes' :
			filters_choice "${filter_section.filter_cond.filtchoice_cond.filters_choice}"
			#if str($filter_section.filter_cond.filtchoice_cond.filters_choice) == 'filters_0_thr' :
				threshold "${filter_section.filter_cond.filtchoice_cond.threshold}"
			#end if
		#end if
		
		reorder_var "$out_section.reorder_var"
		
		color_heatmap "${out_section.heatmap_cond.color_heatmap}"
		#if str($out_section.heatmap_cond.color_heatmap) == 'yes' :
			type_classes "${out_section.heatmap_cond.typeclass_cond.type_classes}"
			#if str($out_section.heatmap_cond.typeclass_cond.type_classes) == 'regular' :
				reg_class_value "${out_section.heatmap_cond.typeclass_cond.reg_class_value}"
			#elif str($out_section.heatmap_cond.typeclass_cond.type_classes) == 'irregular' :
				irreg_class_vect "${out_section.heatmap_cond.typeclass_cond.irreg_class_vect}"
			#end if
		#end if	
		
		tabcorr_out "$tabcorr_out"
		heatmap_out "$heatmap_out"
		
	</command>
	
	<inputs>
	
		<param name="tab1_in" type="data" label="Table 1 file" help="The two input tables must have the same sample IDs" format="tabular" />
		<param name="tab1_samples" label="Where are the samples in table 1?" type="select" display="radio" help="">
			<option value="row">Row</option>
			<option value="column">Column</option>
		</param>
		
		<param name="tab2_in" type="data" label="Table 2 file" help="The two input tables must have the same sample IDs" format="tabular" />
		<param name="tab2_samples" label="Where are the samples in table 2?" type="select" display="radio" help="">
			<option value="row">Row</option>
			<option value="column">Column</option>		
		</param>
		
		<param name="corr_method" label="Method to calculate the correlation coefficients" type="select" help="">
			<option value="pearson">Pearson</option>
			<option value="spearman">Spearman</option>
			<option value="kendall">Kendall</option>
		</param>	
		
		<section name="filter_section" title="Filtering options" expanded="False">
			<conditional name="testcorr_cond">
				<param name="test_corr" label="Significance test for the correlation coefficients" type="select" display="radio" help="">
					<option value="no">No</option>
					<option value="yes">Yes</option>
				</param>
				<when value="yes">
					<param name="correct_multi" label="Method for multiple testing correction" type="select" help="">
						<option value="none">none</option>				
						<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>
					</param>
					<param name="risk_alpha" label="(Corrected) p-value significance threshold" type="float" value="0.05" help="Must be between 0 and 1" />
				</when>
				<when value="no">
				</when>
			</conditional>
			
			<conditional name="filter_cond">
				<param name="filter" label="Filter the correlation table" type="select" display="radio" help="">
					<option value="no">No</option>
					<option value="yes">Yes</option>
				</param>

				<when value ="yes">
					<conditional name="filtchoice_cond">
						<param name="filters_choice" label="Do you want to use only zero filter or combine it with the threshold filter?" type="select" display="radio" help="The zero filter removes variables which have all their correlation coefficients equal to 0. The threshold filter removes variables which have all their correlation coefficients, in absolute value, strictly below a threshold.">
							<option value="filter_0">Only zero filter</option>
							<option value="filters_0_thr">Threshold filter</option>
						</param>
						
						<when value="filters_0_thr">
							<param name="threshold" label="Threshold" type="float" value="" help="Must be between 0 and 1" />
						</when>
						
						<when value="filter_0">
						</when>
					</conditional>	
				</when>
				
				<when value="no">
				</when>
			</conditional>		
		</section>
		
		<section name="out_section" title="Graphical outputs" expanded="False">
			<param name="reorder_var" label="Reorder variables (using Hierarchical Cluster Analysis)" type="select" display="radio" help="">
				<option value="no">No</option>
				<option value="yes">Yes</option>
			</param>
		
			<conditional name="heatmap_cond">
				<param name="color_heatmap" label="Colored correlation table strategy" type="select" display="radio" help="Standard corresponds to a scale with a smooth gradient between three colors: red, white and green (continuous case). Customized creates classes for the correlation coefficients - the scale has discrete values.">
					<option value="no">Standard</option>
					<option value="yes">Customized</option>
				</param>		
		
				<when value="yes">
					<conditional name="typeclass_cond">
						<param name="type_classes" label="Choose the type of classes" type="select" display="radio" help="Regular means the classes have the same size. Irregular means it is possible to choose any intervals." >
							<option value="regular">Regular classes</option>
							<option value="irregular">Irregular classes</option>
						</param>
							
						<when value="regular">
							<param name="reg_class_value" label="Class size" type="float" value="" help="Must be between 0 and 1" />
						</when>
						
						<when value="irregular">
							<param name="irreg_class_vect" label="Vector with values for classes" type="text" value="" help="The vector must be of the following form: (value1,value2,value3,..). The values must be between -1 and 1 not included. For example: (-0.8,-0.5,-0.4,0,0.4,0.5,0.8)." />
						</when>
					</conditional>	
				</when>
				
				<when value ="no">	
				</when>
	
			</conditional>
		</section>
		
	</inputs>	
	
	<outputs>
		<data name="tabcorr_out" label="CorrTable" format="tabular" />
		<data name="heatmap_out" label="CT_plot" format="pdf" />
	</outputs>
	
	<help>
	
.. class:: infomark

**Author:** 
Ophelie Barbet for original code (PFEM - INRA) 
Maintainer: Melanie Petera (PFEM - INRA - MetaboHUB)

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

=========================
Between-table Correlation
=========================

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

 | Allows to visualise links existing between two data tables, with the creation of a correlation table between the variables of these tables, and a heatmap representing the correlation table colored according to the coefficients. 
 |

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

+----------------------------+------------+
| Parameter                  |   Format   |
+============================+============+
| 1 : Table 1 file           |   tabular  |
+----------------------------+------------+
| 2 : Table 2 file           |   tabular  |
+----------------------------+------------+

|
| The two input tables must have the same sample IDs.
|

----------
Parameters
----------

Positions of samples in table 1 and table 2
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        | Essential to correctly calculate the correlations.
        |

Method for calculating the correlation coefficients
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        | - 'Pearson': Measures the intensity of the linear association between two continuous variables.
		| - The 'Spearman' and 'Kendall' methods are explained in the R documentation of the 'cor' function as follows: " Kendall's tau or Spearman's rho statistic is used to estimate a rank-based measure of association. These are more robust and have been recommended if the data do not necessarily come from a bivariate normal distribution.".
		|
		
Significance test for the correlation coefficients
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        | This test is performed on each correlation coefficient, with the following hypotheses:
        |         H0: The correlation coefficient is not significantly different from zero.
        |         H1: The correlation coefficient is significantly different from zero.
        |
        | Coefficients whose null hypothesis (H0) are not rejected are replaced by zeros in the correlation table.
        |

| **Method for multiple testing correction (only if significance test is 'Yes'):**
| 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 powerfil than the others."
|

| **(Corrected) p-value significance threshold (only if significance test is 'Yes'):**
| A value between 0 and 1, usually 0.05.
|
	
Filter the correlation table
^^^^^^^^^^^^^^^^^^^^^^^^^^^^	
        | Allows to reduce the correlation table size by keeping only variables considered relevant.
        |

| **Choose the filters to apply (only if filter is 'Yes'):**
| 	- 'Only zero filter': Remove variables with all their correlation coefficients equal to zero.
| 	- 'Threshold filter': Remove variables with all their correlation coefficients (in absolute value) strictly below a threshold.
	
| *Choose a threshold (only threshold filter is used):* A value between 0 and 1.
|

Reorder variables using Hierarchical Cluster Analysis (HCA)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        | Allows the most linked variables to be close in the correlation table.
        | A HCA is performed on each input tables, with:
        |    - 1 - correlation coefficient, as distance
        |    - Ward as aggregation method.
        |

        
Colored correlation table strategy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
		| Allows to create a colored correlation table. Variables of table 1 and variables of table 2 are related using colored rectangles. 
		| About the colors, the negative correlations are in red, more or less intense according to their position between -1 and 0, and the positive correlations in green, more or less intense according to their position between 0 and 1. The coefficients equal to 0 are in white.
		| 	- 'Standard': the graphical representation has a scale with a smooth gradient between three colors: red, white and green.
		| 	- 'Customized': the colored correlation table has coefficient classes. It is possible to create regular or irregular classes. The scale is discreet.
		|
		
| **Choose the type of classes (only if colored correlation table strategy is 'Customized'):**

| 	- 'Regular': classes are all (or almost) the same size. 	
| To realize these intervals, we start from 1 to go to 0 by taking a step of the size chosen by the user, and we make the symmetry for -1 towards 0. If the last step does not fall on the 0 value, we create a class between this last value and 0, smaller in size than the others. It is important to specify that 0 represents a class on its own, which is assigned the color white for the heatmap.	

| *Size of classes (if regular classes):* A value between 0 and 1.

| Example: if the size is 0.4, classes are [-1;-0.6], ]-0.6;-0.2], ]-0.2;0[, 0, ]0;0.2], ]0.2;0.6] and ]0.6;1].
|

| 	- 'Irregular': classes have variable lengths.
| It is possible to do as many classes as you want, and of any size. There is not necessarily symmetry between -1 and 0, and 0 and 1. You can choose to have a white class with only 0, or an interval which contains the value 0.

| *Vector with values for classes (if irregular classes):* The values in the vector must be between -1 and 1 excluded, and in ascending order. It must have this form (value1,value2,...). If the vector contains 0, then this value becomes a class on its own, otherwise the white class is the one which contains 0.

| Example: if the vector is (-0.8,-0.5,-0.4,0,0.4,0.5,0.8), the classes are [-1;-0.8], ]-0.8;-0.5], ]-0.5;-0.4], ]-0.4;0[, 0, ]0;0.4], ]0.4;0.5], ]0.5;0.8] and ]0.8;1].
|

	
------------
Output files
------------

Correlation Table
^^^^^^^^^^^^^^^^^
	| Tabular output
	| Correlation table between the variables of the two input tables
	|
	
Heatmap (colored correlation table)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	| Pdf output
	| Colored representation of the correlation table. The coefficients are replaced by colors. A coefficient close to -1 is red, close to 0 white, and close to 1 in green.
	|
	
	
	</help>
	
</tool>