← Back to branch summary

~ubuntu-branches/ubuntu/trusty/qiime/trusty

« back to all changes in this revision

Viewing changes to doc/scripts/detrend.rst

  • Committer: Package Import Robot
  • Author(s): Andreas Tille
  • Date: 2013-06-17 18:28:26 UTC
  • mfrom: (9.1.2 sid)
  • Revision ID: package-import@ubuntu.com-20130617182826-376az5ad080a0sfe
Tags: 1.7.0+dfsg-1
Upload preparations done for BioLinux to Debian

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/scripts/detrend.rst
 
1
.. _detrend:
 
2
 
 
3
.. index:: detrend.py
 
4
 
 
5
*detrend.py* -- Detrend Principal Coordinates
 
6
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
7
 
 
8
**Description:**
 
9
 
 
10
Ordination plots (e.g. principal coordinates analysis) of samples that lay along a naturally occurring gradient (e.g. depth, time, pH) often exhibit a curved shape known as the "arch" or "horseshoe" effect. This can cause samples near the endpoints of the gradient to appear closer to one another than would be expected. This script will attempt to remove any (compounded) quadratic curvature in a set of 2D coordinates. If requested, it will also report an evaluation of the association of the transformed coordinates with a known gradient.
 
11
 
 
12
 
 
13
**Usage:** :file:`detrend.py [options]`
 
14
 
 
15
**Input Arguments:**
 
16
 
 
17
.. note::
 
18
 
 
19
        
 
20
        **[REQUIRED]**
 
21
                
 
22
        -i, `-`-input_fp
 
23
                Path to read PCoA/PCA/ordination table
 
24
        
 
25
        **[OPTIONAL]**
 
26
                
 
27
        -o, `-`-output_dir
 
28
                Path to output directory [default: .]
 
29
        -m, `-`-map_fp
 
30
                Path to metadata file [default: None]
 
31
        -c, `-`-gradient_variable
 
32
                Column header for gradient variable in metadata table [default: None]
 
33
        -r, `-`-suppress_prerotate
 
34
                Suppress pre-rotation of the coordinates for optimal detrending; not pre-rotating assumes that the curvature is symmetrical across the vertical axis [default: False]
 
35
 
 
36
 
 
37
**Output:**
 
38
 
 
39
Output is detrended PCoA matrices.
 
40
 
 
41
 
 
42
**Examples:**
 
43
 
 
44
The simplest usage takes as input only a table of principal coordinates:
 
45
 
 
46
::
 
47
 
 
48
        detrend.py -i $PWD/pcoa.txt -o detrending
 
49
 
 
50
One may also include a metadata file with a known real-valued gradient as one of the columns. In this case, the output folder will include a text file providing a summary of how well the analysis fit with the hypothesis that the primary variation is due to the gradient (in this case, "DEPTH"):
 
51
 
 
52
::
 
53
 
 
54
        detrend.py -i $PWD/pcoa.txt -m map.txt -c DEPTH -o detrending
 
55
 
 
56
Note that if you provide a real-valued known gradient the script will prerotate the first two axes of the PCoA coords in order to achieve optimal alignment with that gradient. This can be disabled with "-r":
 
57
 
 
58
::
 
59
 
 
60
        detrend.py -i $PWD/pcoa.txt -m map.txt -c DEPTH -o detrending -r
 
61
 
 
62