.. _`bio/deeptools/computematrix`:

DEEPTOOLS COMPUTEMATRIX
=======================


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

``deepTools computeMatrix`` calculates scores per genomic region. The matrix file can be used as input for other tools or for the generation of a ``deepTools plotHeatmap`` or ``deepTools plotProfiles``. For usage information about ``deepTools computeMatrix``, please see the `documentation <https://deeptools.readthedocs.io/en/develop/content/tools/computeMatrix.html>`_. For more information about ``deepTools``, also see the `source code <https://github.com/deeptools/deepTools>`_.

  +----------------------------+-----------------------------+---------------------+-------------+
  | computeMatrix option       | Output format               | Name of output      | Recommended |
  |                            |                             |                     |             |
  |                            |                             | variable to be used | extension   |
  +============================+=============================+=====================+=============+
  | -\-outFileName, -out, -o   | gzipped matrix file         | matrix_gz           | ".gz"       |
  |                            |                             |                     |             |
  |                            |                             | (required)          |             |
  +----------------------------+-----------------------------+---------------------+-------------+
  | -\-outFileNameMatrix       | tab-separated table of      | matrix_tab          | ".tab"      |
  |                            |                             |                     |             |
  |                            | matrix file                 |                     |             |
  +----------------------------+-----------------------------+---------------------+-------------+
  | -\-outFileSortedRegions    | BED matrix file with sorted | matrix_bed          | ".bed"      |
  |                            |                             |                     |             |
  |                            | regions after skipping zeros|                     |             |
  |                            |                             |                     |             |
  |                            | or min/max threshold values |                     |             |
  +----------------------------+-----------------------------+---------------------+-------------+


**URL**: https://deeptools.readthedocs.io/en/develop/content/tools/computeMatrix.html

Example
-------

This wrapper can be used in the following way:

.. code-block:: python

    rule compute_matrix:
        input:
            # Please note that the -R and -S options are defined via input files
            bed=expand("{sample}.bed", sample=["a", "b"]),
            bigwig=expand("{sample}.bw", sample=["a", "b"]),
            # Optional blacklist file
            # blacklist="",
        output:
            # Please note that --outFileName, --outFileNameMatrix and --outFileSortedRegions 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/computematrix.html.
            matrix_gz="matrix_files/matrix.gz",  # required
            # optional output files
            matrix_tab="matrix_files/matrix.tab",
            matrix_bed="matrix_files/matrix.bed",
        log:
            "logs/deeptools/compute_matrix.log",
        params:
            # required argument, choose "scale-regions" or "reference-point"
            command="scale-regions",
            # optional parameters
            extra="--regionBodyLength 200 --verbose",
        wrapper:
            "v3.0.1/bio/deeptools/computematrix"

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.


Notes
-----

['Bigwig DeepBlue URL, if any, should be given in `params.extra`, or downloaded separately.']

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

* ``deeptools=3.5.4``

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

* ``bed``: Path to BED or GTF files (.bed or .gtf) AND
* ``bigwig``: Path to bigWig files (.bw)

**Output:**

* ``matrix_gz``: gzipped matrix file (.gz) AND/OR
* ``matrix_tab``: tab-separated table of matrix file (.tab) AND/OR
* ``matrix_bed``: BED matrix file with sorted regions after skiping zeros or min/max threshold values (.bed)



Params
------

* ``command``: Either `scale-regions` or `reference-point`

* ``extra``: Optional parameters given to computeMatrix




Authors
-------

* Antonie Vietor
* Thibault Dayris


Code
----

.. code-block:: python

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

    from snakemake.shell import shell
    from tempfile import TemporaryDirectory

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

    blacklist = snakemake.input.get("blacklist", "")
    if blacklist:
        blacklist = f"--blackListFileName {blacklist}"

    out_tab = snakemake.output.get("matrix_tab")
    out_bed = snakemake.output.get("matrix_bed")

    optional_output = ""

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

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


    with TemporaryDirectory() as tempdir:
        temp = ""
        if "deepBlueURL" in snakemake.params.extra:
            temp = f"--deepBlueTempDir {tempdir}"

        shell(
            "computeMatrix "
            "{snakemake.params.command} "
            "{snakemake.params.extra} "
            "--numberOfProcessors {snakemake.threads} "
            "-R {snakemake.input.bed} "
            "-S {snakemake.input.bigwig} "
            "-o {snakemake.output.matrix_gz} "
            "{blacklist} {optional_output} {temp} {log}"
        )


.. |nl| raw:: html

   <br>