.. _`bio/deeptools/plotheatmap`:

DEEPTOOLS PLOTHEATMAP
=====================


.. image:: https://img.shields.io/github/issues-pr/snakemake/snakemake-wrappers/bio/deeptools/plotheatmap?label=version%20update%20pull%20requests
   :target: https://github.com/snakemake/snakemake-wrappers/pulls?q=is%3Apr+is%3Aopen+label%3Abio/deeptools/plotheatmap

``deepTools plotHeatmap`` creates a heatmap for scores associated with genomic regions. As input, it requires a matrix file generated by ``deepTools computeMatrix``. For usage information about ``deepTools plotHeatmap``, please see the `documentation <https://deeptools.readthedocs.io/en/develop/content/tools/plotHeatmap.html>`_. For more information about ``deepTools``, also see the `source code <https://github.com/deeptools/deepTools>`_.

You can select which optional output files are generated by adding the respective output variable with the recommended extension(s) for them (see example Snakemake rule below).

  +----------------------------+---------------------+---------------------+-------------+
  | PlotHeatmap option         | Output              | Name of output      | Recommended |
  |                            |                     |                     |             |
  |                            |                     | variable to be used | extension(s)|
  +============================+=====================+=====================+=============+
  | -\-outFileName, -out, -o   | plot image          | heatmap_img         | ".png" or   |
  |                            |                     |                     |             |
  |                            |                     | (required)          | ".eps" or   |
  |                            |                     |                     |             |
  |                            |                     |                     | ".pdf" or   |
  |                            |                     |                     |             |
  |                            |                     |                     | ".svg"      |
  +----------------------------+---------------------+---------------------+-------------+
  | -\-outFileSortedRegions    | BED file with       | regions             | ".bed"      |
  |                            |                     |                     |             |
  |                            | sorted regions      |                     |             |
  +----------------------------+---------------------+---------------------+-------------+
  | -\-outFileNameMatrix       | tab-separated matrix| heatmap_matrix      | ".tab"      |
  |                            |                     |                     |             |
  |                            | of values underlying|                     |             |
  |                            |                     |                     |             |
  |                            | the heatmap         |                     |             |
  +----------------------------+---------------------+---------------------+-------------+



Example
-------

This wrapper can be used in the following way:

.. code-block:: python

    rule plot_heatmap:
        input:
             # matrix file from deepTools computeMatrix tool
             "matrix.gz"
        output:
            # Please note that --outFileSortedRegions and --outFileNameMatrix are exclusively defined via output files.
            # Usable output variables, their extensions and which option they implicitly call are listed here:
            #         https://snakemake-wrappers.readthedocs.io/en/stable/wrappers/deeptools/plotheatmap.html.
            heatmap_img="plot_heatmap/heatmap.png",  # required
            # optional output files
            regions="plot_heatmap/heatmap_regions.bed",
            heatmap_matrix="plot_heatmap/heatmap_matrix.tab"
        log:
            "logs/deeptools/heatmap.log"
        params:
            # optional parameters
            "--plotType=fill "
        wrapper:
            "v3.0.1/bio/deeptools/plotheatmap"

Note that input, output and log file paths can be chosen freely.

When running with

.. code-block:: bash

    snakemake --use-conda

the software dependencies will be automatically deployed into an isolated environment before execution.


Software dependencies
---------------------

* ``deeptools=3.5.4``

Input/Output
------------
**Input:**

* gzipped matrix file from ``deepTools computeMatrix`` (.gz)

**Output:**

* plot file in image format (.png, .eps, .pdf or .svg) AND/OR
* file with sorted regions after skipping zeros or min/max threshold values (.bed) AND/OR
* tab-separated table for average profile (.tab)




Authors
-------

* Antonie Vietor


Code
----

.. code-block:: python

    __author__ = "Antonie Vietor"
    __copyright__ = "Copyright 2020, Antonie Vietor"
    __email__ = "antonie.v@gmx.de"
    __license__ = "MIT"

    from snakemake.shell import shell

    log = snakemake.log_fmt_shell(stdout=True, stderr=True)

    out_region = snakemake.output.get("regions")
    out_matrix = snakemake.output.get("heatmap_matrix")

    optional_output = ""

    if out_region:
        optional_output += " --outFileSortedRegions {out_region} ".format(
            out_region=out_region
        )

    if out_matrix:
        optional_output += " --outFileNameMatrix {out_matrix} ".format(
            out_matrix=out_matrix
        )

    shell(
        "(plotHeatmap "
        "-m {snakemake.input[0]} "
        "-o {snakemake.output.heatmap_img} "
        "{optional_output} "
        "{snakemake.params}) {log}"
    )


.. |nl| raw:: html

   <br>