annotate chicSignificantInteractions.xml @ 2:3df84bb4486c draft

"planemo upload for repository https://github.com/galaxyproject/tools-iuc/tree/master/tools/hicexplorer commit 4b602d427e0fc0da5353a4510798349de98e4ae4"

<tool id="hicexplorer_chicsignificantinteractions" name="@BINARY@" version="@WRAPPER_VERSION@.0">
    <description>computes viewpoints with the given reference points and a background model</description>
    <macros>
        <token name="@BINARY@">chicSignificantInteractions</token>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements" />
    <command detect_errors="exit_code"><![CDATA[
        #import re

        mkdir interactionFiles &&
        mkdir targetFolder &&
        mkdir significantFilesFolder &&

        #for $file in $interactionFiles:
            #set identifier = @ESCAPE_IDENTIFIER_FILE@

            ln -s '$file' 'interactionFiles/$identifier' &&
        #end for

        #if $batchmode_conditional.batchmode_selector == 'optionSinglemode':
            #set $interactonfileslist = ' '.join([ '\'interactionFiles/%s\'' % @ESCAPE_IDENTIFIER_FILE@ for $file in $interactionFiles ])
        #end if
        @BINARY@
            #if $batchmode_conditional.batchmode_selector == 'optionSinglemode':
                --interactionFile $interactonfileslist
                --computeSampleNumber $batchmode_conditional.computeSampleNumber

            #else:
                --interactionFile $batchmode_conditional.interactionFilesOrderFile
                --interactionFileFolder interactionFiles
                --batchMode
                --targetFileList targetListFile.txt
                --writeFileNamesToFile significantFiles.txt
                --computeSampleNumber $batchmode_conditional.computeSampleNumber
            #end if

            --pValue $pvalue

            #if $filter_conditional.filter_selector == 'optionXfold':
                --xFoldBackground $filter_conditional.xfold
            #else:
                --loosePValue $filter_conditional.loosePvalue

            #end if
            --backgroundModelFile '$backgroundModelFile'
            --resolution $resolution
            --peakInteractionsThreshold $peakInteractionsThreshold
            --range $rangeUpstream $rangeDownstream
            --targetFolder targetFolder
            --outputFolder significantFilesFolder

            --xFoldMaxValueNB $xFoldMaxValueNB
            --fixateRange $fixateRange
            -suffix significant_interactions.txt
            --threads @THREADS@
    ]]></command>
    <inputs>
        <param name='interactionFiles' type="data" format="interval" label="Interaction files" multiple="true"/>
        <conditional name="batchmode_conditional">
            <param name="batchmode_selector" type="select" label="Compute files individually or in batch mode">
                <option value="optionBatchmode">Batch processing</option>
                <option value="optionSinglemode" selected="True">Single file processing</option>
            </param>
            <when value="optionBatchmode">
                <param name='interactionFilesOrderFile' type="data" format="txt" label="Interaction file order"/>
                <param name='computeSampleNumber' type="integer" value='2' label="Create one target file for n consecutive files."/>
            </when>
            <when value="optionSinglemode">
                <param name='computeSampleNumber' type="integer" value='2' label="Create one target file for n consecutive files."/>
            </when>
        </conditional>
        <param name='pvalue' type="float" value='0.05' label="P-value of interaction to be accepted as significant"/>
        <conditional name="filter_conditional">
            <param name="filter_selector" type="select" label="List of chromosomes or a BED file containg regions">
                <option value="optionXfold">x-fold over mean background</option>
                <option value="optionLoosePvalue" selected="True">Loose p-value (NB background)</option>
            </param>
            <when value="optionXfold">
                <param name='xfold' type="float" value='2.0' label="X-fold over mean background to be accepted." help='Filter x-fold over background. Used to merge neighboring bins with a broader peak but
                                                    less significant interactions to one peak with high significance. Used only for pValue option.'/>
            </when>
            <when value="optionLoosePvalue">
                <param name='loosePvalue' type="float" value='0.3' label="Loose p-value" help='loose p-value threshold value to filter target regions in a first round.
                                                    Used to merge neighboring bins with a broader peak but less significant interactions to one peak with high significance.
                                                    Used only for pValue option.'/>
            </when>
        </conditional>
        <param argument="--backgroundModelFile" type="data" format='tabular'
                        label="Background model"
                        help="The background file computed by chicViewpointBackgroundModel" />
        <param argument="--peakInteractionsThreshold" type="integer" value="5"  label="Minimum interactions" help='The minimum number of interactions a detected peaks needs to have to be considered.'/>
        <param argument="--resolution" type="integer" value="1000"  label="Bin resolution of the used data" help='Resolution of the bin in genomic units. Values are usually e.g. 1000 for a 1kb, 5000 for a 5kb or 10000 for a 10kb resolution.
                           This value is used to merge neighboring bins.'/>
        <param name="rangeUpstream" type="integer" value="500000"  label="Upstream range" help='Defines the region upstream of a reference point which should be considered in the analysis.' />
        <param name="rangeDownstream" type="integer" value="500000"  label="Downstream range" help='Defines the region upstream of a reference point which should be considered in the analysis.' />
        <param argument="--fixateRange" type="integer" value="500000"  label="Clip background distance" help='Fixate score of background model starting at distance x. E.g. all values greater 500kb are set to the value of the 500kb bin.'/>
        <param argument="--xFoldMaxValueNB" type="integer" value="10"  label="x-fold for NB distributions" help='x-fold factor to increase the number of precomputed p-values per relative genomic distance. If set to 1, the maximal distance is used.'/>
    </inputs>
    <outputs>
        <collection name="significantFilesCollection" type="list" label="Significant files">
            <discover_datasets pattern="__name__" format="interval" directory="significantFilesFolder" />
        </collection>
        <collection name="targetFilesCollection" type="list" label="Target files">
            <discover_datasets pattern="__name__" format="interval" directory="targetFolder" />
        </collection>
        <data name="significantFileNames" from_work_dir="significantFiles.txt" format="txt" label="${tool.name} significant file names">
            <filter>batchmode_conditional.batchmode_selector == 'optionBatchmode'</filter>
        </data>
        <data name="targetFileNames" from_work_dir="targetListFile.txt" format="txt" label="${tool.name} target file names">
            <filter>batchmode_conditional.batchmode_selector == 'optionBatchmode'</filter>
        </data>
    </outputs>
    <tests>
        <test>
            <param name="interactionFiles" value="cHi-C/chicViewpoint/output_3/FL-E13-5_chr1_chr1_14300280_14300280_Eya1.txt,cHi-C/chicViewpoint/output_3/FL-E13-5_chr1_chr1_4487435_4487435_Sox17.txt,cHi-C/chicViewpoint/output_3/FL-E13-5_chr1_chr1_19093103_19093103_Tfap2d.txt,cHi-C/chicViewpoint/output_3/MB-E10-5_chr1_chr1_19093103_19093103_Tfap2d.txt,cHi-C/chicViewpoint/output_3/MB-E10-5_chr1_chr1_14300280_14300280_Eya1.txt,cHi-C/chicViewpoint/output_3/MB-E10-5_chr1_chr1_4487435_4487435_Sox17.txt"/>
            <conditional name="batchmode_conditional">
                <param name="batchmode_selector" value='optionBatchmode'/>
                <param name="interactionFilesOrderFile" value='cHi-C/chicViewpoint/fileNames_two_matrices.txt'/>
                <param name="computeSampleNumber" value='2'/>
            </conditional>
            <param name="pvalue" value='0.2'/>

            <conditional name="filter_conditional">
                <param name="filter_selector" value='optionLoosePvalue'/>
                <param name="loosePvalue" value='0.5'/>
            </conditional>

            <param name="backgroundModelFile" value="cHi-C/background.txt"/>
            <param name="rangeUpstream" value="200000"/>
            <param name="rangeDownstream" value="200000"/>

            <output_collection name="significantFilesCollection" type="list" count="6">
                <element name="FL-E13-5_chr1_chr1_4487435_4487435_Sox17_significant_interactions.txt" file="cHi-C/chicSignificantInteractions/output_5/FL-E13-5_chr1_chr1_4487435_4487435_Sox17_output_significant.txt" ftype="interval" lines_diff="4"/>
                <element name="FL-E13-5_chr1_chr1_14300280_14300280_Eya1_significant_interactions.txt" file="cHi-C/chicSignificantInteractions/output_5/FL-E13-5_chr1_chr1_14300280_14300280_Eya1_output_significant.txt" ftype="interval" lines_diff="4"/>
                <element name="FL-E13-5_chr1_chr1_19093103_19093103_Tfap2d_significant_interactions.txt" file="cHi-C/chicSignificantInteractions/output_5/FL-E13-5_chr1_chr1_19093103_19093103_Tfap2d_output_significant.txt" ftype="interval" lines_diff="4"/>

                <element name="MB-E10-5_chr1_chr1_4487435_4487435_Sox17_significant_interactions.txt" file="cHi-C/chicSignificantInteractions/output_5/MB-E10-5_chr1_chr1_4487435_4487435_Sox17_output_significant.txt" ftype="interval" lines_diff="4"/>
                <element name="MB-E10-5_chr1_chr1_14300280_14300280_Eya1_significant_interactions.txt" file="cHi-C/chicSignificantInteractions/output_5/MB-E10-5_chr1_chr1_14300280_14300280_Eya1_output_significant.txt" ftype="interval" lines_diff="4"/>
                <element name="MB-E10-5_chr1_chr1_19093103_19093103_Tfap2d_significant_interactions.txt" file="cHi-C/chicSignificantInteractions/output_5/MB-E10-5_chr1_chr1_19093103_19093103_Tfap2d_output_significant.txt" ftype="interval" lines_diff="4"/>
            </output_collection>

            <output_collection name="targetFilesCollection" type="list" count="3">
                <element name="FL-E13-5_MB-E10-5_chr1_chr1_4487435_4487435_Sox17_target.txt" file="cHi-C/chicSignificantInteractions/output_5_target/FL-E13-5_MB-E10-5_chr1_chr1_4487435_4487435_Sox17_target.txt" ftype="interval" lines_diff="4"/>
                <element name="FL-E13-5_MB-E10-5_chr1_chr1_14300280_14300280_Eya1_target.txt" file="cHi-C/chicSignificantInteractions/output_5_target/FL-E13-5_MB-E10-5_chr1_chr1_14300280_14300280_Eya1_target.txt" ftype="interval" lines_diff="4"/>
                <element name="FL-E13-5_MB-E10-5_chr1_chr1_19093103_19093103_Tfap2d_target.txt" file="cHi-C/chicSignificantInteractions/output_5_target/FL-E13-5_MB-E10-5_chr1_chr1_19093103_19093103_Tfap2d_target.txt" ftype="interval" lines_diff="4"/>
            </output_collection>
            <output name="targetFileNames" file="cHi-C/chicSignificantInteractions/output_5_target_list.txt" ftype="txt" compare="sim_size" delta='40000'/>
            <output name="significantFileNames" file="cHi-C/chicSignificantInteractions/output_5_significant_files.txt" ftype="txt" compare="sim_size" delta='40000'/>
        </test>
        <test>
            <param name="interactionFiles" value="cHi-C/chicViewpoint/output_1/FL-E13-5_chr1_chr1_14300280_14300280_Eya1.txt,cHi-C/chicViewpoint/output_1/MB-E10-5_chr1_chr1_14300280_14300280_Eya1.txt"/>
            <conditional name="batchmode_conditional">
                <param name="batchmode_selector" value='optionSinglemode'/>
                <param name="computeSampleNumber" value="1"/>
            </conditional>
            <param name="pvalue" value='0.2'/>

            <conditional name="filter_conditional">
                <param name="filter_selector" value='optionXfold'/>
                <param name="xfold" value='1.5'/>
            </conditional>

            <param name="backgroundModelFile" value="cHi-C/background.txt"/>
            <param name="rangeUpstream" value="200000"/>
            <param name="rangeDownstream" value="200000"/>

            <output_collection name="significantFilesCollection" type="list" count="2">
               <element name="FL-E13-5_chr1_chr1_14300280_14300280_Eya1_significant_interactions.txt" file="cHi-C/chicSignificantInteractions/output_3/FL-E13-5_chr1_chr1_14300280_14300280_Eya1_output_significant.txt" ftype="interval" lines_diff="4"/>
               <element name="MB-E10-5_chr1_chr1_14300280_14300280_Eya1_significant_interactions.txt" file="cHi-C/chicSignificantInteractions/output_3/MB-E10-5_chr1_chr1_14300280_14300280_Eya1_output_significant.txt" ftype="interval" lines_diff="4"/>
            </output_collection>

            <output_collection name="targetFilesCollection" type="list" count="2">
                <element name="FL-E13-5_chr1_chr1_14300280_14300280_Eya1_target.txt" file="cHi-C/chicSignificantInteractions/output_3_target/FL-E13-5_chr1_chr1_14300280_14300280_Eya1_target.txt" ftype="interval" lines_diff="4"/>
                <element name="MB-E10-5_chr1_chr1_14300280_14300280_Eya1_target.txt" file="cHi-C/chicSignificantInteractions/output_3_target/MB-E10-5_chr1_chr1_14300280_14300280_Eya1_target.txt" ftype="interval" lines_diff="4"/>
            </output_collection>
        </test>

    </tests>
    <help><![CDATA[

Significant interaction detection
=================================

Significant interactions are detected by this tool for each viewpoint based on the background model. chicSignificantInteractions outputs for each viewpoint a file containing all recorded significant interactions and
a target file. The target file is especially useful in the batch mode context, as it merges for two consecutive listed control and treatment viewpoint the significant interactions which can then be used
to test for a differential interaction scheme.

chicSignificantInteractions supports two modes to detect significant interactions, either by an x-fold over the average background or a loose p-value. In both cases neighboring significant peaks are merged together and an additional
p-value based on the sum of interactions for this neighborhood is computed. Only interactions with a higher p-value as specified by the threshold `--pValue` are accepted as a significant interaction.

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>