annotate transit_resampling.xml @ 3:0e0618c96ca4 draft

"planemo upload for repository https://github.com/galaxyproject/tools-iuc/tree/master/tools/transit/ commit bd061799ebd49ada1a666d0815720c18291728da"

<?xml version="1.0"?>
<tool id="transit_resampling" name="Resampling" version="@VERSION@+galaxy2">
    <description>- determine per-gene p-values</description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements" />
    <command detect_errors="exit_code"><![CDATA[
    	@LINK_INPUTS@
        #set $control_files = ','.join(['control_file_%d.wig' % idx for idx, _ in enumerate(str($controls).split(','))])
        #for idx, filename in enumerate(str($controls).split(',')):
            ln -s '$filename' control_file_${idx}.wig &&
        #end for
        transit resampling $input_files $control_files annotation.dat transit_out.txt
        @STANDARD_OPTIONS@
        -s $samples $histogram $adaptive $exclude_zero $pseudo $loess
        ]]>
    </command>
    <inputs>
        <expand macro="standard_inputs">
            <expand macro="handle_replicates" />
            <param name="controls" type="data" format="wig" multiple="true" label="Control .wig files" />
            <param name="samples" argument="-s" type="integer" value="10000" label="Number of samples" />
            <param name="histogram" argument="-h" type="boolean" truevalue="-h" falsevalue="" label="Output histogram of the permutations" />
            <param name="adaptive" argument="-a" type="boolean" truevalue="-a" falsevalue="" label="Perform adaptive resampling" />
            <param name="exclude_zero" argument="-ez" type="boolean" truevalue="-ez" falsevalue="" label="Exclude rows with zero accross conditions" />
            <param name="pseudo" argument="-pc" type="boolean" truevalue="-pc" falsevalue="" label="Add pseudocounts at each site" />
            <param name="loess" argument="-l" type="boolean" truevalue="-l" falsevalue="" label="Perform LOESS Correction" help="Helps remove possible genomic position bias." />

        </expand>
    </inputs>
    <outputs>
        <expand macro="outputs" />
    </outputs>
    <tests>
        <test>
            <param name="inputs" ftype="wig" value="transit-in1-rep1.wig,transit-in1-rep2.wig" />
            <param name="controls" ftype="wig" value="transit-co1-rep1.wig,transit-co1-rep2.wig,transit-co1-rep3.wig" />
            <param name="annotation" ftype="tabular" value="transit-in1.prot" />
            <param name="samples" value="1000" />
            <param name="burnin" value="100" />
            <param name="replicates" value="Replicates" />
            <output name="sites" file="resampling-sites1.txt" ftype="tabular" compare="sim_size" />
        </test>
    </tests>

    <help>
<![CDATA[.. class:: infomark

**What it does**

-------------------


The re-sampling method is a comparative analysis the allows that can be used to determine conditional essentiality of genes. It is based on a permutation test, and is capable of determining read-counts that are significantly different across conditions.

This technique has yet to be formally published in the context of differential essentiality analysis. Briefly, the read-counts at each genes are determined for each replicate of each condition. The total read-counts in condition A is subtracted from the total read counts at condition B, to obtain an observed difference in read counts. The TA sites are then permuted for a given number of “samples”. For each one of these permutations, the difference is read-counts is determined. This forms a null distribution, from which a p-value is calculated for the original, observed difference in read-counts.


Note : Can be used for both Himar1 and Tn5 datasets


-------------------

**Inputs**

-------------------

Input files for Resampling need to be:

-   .wig files : Tabulated files containing one column with the TA site coordinate and one column with the read count at this site.
-   annotation .prot_table : Annotation file generated by the `Convert Gff3 to prot_table for TRANSIT` tool.


-------------------

**Parameters**

-------------------

Optional Arguments:

-s <integer>    :=  Number of samples. Default: 10000
-n <string>     :=  Normalization method. Default: TTR
-h              :=  Output histogram of the permutations for each gene. Default: Off.
-a              :=  Perform adaptive resampling. Default: Off.
-ez             :=  Exclude rows with zero accross conditions. Default: Off
--pc            :=  Pseudocounts to be added at each site. Default: 0
-l              :=  Perform LOESS Correction; Helps remove possible genomic position bias. Default: Off.
-r <string>     :=  How to handle replicates. Sum, Mean. Default: -r Mean
--iN <float>     :=  Ignore TAs occuring at given fraction of the N terminus. Default: 0.0
--iC <float>     :=  Ignore TAs occuring at given fraction of the C terminus. Default: 0.0
--ctrl_lib      :=  String of letters representing library of control files in order e.g. 'AABB' Default: empty. Letters used must also be used in --exp_lib. If non-empty, resampling will limit permutations to within-libraries.
--exp_lib    :=  String of letters representing library of experimental files in order e.g. 'ABAB' Default: empty. Letters used must also be used in --ctrl_lib. If non-empty, resampling will limit permutations to within-libraries.


The resampling method is non-parametric, and therefore does not require any parameters governing the distributions or the model. The following parameters are available for the method:

-   Samples: The number of samples (permutations) to perform. The larger the number of samples, the more resolution the p-values calculated will have, at the expense of longer computation time. The re-sampling method runs on 10,000 samples by default.
-   Output Histograms:Determines whether to output .png images of the histograms obtained from resampling the difference in read-counts.
-   Adaptive Resampling: An optional “adaptive” version of resampling which accelerates the calculation by terminating early for genes which are likely not significant. This dramatically speeds up the computation at the cost of less accurate estimates for those genes that terminate early (i.e. deemed not significant). This option is OFF by default.
-   Include Zeros: Select to include sites that are zero. This is the preferred behavior, however, unselecting this (thus ignoring sites that) are zero accross all dataset (i.e. completely empty), is useful for decreasing running time (specially for large datasets like Tn5).
-   Normalization Method: Determines which normalization method to use when comparing datasets. Proper normalization is important as it ensures that other sources of variability are not mistakenly treated as real differences. See the Normalization section for a description of normalization method available in TRANSIT.
    - TTR (Default) : Trimmed Total Reads (TTR), normalized by the total read-counts (like totreads), but trims top and bottom 5% of read-counts. This is the recommended normalization method for most cases as it has the beneffit of normalizing for difference in saturation in the context of resampling.
    - nzmean : Normalizes datasets to have the same mean over the non-zero sites.
    - totreads : Normalizes datasets by total read-counts, and scales them to have the same mean over all counts.
    - zinfnb : Fits a zero-inflated negative binomial model, and then divides read-counts by the mean. The zero-inflated negative binomial model will treat some empty sites as belonging to the “true” negative binomial distribution responsible for read-counts while treating the others as “essential” (and thus not influencing its parameters).
    - quantile : Normalizes datasets using the quantile normalization method described by Bolstad et al. (2003). In this normalization procedure, datasets are sorted, an empirical distribution is estimated as the mean across the sorted datasets at each site, and then the original (unsorted) datasets are assigned values from the empirical distribution based on their quantiles.
    - betageom : Normalizes the datasets to fit an “ideal” Geometric distribution with a variable probability parameter p. Specially useful for datasets that contain a large skew. See Beta-Geometric Correction .
    - nonorm : No normalization is performed.


-------------------

**Outputs**

-------------------

The re-sampling method outputs a tab-delimited file with results for each gene in the genome. P-values are adjusted for multiple comparisons using the Benjamini-Hochberg procedure (called “q-values” or “p-adj.”). A typical threshold for conditional essentiality on is q-value < 0.05.


=============================================   ========================================================================================================================
**Column Header**                               **Column Definition**
---------------------------------------------   ------------------------------------------------------------------------------------------------------------------------
Orf                                             Gene ID
Name                                            Gene Name
Desc                                            Gene Description
N                                               Number of TA sites in the gene.
TAs Hit                                         Number of TA sites with at least one insertion.
Sum Rd 1                                        Sum of read counts in condition 1.
Sum Rd 2                                        Sum of read counts in condition 2.
Delta Rd                                        Difference in the sum of read counts.
p-value                                         P-value calculated by the permutation test.
p-adj.                                          Adjusted p-value controlling for the FDR (Benjamini-Hochberg)
=============================================   ========================================================================================================================



-------------------

**More Information**

-------------------

See  `TRANSIT documentation`

- TRANSIT: https://transit.readthedocs.io/en/latest/index.html
- `TRANSIT Gumbel`: https://transit.readthedocs.io/en/latest/transit_methods.html#re-sampling
]]></help>

    <expand macro="citations" />
</tool>