annotate chicSignificantInteractions.xml @ 5:6bc82c6d6620 draft

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

<tool id="hicexplorer_chicsignificantinteractions" name="@BINARY@" version="@WRAPPER_VERSION@.1">
    <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 &&

        #if $tar_input_conditional.tar_input_selector == 'tar_input':
            ln -s '$tar_input_conditional.interactionFiles' viewpoints.tar && 
            tar -C interactionFiles -xvf viewpoints.tar &&
        #else:
            #for $file in $tar_input_conditional.interactionFiles:
                #set identifier = @ESCAPE_IDENTIFIER_FILE@
                                    
                ln -s '$file' 'interactionFiles/$identifier' &&
            #end for
        #end if
    
        #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
            $truncateZeroPvalues
            --fixateRange $fixateRange
            -suffix significant_interactions.txt
            --threads @THREADS@

            #if $tar:
                && cd targetFolder
                && tar -cvf ../targetFolder.tar *
                && cd ..
                && rm -rf targetFolder

                && cd significantFilesFolder
                && tar -cvf ../significantFilesFolder.tar *
                && cd ..
                && rm -rf significantFilesFolder

            #end if
    ]]></command>
    <inputs>
        <conditional name="tar_input_conditional">
            <param name="tar_input_selector" type="select" label="Compute files individually or in batch mode">
                <option value="tar_input">Tar file</option>
                <option value="interval_input" selected="True">Interval files</option>
            </param>
            <when value="tar_input">
        <param name='interactionFiles' type="data" format="tar" label="Interaction files" multiple="false"/>
            </when>
            <when value="interval_input">
        <param name='interactionFiles' type="data" format="interval" label="Interaction files" multiple="true"/>
            </when>
        </conditional>



        <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 name='truncateZeroPvalues' type='boolean' truevalue='--truncateZeroPvalues'  falsevalue="" checked="false" label="Truncate zeros by setting them to one."
                    help="Sets all p-values which are equal to zero to one. This has the effect that the associated positions are not part of the significance decision."/>
        <param name='tar' type='boolean' checked="false" truevalue='True' label="tar output to one file"
                    help="The output is tarred to one file and not written to a collection. Set this option if the number of files is large."/>
    </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>
        <data name="targetFolderTar" from_work_dir="targetFolder.tar" format="tar" label="Target files tar">
            <filter>tar</filter>
        </data>
        <data name="significantFilesFolderTar" from_work_dir="significantFilesFolder.tar" format="tar" label="Significant files tar">
            <filter>tar</filter>
        </data>
    </outputs>
    <tests>
        <test>
            <conditional name="tar_input_conditional">
                <param name="tar_input_selector" value='interval_input'/>
                <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>
            <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_significant_interactions.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_significant_interactions.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_significant_interactions.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_significant_interactions.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_significant_interactions.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_significant_interactions.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>
            <conditional name="tar_input_conditional">
                <param name="tar_input_selector" value='interval_input'/>
                <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>
            <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> 

        <test>
            <conditional name="tar_input_conditional">
                <param name="tar_input_selector" value='interval_input'/>
                <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>
            <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"/>

            <param name='tar' value='True'/>

            <output name="targetFolderTar" file="cHi-C/chicSignificantInteractions/targetFolder.tar" ftype='tar' compare="sim_size" delta='40000' />
            <output name="significantFilesFolderTar" file="cHi-C/chicSignificantInteractions/significantFilesFolder.tar" ftype='tar' compare="sim_size" delta='40000' />

            <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>
            <conditional name="tar_input_conditional">
                <param name="tar_input_selector" value='tar_input'/>
                <param name="interactionFiles" value="cHi-C/chicViewpoint/viewpoints.tar"/>
            </conditional>
            <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"/>

            <param name='tar' value='True'/>

            <output name="targetFolderTar" file="cHi-C/chicSignificantInteractions/targetFolder.tar" ftype='tar' compare="sim_size" delta='40000' />
            <output name="significantFilesFolderTar" file="cHi-C/chicSignificantInteractions/significantFilesFolder.tar" ftype='tar' compare="sim_size" delta='40000' />

            <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>

    </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>