<tool id="deeptools_plot_heatmap" name="plotHeatmap" version="@WRAPPER_VERSION@.1" profile="18.01">
    <description>creates a heatmap for score distributions across genomic regions</description>
    <macros>
        <token name="@BINARY@">plotHeatmap</token>
        <import>deepTools_macros.xml</import>
    </macros>
    <expand macro="requirements"/>
    <command>
<![CDATA[
        @BINARY@
            --matrixFile '$matrixFile'
            --outFileName '$outFileName'

            #if $output.showOutputSettings == "yes"
                --plotFileFormat '$output.outFileFormat'

                #if $outFileNameMatrix:
                    --outFileNameMatrix '$outFileNameMatrix'
                #end if

                #if $outFileSortedRegions:
                    --outFileSortedRegions '$outFileSortedRegions'
                #end if

                #if $output.dpi:
                    --dpi '$output.dpi'
                #end if
            #else
                --plotFileFormat 'png'
            #end if

            #if $advancedOpt.showAdvancedOpt == "yes"
                #if $advancedOpt.sortRegions:
                    --sortRegions '$advancedOpt.sortRegions'
                #end if

                #if $advancedOpt.sortUsing:
                    --sortUsing '$advancedOpt.sortUsing'
                #end if

                #if $advancedOpt.averageTypeSummaryPlot:
                    --averageTypeSummaryPlot '$advancedOpt.averageTypeSummaryPlot'
                #end if

                --plotType '$advancedOpt.plotType'

                #if str($advancedOpt.missingDataColor.value) != "None":
                    --missingDataColor '$advancedOpt.missingDataColor'
                #end if

                #set colorMap = []
                #for $cmap in $advancedOpt.colorMapRepeat:
                    #silent $colorMap.append(str($cmap.colorMap))
                #end for
                #if len($colorMap) > 0:
                    --colorMap #echo " ".join($colorMap)#
                #end if

                --alpha '$advancedOpt.alpha'
                #if str($advancedOpt.colorList).strip() != "":
                    --colorList $advancedOpt.colorList
                #end if

                #if str($advancedOpt.zMin).strip() != "":
                    --zMin $advancedOpt.zMin
                #end if
                #if str($advancedOpt.zMax).strip() != "":
                    --zMax $advancedOpt.zMax
                #end if

                #if str($advancedOpt.yMin).strip() != "":
                    --yMin $advancedOpt.yMin
                #end if
                #if $advancedOpt.yMax:
                    --yMax $advancedOpt.yMax
                #end if

                --xAxisLabel '$advancedOpt.xAxisLabel'
                --yAxisLabel '$advancedOpt.yAxisLabel'

                --heatmapWidth $advancedOpt.heatmapWidth
                --heatmapHeight $advancedOpt.heatmapHeight

                --whatToShow '$advancedOpt.whatToShow'

                --startLabel '$advancedOpt.startLabel'
                --endLabel '$advancedOpt.endLabel'

                --refPointLabel '$advancedOpt.referencePointLabel'

                #if $advancedOpt.samplesLabel and str($advancedOpt.samplesLabel).strip() != "":
                    --samplesLabel $advancedOpt.samplesLabel
                #end if

                #if $advancedOpt.regionsLabel and str($advancedOpt.regionsLabel).strip() != "":
                    --regionsLabel $advancedOpt.regionsLabel
                #end if

                #if $advancedOpt.plotTitle and str($advancedOpt.plotTitle.value) != "":
                    --plotTitle '$advancedOpt.plotTitle'
                #end if

                --legendLocation '$advancedOpt.legendLocation'

                --labelRotation '$advancedOpt.labelRotation'

                $advancedOpt.perGroup

                @KMEANS_CLUSTERING@

            #end if
]]>
    </command>
    <inputs>
        <param argument="matrixFile" format="deeptools_compute_matrix_archive" type="data"
               label="Matrix file from the computeMatrix tool" help=""/>

        <expand macro="input_graphic_output_settings">
            <expand macro="input_image_file_format" />
            <expand macro="output_dpi" />
            <expand macro="input_save_matrix_values" />
        </expand>

        <conditional name="advancedOpt" >
            <param name="showAdvancedOpt" type="select" label="Show advanced options" >
                <option value="no" selected="true">no</option>
                <option value="yes">yes</option>
            </param>
            <when value="no" />
            <when value="yes">
                <expand macro="sortRegions" />
                <expand macro="sortUsing" />
                <param argument="--averageTypeSummaryPlot" type="select"
                    label="Type of statistic that should be plotted in the summary image above the heatmap"
                    help="">
                    <option value="mean" selected="true">mean</option>
                    <option value="median">median</option>
                    <option value="min">min</option>
                    <option value="max">max</option>
                    <option value="sum">sum</option>
                    <option value="std">std</option>
                </param>
                <param argument="--plotType" type="select" label="Type of summary plot">
                    <option value="lines">plot the profile line based on the statistic selected above.</option>
                    <option value="fill">fills the region between zero and the profile.</option>
                    <option value="se">color the region between the profile and the standard error.</option>
                    <option value="std">color the region between the profile and the standard deviation.</option>
                </param>
                <param argument="--missingDataColor" type="text" value="black" optional="true" label="Missing data color"
                    help="If 'Represent missing data as zero' is not set, such cases will be colored in black by default.
                    By using this parameter a different color can be set. A value between 0 and 1 will be used for a gray scale (black is 0).
                    Also color names can be used, see a list here: http://packages.python.org/ete2/reference/reference_svgcolors.html.
                    Alternatively colors can be specified using the #rrggbb notation." />

                <repeat name="colorMapRepeat" title="Colormap to use for each sample"
                    help="A different colormap can be applied to each column of the heatmap. If you select fewer colormaps than you have samples in your matrix, then the select colormap(s) will be repeated (e.g., if you select one colormap then it will be applied to all samples).">
                    <expand macro="colorMap" />
                </repeat>
                <param argument="--alpha" type="float" value="1.0" min="0.0"
                    max="1.0" optional="True"
                    label="Alpha channel (transparency)"
                    help="The alpha channel (transparency) to use for the heatmaps. The default is 1.0 and values must
                    be between 0 and 1. A value of 0.0 would be fully transparent." />

                <param argument="--colorList" type="text" value="" size="50" optional="True"
                    label="List of colors for each heatmap. Separate lists by spaces and the colors in the list by comas"
                    help="The color of the heatmaps can be specified as a list of colors separated by comas with
                    not space in between. For example: white,blue white,green will set a color map from white
                    to blue for the first heatmap and for white to green for the next heatmap."/>
                <expand macro="zMin_zMax" />
                <param argument="--yMin" type="float" value="" size="3" optional="True"
                    label="Minimum value for the Y-axis of the summary plot. Leave empty for automatic values" help=""/>
                <param argument="--yMax" type="float" value="" size="3" optional="True"
                    label="Maximum value for Y-axis of the summary plot. Leave empty for automatic values" help=""/>
                <param argument="--xAxisLabel" type="text" value="distance from TSS (bp)" size="200"
                    label="The x-axis label" help="" />
                <param argument="--yAxisLabel" type="text" value="genes" size="30"
                    label="The y-axis label for the top panel" help="" />

                <param argument="--heatmapWidth" type="float" value="7.5" min="1" max="100"
                    label="Heatmap width in cm" help="The minimum value is 1 and the maximum is 100."/>
                <param argument="--heatmapHeight" type="float" value="25" min="3" max="100"
                    label="Heatmap height in cm" help="The minimum value is 3 and the maximum is 100."/>

                <param argument="--whatToShow" type="select" label="What to show"
                    help ="The default is to include a summary or profile plot on top of the heatmap and a heatmap colorbar.">
                    <option value="plot, heatmap and colorbar" selected="true">summary plot, heatmap and colorbar</option>
                    <option value="plot and heatmap">summary plot and heatmap (no colorbar)</option>
                    <option value="heatmap and colorbar">heatmap and colorbar</option>
                </param>

                <param argument="--startLabel" type="text" value="TSS" size="10"
                    label="Label for the region start"
                    help ="Only for scale-regions mode. Label shown in the plot for the start of the region. Default is TSS (transcription start site), but could be changed to anything, e.g. &quot;peak start&quot;." />
                <param argument="--endLabel" type="text" value="TES" size="10"
                    label="Label for the region end"
                    help="Only for scale-regions mode. Label shown in the plot for the region end. Default is TES (transcription end site)."/>

                <param argument="--referencePointLabel" type="text" value="TSS" size="10"
                    label="Reference point label"
                    help ="Label shown in the plot for the reference-point. Default is the same as the reference point selected (e.g. TSS), but could be anything, e.g. &quot;peak start&quot; etc." />
                <param argument="--samplesLabel" type="text" size="30"
                    label="Labels for the samples (each bigwig) plotted"
                    help="The default is to use the file name of the sample. The sample labels should be separated by
                    spaces and quoted if a label itself contains a space E.g. label-1 &quot;label 2&quot;">
                    <sanitizer>
                        <valid initial="string.printable">
                        </valid>
                    </sanitizer>
                </param>
                <param argument="--regionsLabel" type="text" size="30"
                    label="Labels for the regions plotted in the heatmap"
                    help="If more than one region is being plotted a list of labels separated by space is required.
                          If a label itself contains a space, then quotes are needed.
                          For example, label_1 &quot;label 2&quot;" />

                <expand macro="plotTitle" />
                <expand macro="legendLocation" />
                <expand macro="labelRotation" />
                <param argument="--perGroup" type="boolean" truevalue="--perGroup" falsevalue=""
                    label="Make one plot per group of regions"
                    help="The default is to make one plot per bigWig file, i.e., all samples next to each other. Choosing this option will make one plot per group of regions."/>

                <expand macro="kmeans_clustering" />
            </when>
        </conditional>
    </inputs>
    <outputs>
        <expand macro="output_image_file_format" />
        <expand macro="output_graphic_outputs" />
        <expand macro="output_save_matrix_values" />
    </outputs>
    <tests>
        <test>
            <param name="matrixFile" value="computeMatrix_result1.gz" ftype="deeptools_compute_matrix_archive" />
            <output name="outFileName" file="heatmapper_result1.png" ftype="png" compare="sim_size" delta="4000" />
        </test>
        <test>
            <param name="matrixFile" value="computeMatrix_result1.gz" ftype="deeptools_compute_matrix_archive" />
            <param name="showAdvancedOpt" value="yes" />
            <param name="whatToShow" value="heatmap and colorbar" />
            <output name="outFileName" file="heatmapper_result2.png" ftype="png" compare="sim_size" delta="4000" />
        </test>
    </tests>
    <help>
<![CDATA[

What it does
--------------

``plotHeatmap`` visualizes scores associated with genomic regions, for example ChIP enrichment values around the TSS of genes.
Like ``plotProfile``, it requires that computeMatrix was run first to calculate the values.

We have implemented a number of optional parameters to optimize the visual output and we encourage you to play around with the min/max values
displayed in the heatmap as well as with the different coloring options.

**TIP:** *If your data is rather sparse and the resulting heatmap is too black, change the "Missing data color" to white (via "Advanced options").*

The most powerful option is probably the **k-means/hierarchical clustering** where you can sort your regions into groups of regions with similar score distributions.

**NOTE:** *The clustering will only work if you supplied a single BED file to computeMatrix. plotHeatmap cannot cluster regions within pre-defined groups. Moreover, k-means will be much faster than hierarchical clustering.*

Output
--------------

This is a heatmap based on two bigWig files generated with default settings and k-means clustering.

.. image:: $PATH_TO_IMAGES/plotHeatmap_example.png
   :width: 600
   :height: 694

.. image:: $PATH_TO_IMAGES/plotHeatmap_example02.png
    :width: 600
    :height: 694

In addition to the image, ``plotHeatmap`` can also generate the values underlying both the heatmap.

See the following table for the optional output options:

+-----------------------------------+--------------------+-----------------+-----------------+
|  **optional output type**         |  **computeMatrix** | **plotHeatmap** | **plotProfile** |
+-----------------------------------+--------------------+-----------------+-----------------+
| values underlying the heatmap     |  yes               | yes             | no              |
+-----------------------------------+--------------------+-----------------+-----------------+
| values underlying the profile     | no                 | no              | yes             |
+-----------------------------------+--------------------+-----------------+-----------------+
| sorted and/or filtered regions    | yes                | yes             | yes             |
+-----------------------------------+--------------------+-----------------+-----------------+

**More examples** can be found in our `Gallery <http://deeptools.readthedocs.org/en/latest/content/example_gallery.html#normalized-chip-seq-signals-and-peak-regions>`_.

-----

@REFERENCES@
]]>
    </help>
    <expand macro="citations" />
</tool>