.. _`bio/deeptools/plotprofile`:

DEEPTOOLS PLOTPROFILE
=====================


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

``deepTools plotProfile`` plots scores over sets of genomic regions. As input, it requires a matrix file generated by ``deepToolscomputeMatrix``. For usage information about ``deepTools plotProfile``, please see the `documentation <https://deeptools.readthedocs.io/en/develop/content/tools/plotProfile.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 for them (see example Snakemake rule below).

  +----------------------------+---------------------+---------------------+-------------+
  | PlotProfile option         | Output              | Name of output      | Recommended |
  |                            |                     |                     |             |
  |                            |                     | variable to be used | extension(s)|
  +============================+=====================+=====================+=============+
  | -\-outFileName, -out, -o   | profile plot        | plot_img            | ".png" or   |
  |                            |                     |                     |             |
  |                            |                     | (required)          | ".eps" or   |
  |                            |                     |                     |             |
  |                            |                     |                     | ".pdf" or   |
  |                            |                     |                     |             |
  |                            |                     |                     | ".svg"      |
  +----------------------------+---------------------+---------------------+-------------+
  | -\-outFileSortedRegions    | BED file with       | regions             | ".bed"      |
  |                            |                     |                     |             |
  |                            | sorted regions      |                     |             |
  +----------------------------+---------------------+---------------------+-------------+
  | -\-outFileNameData         | tab-separated table | data                | ".tab"      |
  |                            |                     |                     |             |
  |                            | for average profile |                     |             |
  +----------------------------+---------------------+---------------------+-------------+



Example
-------

This wrapper can be used in the following way:

.. code-block:: python

    rule plot_profile:
        input:
             # matrix file from deepTools computeMatrix tool
             "matrix.gz"
        output:
            # Please note that --outFileSortedRegions and --outFileNameData 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/plotprofile.html.
            # Through the output variables image file and more output options for plot profile can be selected.
            plot_img="plot_profile/plot.png",  # required
            # optional output files
            regions="plot_profile/regions.bed",
            data="plot_profile/data.tab"
        log:
            "logs/deeptools/plot_profile.log"
        params:
            # optional parameters
            "--plotType=fill "
            "--perGroup "
            "--colors red yellow blue "
            "--dpi 150 "
        wrapper:
            "v3.0.1/bio/deeptools/plotprofile"

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_data = snakemake.output.get("data")

    optional_output = ""

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

    if out_data:
        optional_output += " --outFileNameData {out_data} ".format(out_data=out_data)

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


.. |nl| raw:: html

   <br>