← Back to branch summary

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

« back to all changes in this revision

Viewing changes to doc/tutorials/distance_matrix_comparison.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/tutorials/distance_matrix_comparison.rst
8
8
------------
9
9
This tutorial explains how to use several different distance matrix comparison techniques that are available in `compare_distance_matrices.py <../scripts/compare_distance_matrices.html>`_. All of the currently available comparison techniques are based on the Mantel test, which is a non-parametric statistical method that computes the correlation between two distance matrices. In addition to this statistical method, QIIME also provides the partial Mantel test and Mantel correlogram. Each of these methods will be described in greater detail below.
10
10
 
11
 
One common application of distance matrix comparison techniques is to determine if correlation exists between a community distance matrix (e.g. UniFrac distance matrix) and a second matrix derived from a gradient (e.g. difference in pH, temperature, or geographical location). For example, one might be interested in seeing if communities that are at dissimilar pH levels are more different from one another than communities that are at very similar pH levels. If so, this indicates positive gradient correlation. To create a gradient distance matrix from a continuous category in your mapping file, please refer to the `distance_matrix_from_mapping.py <../scripts/distance_matrix_from_mapping.html>`_ script documentation.
 
11
One common application of distance matrix comparison techniques is to determine if correlation exists between a community distance matrix (e.g. UniFrac distance matrix) and a second matrix derived from an environmental parameter that is numeric/continuous in nature (e.g. difference in pH, temperature, or geographical location). For example, one might be interested in seeing if communities that are at dissimilar pH levels are more different from one another than communities that are at very similar pH levels. If so, this would indicate positive correlation between the two distance matrices. To create a distance matrix from a continuous category in your mapping file (e.g. environmental parameter), please refer to the `distance_matrix_from_mapping.py <../scripts/distance_matrix_from_mapping.html>`_ script documentation.
12
12
 
13
13
Please note that this tutorial does not attempt to cover every possible option that can be used in the distance matrix comparison script. Instead, it attempts to provide useful examples to give you an idea of how to use these statistical methods in your own analysis, as well as customize some of the output to your liking. For a complete listing of the available options, please refer to the `compare_distance_matrices.py <../scripts/compare_distance_matrices.html>`_ script documentation.
14
14
 
28
28
 
29
29
    compare_distance_matrices.py --method=mantel -i unweighted_unifrac_dm.txt,PH_dm.txt -o mantel_out -n 999
30
30
 
31
 
This command will create a new output directory named :file:`mantel_out`, which will contain a single text file called :file:`mantel_results.txt`. Open up :file:`mantel_results.txt` to see the results of the test: 
 
31
This command will create a new output directory named :file:`mantel_out`, which will contain a single text file called :file:`mantel_results.txt`. Open up :file:`mantel_results.txt` to see the results of the test:
32
32
 
33
33
.. note::
34
34
 
58
58
    * unweighted_unifrac_dm.txt PH_dm.txt       77      0.75592 0.001   999     two sided
59
59
    * unweighted_unifrac_dm_shuffled_1.txt      PH_dm.txt       77      0.01960 0.559   999     two sided
60
60
 
61
 
We specified three distance matrices in the previous command. Two of the distance matrices are the same and we added a third distance matrix called :file:`unweighted_unifrac_dm_shuffled.txt`. This distance matrix is the same as the original unweighted UniFrac distance matrix except its sample IDs are shuffled. This distance matrix is included to illustrate a negative control, i.e. one that should `not` be correlated with either of the other two distance matrices. The results file indicates that there isn't significant correlation between the original and shuffled UniFrac distance matrices because the Mantel `r` statistic is close to zero and the p-value is very large (0.659). The middle line in the results file is the same as our previous results (strong significant positive correlation). The last line indicates that the shuffled UniFrac and pH distance matrices are not significantly correlated.
 
61
We specified three distance matrices in the previous command. Two of the distance matrices are the same ones we previously used and we added a third new distance matrix called :file:`unweighted_unifrac_dm_shuffled.txt`. This distance matrix is the same as the original unweighted UniFrac distance matrix except its sample IDs are shuffled. This distance matrix is included to illustrate a negative control, i.e. one that should `not` be correlated with either of the other two distance matrices. The results file indicates that there isn't significant correlation between the original and shuffled UniFrac distance matrices because the Mantel `r` statistic is close to zero and the p-value is very large (0.659). The middle line in the results file is the same as our previous results (strong significant positive correlation). The last line indicates that the shuffled UniFrac and pH distance matrices are not significantly correlated.
62
62
 
63
63
Partial Mantel Test
64
64
-------------------
65
 
The partial Mantel test is used to estimate the correlation between two matrices, A and B, while controlling for the effect of a control matrix C. The partial Mantel test is a first-order correlation analysis that utilizes three distance (dissimilarity) matrices. This test builds on the simple Mantel test by adding a third "control" matrix. The goal is to test the correlation between matrices A and B while controlling the effect of a third matrix C, in order to remove spurious correlations. The first distance matrix is the one that is permuted so that the correlation structure between the first and second distance matrices is kept constant (Oksanen et al., 2011).
 
65
The partial Mantel test is used to estimate the correlation between two matrices, A and B, while controlling for the effect of a control matrix C. The partial Mantel test is a first-order correlation analysis that utilizes three distance (dissimilarity) matrices. This test builds on the simple Mantel test by adding a third "control" matrix. The goal is to test the correlation between matrices A and B while controlling the effect of a third matrix C, in order to remove spurious correlations. The first distance matrix is the one that is permuted so that the correlation structure between the first and second distance matrices is kept constant (Oksanen et al., 2011). A popular use of the partial Mantel test is to compare a community distance matrix with another distance matrix derived from an environmental parameter, using geographic distance as the third "control" distance matrix.
66
66
 
67
67
To illustrate the use of the partial Mantel test, we will determine if there is significant correlation between the unweighted and weighted UniFrac distance matrices, using the pH distance matrix as the control matrix. Run the following command: ::
68
68
 
83
83
 
84
84
Mantel Correlogram
85
85
------------------
86
 
Mantel correlogram is a method that tests whether there is correlation between two distance matrices by examining the correlation between matrices for each distance class. Mantel correlogram performs a Mantel test on each distance class and generates a correlogram with distance classes on the x-axis and their corresponding Mantel test statistic on the y-axis. Thus, Mantel correlogram allows you to see where the correlation exists between the two matrices by providing a higher-resolution view than a traditional Mantel test. For example, you might want to see if there is correlation between a Unifrac distance matrix and a spatial distance matrix. Mantel Correlogram will let you see what the correlation is at different ranges of spatial distances (distance classes).
87
 
 
88
 
The Mantel correlogram method computes a Mantel `r` statistic for each geographic distance class that can be derived from the input. It tests for significance of genetic/community distance versus geographic distance (or some other type of distance). The null hypothesis that is tested is that there is no association of geographic distance to community distance for each distance class.
89
 
 
90
 
Sturge’s rule is used to determine how many distance classes to use based on the number of pairwise comparisons you have. These distance classes can be thought of as bins (as used in histograms). For each distance class, a Mantel test is performed and a Mantel statisic is computed. A corrected p-value (i.e. Bonferroni, FDR, Holm, etc.) is also computed for each test. The results of this method are usually visualized in a correlogram, which is a graph with the geographic distance classes on the x-axis and the Mantel statistics on the y-axis.
91
 
 
92
 
This method is very similar to the Mantel method, so the resulting Mantel statistics can be interpreted in the same way as you would for a traditional Mantel test (i.e. a positive value indicates positive spatial correlation). p-values are obtained in the same way as well (i.e. through permutations).
93
 
 
94
 
To illustrate the use of the Mantel correlogram method, we will determine if there is significant correlation between the unweighted UniFrac distance matrix and the pH distance matrix. Run the following command: ::
 
86
Mantel correlogram tests whether there is correlation between two distance matrices by measuring the correlation between each class of distances. Mantel correlogram performs a Mantel test on each distance class and generates a correlogram with distance classes on the x-axis and their corresponding Mantel test statistic on the y-axis. The shape of the correlogram can then be analyzed to determine the underlying correlative structure that exists between the two input distance matrices. Mantel correlogram is typically used as an auxiliary method to the traditional Mantel test. Thus, the Mantel test is used to check for overall significant correlation between two distance matrices, and Mantel correlogram can then be used to further investigate the underlying structure of the correlative relationship.
 
87
 
 
88
Sturge’s rule is used to determine the number of distance classes based on the number of pairwise comparisons that are possible in the input distance matrices. These distance classes can be thought of as bins (as used in histograms). For each distance class, a Mantel test is performed and a Mantel `r` statisic is computed. A corrected p-value (i.e. Bonferroni, FDR, Holm, etc.) is also computed for each test. The results of this method are usually visualized in a correlogram, which is a graph with the geographic/environmental distance classes on the x-axis and the Mantel statistics on the y-axis.
 
89
 
 
90
As previously stated, the *shape* of the correlogram determines the underlying structure of the correlative relationship. For example, different correlogram shapes indicate whether the correlation exists as a linear gradient, a single bump, multiple bumps, a "nugget" effect, and so on. This tutorial does not attempt to illustrate or explain all possible types of correlograms. We refer the reader to Legendre and Legendre (1998) for an excellent discussion of how to interpret correlograms.
 
91
 
 
92
To illustrate the use of the Mantel correlogram method, we will determine the underlying correlative structure between unweighted UniFrac distance and difference in pH. Since we previously obtained significant results from the traditional Mantel test, it is appropriate to use Mantel correlogram for further investigation. Run the following command: ::
95
93
 
96
94
    compare_distance_matrices.py --method=mantel_corr -i unweighted_unifrac_dm.txt,PH_dm.txt -o mantel_correlogram_out -n 999
97
95
 
129
127
.. image:: ../images/mantel_correlogram.png
130
128
   :align: center
131
129
 
132
 
The correlogram is a visual representation of the results in the output text file. The x-axis is the distance class indices and the y-axis is the Mantel `r` statistic. Points that are filled in (black) are statistically significant at an alpha of 0.05 (this can be changed with the -a option). Points that are not filled in (white) are not statistically significant at the specified alpha level. By examining the correlogram, we see that positive correlation exists at closer distance classes, while the strength of the correlation decreases as the distance classes increase. The default output format for the correlogram plot is PDF, but this can be changed to PNG or SVG using the -g option.
 
130
The correlogram is a visual representation of the results in the output text file that we just examined. The x-axis is the distance class indices and the y-axis is the Mantel `r` statistic. Points that are filled in (black) are statistically significant at an alpha of 0.05 (this can be changed with the -a option). Points that are not filled in (white) are not statistically significant at the specified alpha level. By examining the shape of the correlogram, we see that the underlying correlative structure is a linear gradient. Also note that most of the points in the correlogram are statistically significant. The default output format for the correlogram plot is PDF, but this can be changed to PNG or SVG using the -g option.
133
131
 
134
132
References
135
133
----------
136
 
Pyrosequencing-based assessment of soil pH as a predictor of soil bacterial community structure at the continental scale.  Lauber CL, Hamady M, Knight R, Fierer N.  Appl Environ Microbiol. 2009 Aug;75(15):5111-20.
137
 
 
138
 
Jari Oksanen, F. Guillaume Blanchet, Roeland Kindt, Pierre Legendre, Peter R. Minchin, R. B. O'Hara, Gavin L. Simpson, Peter Solymos, M.  Henry H. Stevens and Helene Wagner (2011). vegan: Community Ecology Package. R package version 2.0-2. http://CRAN.R-project.org/package=vegan
 
134
Lauber, Christian L et al. "Pyrosequencing-based assessment of soil pH as a predictor of soil bacterial community structure at the continental scale." Applied and environmental microbiology 75.15 (2009): 5111-5120.
 
135
 
 
136
Legendre, P., Legendre, L. Numerical Ecology Second English Edition (1998).
 
137
 
 
138
Oksanen, Jari et al. vegan: Community Ecology  Package. R package version 2.0-3  (2012). http://CRAN.R-project.org/package=vegan