annotate hicPlotMatrix.xml @ 8:d398f5373c70 draft

planemo upload for repository https://github.com/maxplanck-ie/HiCExplorer/tree/master/galaxy/wrapper/ commit 0456f085bac2c88b8cbddfcf12b02776d2a0d457

<tool id="hicexplorer_hicplotmatrix" name="@BINARY@" version="@WRAPPER_VERSION@.0">
    <description>Plots a HiC matrix heatmap</description>
    <macros>
        <token name="@BINARY@">hicPlotMatrix</token>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements" />
    <command detect_errors="exit_code"><![CDATA[

        #if str($pca_conditional.pca_type) == 'bigwig':
            ln -s $pca_conditional.pca_bigwig pca.bw &&
            #set $pca = '--bigwig pca.bw'
        #elif str($pca_conditional.pca_type) == '':
            #set $pca = ''
        #end if
        
        @BINARY@

            --matrix '$matrix_h5_cooler'

            #if $title and $title is not None:
                --title '$title'
            #end if

            #if $scoreName and $scoreName is not None:
                --scoreName '$scoreName'
            #end if

            --outFileName plot.$image_file_format

            $perChromosome
            $clearMaskedBins

            ## special: --chromosomeOrder is optional, but if given needs at least one argument
            #set chroms = '" "'.join([ str($var.chromosome) for $var in $chromosomeOrder ])
            #if chroms:
                --chromosomeOrder "$chroms"
            #end if

            #if $region:
                --region '$region'
            #end if

            #if $region2:
                --region2 '$region2'
            #end if
            $log1p
            $log

            #if $colormap:
                --colorMap $colormap
            #end if

            #if $vMin:
                --vMin $vMin
            #end if

            #if $vMax:
                --vMax $vMax
            #end if

            $pca

        && mv plot.$image_file_format plot
]]>
    </command>
    <inputs>
        <expand macro='matrix_h5_cooler_macro' />

        <param argument="--title" type="text" optional="true" label="Plot title"/>
        <param argument="--scoreName" type="text" optional="true" label="Score name"/>
        <param argument="--perChromosome" type="boolean" truevalue="--perChromosome" falsevalue="" checked="false"
            label="Plot per chromosome"
            help="Instead of plotting the whole matrix each chromosome is plotted next to the other. This parameter is not compatible with --region" />
        <param argument="--clearMaskedBins" type="boolean" truevalue="--clearMaskedBins" falsevalue="" checked="false"
            label="Remove masked bins from the matrix"  />

        <repeat name="chromosomeOrder" min="0" title="Chromosomes to include (and order to plot in):"
            help="This option overrides --region and --region2" >
            <param name="chromosome" type="text" >
                <validator type="empty_field" />
            </param>
        </repeat>

        <param argument="--region" type="text" optional="True" label="Plot only this region"
            help="The format is chr:start-end The plotted region contains the main diagonal and is symmetric unless  --region2 is given"/>
        <param argument="--region2" type="text" optional="True" label="Region two to plot"
            help="If given then only the region defined by --region and --region2 is plotted. The format is the same as --region"/>
        <param argument="--log1p" type="boolean" truevalue="--log1p" falsevalue="" checked="false" label="Plot the log1p of the matrix values."/>
        <param argument="--log" type="boolean" truevalue="--log" falsevalue="" checked="false" label="Plot the log of the matrix values."/>

        <expand macro="colormap" />

        <param argument="--vMin" type="float" optional="true" label="vMin"/>
        <param argument="--vMax" type="float" optional="true" label="vMax"/>

        <conditional name="pca_conditional">
            <param name='pca_type' label='Datatype of eigenvector file' type='select'>
                <option value='' selected="true"></option>
                <option value='bigwig'>bigwig</option>
            </param>
            <when value='' />
            <when value='bigwig'>
                <param name='pca_bigwig'  type="data" format="bigwig" 
                            label="Eigenvector file"/>
            </when>
        </conditional>
        <param name="image_file_format" type="select" label="Image output format">
            <option value="png" selected="True">png</option>
            <option value="svg">svg</option>
        </param>
    </inputs>
    <outputs>
        <data format="png" name="outFileName" from_work_dir="plot" label="${tool.name} on ${on_string}">
            <change_format>
                <when input="image_file_format" value="svg" format="svg" />
            </change_format>
        </data>
    </outputs>
    <tests>
        <test>
            <param name="matrix_h5_cooler" value="Li_et_al_2015.h5"/>
            <conditional name="pca_conditional">
                <param name="pca_type" value=''/>
            </conditional>
            <param name="region" value="chrX:3000000-3500000"/>
            <param name="region2" value="chrX:3100000-3600000"/>
            <param name="log1p" value="True"/>
            <param name="clearMaskedBins" value="True"/>
            <param name="image_file_format" value="png" />
            <output name="outFileName" file="master_matrix_plot.png" ftype="png" compare="sim_size"/>
        </test>
        <test>
            <param name="matrix_h5_cooler" value="Li_et_al_2015.cool"/>
            <conditional name="pca_conditional">
                <param name="pca_type" value=''/>
            </conditional>
            <param name="region" value="X:3000000-3500000"/>
            <param name="image_file_format" value="png" />
            <output name="outFileName" file="Li_chrX30-35_cool.png" ftype="png" compare="sim_size"/>
        </test>
        <test>
            <param name="matrix_h5_cooler" value="pearson_small_50kb.cool"/>
            <param name="perChromosome" value="True"/>
            <conditional name="pca_conditional">
                <param name="pca_type" value='bigwig'/>
                <param name="pca_bigwig" value="pca1.bw"/>
            </conditional>
            <param name='colormap' value='hot'/>
            <param name="image_file_format" value="svg" />
            <output name="outFileName" file="small_matrix_50kb_pearson_pca1_plot.svg" ftype="svg" compare="sim_size" delta='35000'/>
        </test>
        <test>
            <param name="matrix_h5_cooler" value="pearson_small_50kb.h5"/>
            <param name="perChromosome" value="True"/>
            <conditional name="pca_conditional">
                <param name="pca_type" value='bigwig'/>
                <param name="pca_bigwig" value="pca1.bw"/>
            </conditional>
            <param name='colormap' value='hot'/>
            
            <param name="image_file_format" value="svg" />
            <output name="outFileName" file="small_matrix_50kb_pearson_pca1_plot.svg" ftype="svg" compare="sim_size" delta='35000'/>
        </test>
    </tests>
    <help><![CDATA[
Contact matrix plot
=======================

``hicPlotMatrix`` is a visualization tool for a contact matrix. It supports to plot the whole contact matrix, one or more chromosomes, a region or two regions against each other.
 Additional it can plot the result of a principal component analysis to have a better understanding of A / B compartments.

Input
-----

Parameters
__________
- the contact matrix: h5 or cool file format.
- A title for the plot
- Score name
- per chromosome
- The chromosomes to include in the plot. 
- What to show: 
- The region(s) to plot. This parameter overrides 'chromosome'. If either 'chromosomes' or 'region' is given the full contact matrix is used.
- log / log1p of the values: It is recommended to use log1p.
- Colormaps_ for the heatmap. 
- vMin / vMax
- principal component: a bigwig file containing eigenvector information

Output
------

The contact matrix plotted for chromosome 1.

.. image:: SRR027956.svg
   :width: 60%


The contact matrix used with ``--perChr`` and the first eigenvector from the tool ``hicPCA``. For this plot a pearson correlated matrix was used which is computed by creating first an observed / expected matrix and second a pearson correlation matrix. These matricies can be computed with ``hicChangeMatrixType``. The used Hi-C data were published by `Lieberman-Aiden <https://doi.org/10.1126/science.1181369>`_ in 2009, `GSE18199 <https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE18199>`_.

.. image:: $PATH_TO_IMAGES/SRR0279XX_perChr_eigenvector1.png
   :width: 70 %

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

.. _readthedocs.io: http://hicexplorer.readthedocs.io/en/latest/index.html
.. _Colormaps: https://matplotlib.org/examples/color/colormaps_reference.html
]]></help>
    <expand macro="citations" />
</tool>