--- a/hicCorrelate.xml	Wed Mar 07 03:39:03 2018 -0500
+++ b/hicCorrelate.xml	Fri Apr 27 03:33:56 2018 -0400
@@ -1,5 +1,5 @@
 <tool id="hicexplorer_hiccorrelate" name="@BINARY@" version="@WRAPPER_VERSION@.0">
-    <description>Computes pairwise correlations between hic matrices data</description>
+    <description>compute pairwise correlations between multiple Hi-C contact matrices</description>
     <macros>
         <token name="@BINARY@">hicCorrelate</token>
         <import>macros.xml</import>
@@ -40,12 +40,16 @@
             <option selected="true" value="pearson">Pearson</option>
         </param>
         <param name="log1p" type="boolean" argument="--log1p"  truevalue="--log1p" falsevalue=""
-            label="Use the log1p of the matrix values" help="(--log1p)" />
+            label="Use the log1p of the matrix values" help="If set, then the log1p of the matrix values is used.
+            This parameter has no effect for Spearman correlations
+            but changes the output of Pearson correlation and, for
+            the scatter plot, if set, the visualization of the
+            values is easier." />
 
         <expand macro="use_range" />
 
         <repeat name="chromosomes" title="List of chromosomes to be included in the correlation" min="0">
-            <param name="chromosome" type="text">
+            <param name="chromosome" type="text" label='chromosome (one per field)'>
                 <validator type="empty_field" />
             </param>
         </repeat>
@@ -93,43 +97,43 @@
 Matrix correlation
 ==================
 
-Computes pairwise correlations between Hi-C contact matrices.
-The correlation is computed taking the values from each pair of matrices and discarding values that are zero in both matrices.
+**hicCorrelate** is a dedicated Quality Control tool that allows the correlation of multiple Hi-C matrices at once with either a heatmap or scatterplots output.
+
+Computes pairwise correlations between Hi-C matrices data. The correlation is computed taking the values from each pair of matrices and discarding values that are zero in both matrices. Parameters that strongly affect correlations are bin size of the Hi-C matrices (can be changed using ``hicMergeMatrixBins``) and the considered range. The smaller the bin size of the matrices, the finer the differences you score. The *Range* parameter should be selected at a meaningful genomic scale according to, for example, the mean size of the TADs in the organism you work with or to specific ranges found using ``hicPlotDistVsCounts``.
 
-Input
+_________________
+
+Usage
 -----
 
-Parameters
-__________
-- Two contact matrices which are used for the correlation.
-- Choice if pearson or spearman correlation should be used.
-- log scale for the values
-- Correlate full matrix or only specific chromosomes
-- Correlate only within a given range.
-- colormap to use:  Colormap_
+It is recommended to use this tool on corrected matrices (``hicCorrectMatrix``) at restriction enzyme resolution (unmerged bins).
+
+_________________
 
 Output
 ------
 
-Pearson correlation
-___________________
+**hicCorrelate** outputs correlation plots of multiple Hi-C matrices.
+
+Below, you can find a correlation example of uncorrected Hi-C matrices obtained from *Drosophila melanogaster* embryos, either wild-type or having one gene knocked-down by RNAi.
 
-.. image:: $PATH_TO_IMAGES/hicCorrelate_pearson.png
+Heatmap
+_______
+
+.. image:: $PATH_TO_IMAGES/hicCorrelate_Dmel_heatmap.png
    :width: 45%
 
-.. image:: $PATH_TO_IMAGES/hicCorrelate_pearson_scatter.png
- :width: 45%
+This example is showing a heatmap that was calculated using the Pearson correlation of corrected Hi-C matrices with a bin size of 6000 bp at a range of 5000 to 200000. The dendrogram indicates which samples are most similar to each other. You can see that the wild-type samples are seperated from the knock-down samples. In that case, Spearman correlation gives very similar results (not shown).
 
-
+Scatterplot
+___________
 
-Spearman correlation
-_____________________
+.. image:: $PATH_TO_IMAGES/hicCorrelate_Dmel_scatterplot.png
+   :width: 45%
 
-.. image:: $PATH_TO_IMAGES/hicCorrelate_spearman.png
-   :width: 45 %
+Additionally, pairwise scatterplots comparing interactions between each sample can be plotted.
 
-.. image:: $PATH_TO_IMAGES/hicCorrelate_spearman_scatter.png
-   :width: 45 %
+_________________
 
 For more information about HiCExplorer please consider our documentation on readthedocs.io_.