annotate calc_fitness.xml @ 11:1bc740b6462d draft default tip

Uploaded

<tool id="calc_fitness" name="Calculate Fitness">
  <description>of transposon insertion locations</description>
  <requirements>
    <requirement type="package" version="1.64">biopython</requirement>
  </requirements>
  <command interpreter="python">
    calc_fitness.py 
    -ef $ef 
    -el $el 
    -wig $output3 
    -t1 $t1 
    -t2 $t2 
    -ref $ref 
    -out $output 
    -out2 $output2 
    -expansion $expansion
    -maxweight $maxweight
    -cutoff $cutoff
    -cutoff2 $cutoff2
    -strand $strand
    #if $normalization.calculations  == "yes":
      -normalize $normalization.genes
    #end if
    #if $multiply.choice  == "yes":
      -multiply $multiply.factor
    #end if
    #if $reads.uncol  == "yes":
      -uncol 1
    #end if
    #if $bottle.all  == "yes":
      -b 1
    #end if
  </command>
  <inputs>
    <param name="t1" type="data" label="Map files from t1"/>
    <param name="t2" type="data" label="Map files from t2"/>
    <param name="ref" type="data" label="GenBank reference genome"/>
    <conditional name="normalization">
      <param name="calculations" type="select" label="Normalize fitness calculations?">
        <option value="no">No</option>
        <option value="yes">Yes</option>
      </param>
      <when value="no">
        <!-- do nothing -->
      </when>
      <when value="yes"> 
        <param name="genes" type="data" label="Genes to normalize by" />
      </when>
    </conditional>
    <param name="strand" type="select" label="Use reads from which strands?">
      <option value="both">both</option>
      <option value="+">Watson (+)</option>
      <option value="-">Crick (-)</option>
    </param>
    <param name="expansion" type="float" value="250" label="Expansion factor"/>
    <param name="cutoff" type="float" value="0.0" label="Cutoff1"/>
    <param name="cutoff2" type="float" value="0.0" label="Cutoff2"/>
    <param name="ef" type="float" value="0.0" label="Exclude first %"/>
    <param name="el" type="float" value="0.0" label="Exclude last %"/>
    <param name="maxweight" type="float" value="75" label="Maximum weight of a transposon gene in normalization calculations"/>
    <conditional name="multiply">
      <param name="choice" type="select" label="Multiply fitness scores by a certain value?">
        <option value="no">No</option>
        <option value="yes">Yes</option>
      </param>
      <when value="no">
        <!-- do nothing -->
      </when>
      <when value="yes"> 
        <param name="factor" type="float" value="0.0" label="Multiply by" />
      </when>
    </conditional>
    <conditional name="bottle">
      <param name="all" type="select" label="Calculate bottleneck value from all genes (rather than only normalization genes)?">
        <option value="no">No</option>
        <option value="yes">Yes</option>
      </param>
      <when value="no">
        <!-- do nothing -->
      </when>
      <when value="yes"> 
        <!-- do nothing -->
      </when>
    </conditional>
    <conditional name="reads">
      <param name="uncol" type="select" label="Were reads uncollapsed when mapped?">
        <option value="no">No</option>
        <option value="yes">Yes</option>
      </param>
      <when value="no">
        <!-- do nothing -->
      </when>
      <when value="yes"> 
        <!-- do nothing -->
      </when>
    </conditional>
  </inputs>
    <outputs>
        <data format="csv" name="output" />
        <data format="txt" name="output2" />
        <data format="wig" name="output3" />
    </outputs>
  <help>

**What it does**

This tool calculates the fitness values of transposon insertion mutations generated by Tn-Seq, by analyzing Illumina sequencing reads from t1 and t2.

**The options explained**

Map files from t1: a bowtie mapfile containing the mapped flanking reads from t1

Map files from t2: a bowtie mapfile containing the mapped flanking reads from t2

GenBank reference genome: the reference genome of whatever model you're working with, which needs to be in standard genbank format. For more on that format see the genbank website.

Normalizing fitness calculations: our normalization relies on the fitness scores of insertions within transposon genes, which ought to have a neutral fitness of 1. The file of normalization genes should be formatted so that each line is a single gene loci like "SP_0017"

Using reads from certain strands: typically users will use reads from both strands, but this lets you do things like comparing reads between strands.

Expansion factor: the expansion factor of the bacteria culture you got your reads from - this is something you should measure when you're growing up the bacteria from t1 to t2. Using the default expansion factor of 250 will give you very rough fitness calculations and so it's not recommended.

Cutoff1: the cutoff for all genes; insertion locations with an average count less than this number will be disregarded, as insertion locations with a low number of reads can have inaccurate fitnesses calculated, for the same reason studies with low sample sizes can be inaccurate.

Cutoff2: the cutoff for the normalization genes; only has an effect if larger than cutoff

Exclude first %: insertions in the very beginning of genes sometimes don't actually interfere with their function, and so you can exclude insertions from the first % of a gene from being counted as within those genes. This mostly affects the aggregate calculations downstream.

Exclude last %: similarly insertions in the very end of genes sometimes don't actually interfere with their function, and so you can exclude insertions from the last % of a gene. Also mostly affects the aggregate calculations downstream.

Maximum weight of a transposon gene in normalization calculations: in the normalization calculations, fitnesses within transposon genes are weighted according to their number of reads, as fitnesses calculated from more reads tend to be more accurate. However, to keep those fitnesses with huge numbers of reads from vastly outweighing the others, you can limit the max weight.

Multiplying fitness scores by a certain value: what it says on the lid; you can multiply the normalized fitness scores by a certain value. This can be helpful for genetic interaction screens, where Tn-seq is performed as usual except there's one background knockout all the mutants share. This is because a combination of independent mutations should have a fitness value that's equal to their individual fitness values multipled, but related mutations will deviate from that; to find those deviations you'd multiply all the fitness values from mutants from a normal library by the fitness of the background knockout and compare that to the fitness values found from the knockout library!	

Setting reads1 / reads2 manually: these are related to the correction factor calculations; it's not recommended that you set them manually. If this number is too low it will cause a mathematical error and Calculate Fitness will not work.

Output: the output is a csv (comma separated values) file containing the fitness values calculated. Each line besides the header will represent the following information for an insertion location: position, strand, count_1, count_2, ratio, mt_freq_t1, mt_freq_t2, pop_freq_t1, pop_freq_t2, gene, D, W, nW

Output2: a txt file containing the percent blanks to be used in the Aggregate tool for normalization

Output3: a wig file that can be used for visualization of the fitness values; each line besides the header will be an insertion location and its (possibly normalized) fitness.

</help>
</tool>