annotate tools/stats/dna_filtering.xml @ 0:9071e359b9a3

Uploaded

<tool id="dna_filter" name="Filter on ambiguities" version="1.0.0">
  <description>in polymorphism datasets</description>
  <command interpreter="python">
    dna_filtering.py
      --input=$input 
      --output=$out_file1 
      --cond="$cond" 
      --n_handling=$n_handling
      --columns=${input.metadata.columns} 
      --col_types="${input.metadata.column_types}"
  </command>
  <inputs>
    <param format="tabular" name="input" type="data" label="Filter" help="Dataset missing? See TIP below."/>
    <param name="cond" size="40" type="text" value="c4 == 'G'" label="With following condition" help="Double equal signs, ==, must be used as shown above. To filter for an arbitrary string, use the Select tool.">
      <validator type="empty_field" message="Enter a valid filtering condition, see syntax and examples below."/>
    </param>
    <param name="n_handling" type="select" label="What is the meaning of N" help="Everything matches everything, Unknown matches nothing">
      <option value="all">Everything (A, T, C, G)</option>
      <option value="none">Unknown</option>
    </param>
  </inputs>
  <outputs>
    <data format="input" name="out_file1" metadata_source="input"/>
  </outputs>
  <tests>
    <test>
      <param name="input" ftype="tabular" value="dna_filter_in1.tabular" />
      <param name="cond" value="c8=='G'" />
      <param name="n_handling" value="all" />
      <output name="out_file1" ftype="tabular" file="dna_filter_out1.tabular" />
    </test>
    <test>
      <param name="input" value="dna_filter_in1.tabular" />
      <param name="cond" value="(c10 == c11 or c17 == c18) and c6 != 'C' and c23 == 'R'" />
      <param name="n_handling" value="all" />
      <output name="out_file1" file="dna_filter_out2.tabular" />
    </test>
    <test>
      <param name="input" value="dna_filter_in1.tabular" />
      <param name="cond" value="c4=='B' or c9==c10" />
      <param name="n_handling" value="none" />
      <output name="out_file1" file="dna_filter_out3.tabular" />
    </test>
    <test>
      <param name="input" value="dna_filter_in1.tabular" />
      <param name="cond" value="c1!='chr1' and c7!='Y' and c25!='+'" />
      <param name="n_handling" value="none" />
      <output name="out_file1" file="dna_filter_out4.tabular" />
    </test>
  </tests>
  <help>

.. class:: infomark

**TIP:** If your data is not TAB delimited, use *Text Manipulation-&gt;Convert*

.. class:: warningmark

**TIP:** This tool is intended primarily for comparing column values (such as "c5==c12"), although it is also possible to filter on specific values (like "c6!='G'"). Be aware that when searching for specific values, any possible match is considered. So if you search on "c6!='G'", rows will be excluded when c6 is G, K, R, S, B, V, or D (plus N or X if you set that to equal "Everything"), because it is possible those values could indicate G. 

-----

**What it does**

This tool is written for a very specific case related to an analysis of polymorphism data. Suppose you have a table of SNP data that looks like this::

  chromosome start end patient1 parient2 patient3 patient4
  --------------------------------------------------------
  chr1       100   101 A        M        C        R 
  chr1       200   201 T        K        C        C 
  
and your want to select all rows where patient1 has the same base as patient2. Unfortunately you cannot do this with the *Filter and Sort -> Filter* tool because it does not understand DNA ambiguity codes (see below). For example, at position 100 patient1 is the same as patient2 because M is a mix of As and Cs. This tool is designed to make filtering on ambiguities possible.

-----

**Syntax**

The filter tool allows you to restrict the dataset using simple conditional statements:

- Columns are referenced with **c** and a **number**. For example, **c1** refers to the first column of a tab-delimited file (e.g., **c4 == c5**)
- When using 'equal-to' operator **double equal sign '==' must be used** ( e.g., **c1=='chr1'** )
- Non-numerical values must be included in single or double quotes ( e.g., **c6=='C'** )
- Filtering condition can include logical operators, but **make sure operators are all lower case** ( e.g., **(c1!='chrX' and c1!='chrY') or c6=='+'** )

------

**Allowed types of filtering**

The following types of filtering are allowed:

- Testing columns for equality (e.g., c2 == c4 or c2 != c4)
- Testing that a column contains a particular base (e.g., c4 == 'C'). Only bases listed in *DNA Codes* below are allowed.
- Testing that a column represents a plus or a minus strand (e.g., c3 == '+' or c3 != '-')
- Testing that a column is a chromosomes (c1 == 'chrX') or a scaffold (c1 == 'scaffold87976')

All other types of filtering should be done with *Filter and Sort -> Filter* tool.

-----

**DNA Codes**

The following are the DNA codes used for filtering::

  Code   Meaning
  ----   --------------------------
   A     A
   T     T
   U     T
   G     G
   C     C
   K     G or T
   M     A or C
   R     A or G
   Y     C or T
   S     C or G
   W     A or T
   B     C, G or T
   V     A, C or G
   H     A, C or T
   D     A, G or T
   X     A, C, G or T
   N     A, C, G or T
   .     not (A, C, G or T)
   -     gap of indeterminate length

-----

**Example**

- **c8=='A'** selects lines in which the eighth column is A, M, R, W, V, H, or D, or N or X if appropriate
- **c12==c15** selects lines where the value in the twelfth column could be the same as the fifteenth and the fifteenth column could be the same as the twelfth column (based on appropriate codes)
- **c9!=c19** selects lines where column nine could not be the same as column nineteen or column nineteen could not be the same as column nine (using appropriate codes)
- **c4 == 'A' and c4 == c5** selects lines where column 4 and 5 are both A, M, R, W, V, H, D or N, or X if appropriate

</help>
</tool>