<tool id="deeptools_plot_heatmap" name="plotHeatmap" version="@WRAPPER_VERSION@.0">
    <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
            #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

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

                --colorMap '$advancedOpt.colorMap'

                #if str($advancedOpt.zMin).strip() != "":
                    --zMin $advancedOpt.zMin
                #end if
                #if $advancedOpt.zMax:
                    --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

                $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="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="--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." />

                <expand macro="colorMap" />

                <param argument="--zMin" type="float" value="" size="3" optional="True"
                    label="Minimum value for the heatmap intensities. Leave empty for automatic values" help=""/>
                <param argument="--zMax" type="float" value="" size="3" optional="True"
                    label="Maximum value for the heatmap intensities. Leave empty for automatic values" help=""/>
                <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" />
                <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>