<tool id="hicexplorer_hiccomparematrices" name="@BINARY@" version="@WRAPPER_VERSION@.0">
    <description>normalize and compare two Hi-C contact matrices</description>
    <macros>
        <token name="@BINARY@">hicCompareMatrices</token>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements" />
    <command detect_errors="exit_code"><![CDATA[
    ln -s '$matrix1' 'matrix1.$matrix1.ext' &&
    ln -s '$matrix2' 'matrix2.$matrix2.ext' &&


    @BINARY@
    --matrices 'matrix1.$matrix1.ext' 'matrix2.$matrix2.ext'
    --operation $operation
    --outFileName 'matrix.$matrix1.ext'

    && mv 'matrix.$matrix1.ext' matrix
]]>
    </command>
    <inputs>
        <param name='matrix1' type="data" format="h5,cool"
            label="First matrix"/>
        <param name='matrix2' type="data" format="h5,cool"
            label="Second matrix to compare against the first"/>

        <param name='operation' type='select' label="Operation to be used for the comparison">
            <option value='diff'>diff</option>
            <option value="ratio">ratio</option>
            <option value="log2ratio">log2ratio</option>
        </param>
    </inputs>
    <outputs>
        <data name="outFileName" from_work_dir="matrix" format="cool" label="${tool.name} MATRIX on ${on_string}">
            <change_format>
                <when input_dataset="matrix1" attribute="ext" value="h5" format="h5"/>
            </change_format>
        </data>
    </outputs>
    <tests>
        <test>
            <param name="matrix1" value="small_test_matrix.h5"/>
            <param name="matrix2" value="small_test_matrix.h5"/>
            <param name="operation" value='log2ratio' />
            <output name="outFileName" ftype="h5">
                <assert_contents>
                    <has_h5_keys keys='intervals,matrix'/>
                </assert_contents>
            </output>
        </test>

    </tests>
    <help><![CDATA[
Comparison of Hi-C matrices
===========================

This tool is useful to compare two matrices by applying operations like difference, ratio or log2ratio after normalization. To
normalize the matrices, each element is divided by the sum of the matrix.

**hicCompareMatrices** can be used for example to determine the effect of a mutation compared to wild-type samples on contact enrichment,
or to see TAD structure modifications near differentially expressed genes between two conditions when followed by ``hicPlotMatrix``.
It can also be used to compare two biological replicates.

_________________

Usage
-----

**hicCompareMatrices** is usually perfomed on corrected matrices (``hicCorrectMatrix``) with bins merged (``hicMergeMatrixBins``) depending
on the downstream analyses to perform (visualisation of a whole chromosome, or of a small region, etc).

_________________

Output
------

Here is an example of a log2ratio comparison between M1BP Knockdown and GST cells in
*Drosophila melanogaster* on corrected matrices with 50 bins merged (about 30kb bins) plotted using ``hicPlotMatrix``.

.. image:: $PATH_TO_IMAGES/hicCompareMatrices_m1bp_over_gst_log2_m50_matrix_plot.png
   :width: 50%

In this plot we see that the cells with a M1BP Knockdown display a negative log2ratio compared to the wild-type. Depletion of M1BP thus show a dramatic effect on the distribution of Hi-C contacts in which short range contacts decrease (Ramirez *et al.* 2017,  High-resolution TADs reveal DNA sequences underlying genome organization in flies, https://doi.org/10.1038/s41467-017-02525-w).

Below you can find an example of a log2ratio plot between Hi-C matrices of two biological replicates, no differences are observable which means that the replicates are well correlated.

.. image:: $PATH_TO_IMAGES/hicCompareMatrices_QC_log2_m50_matrix_plot.png
   :width: 50%

_________________

| For more information about HiCExplorer please consider our documentation on readthedocs.io_

.. _readthedocs.io: http://hicexplorer.readthedocs.io/en/latest/index.html
]]></help>
    <expand macro="citations" />
</tool>