# Robust Aitchison PCA Beta Diversity with DEICODE
**URL:** https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333
**Category:** Tutorials
**Created:** [February 12, 2019, 4:15pm UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333 "2019-02-12T16:15:44Z")
**Posts on this page:** 15
**Page:** 1
### Author:  [@cmartino](https://forum.qiime2.org/u/cmartino)
#### Post date: [February 12, 2019, 4:15pm UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/1 "2019-02-12T16:15:44Z")
# DEICODE
(pronounced like decode /de.ko.de/)
[Documentation available in the pugin library.](https://library.qiime2.org/plugins/deicode/19/)
DEICODE is a form of [Aitchison Distance](https://en.wikipedia.org/wiki/Aitchison_geometry) that is robust to high levels of sparsity. DEICODE utilizes a natural solution to the zero problem formulated in recommendation systems called [matrix completion](https://arxiv.org/pdf/0906.2027.pdf). A simple way to interpret the method is, as a robust compositional [PCA (via SVD)](https://en.wikipedia.org/wiki/Principal_component_analysis) where zero values do not influence the resulting ordination. One of the benefits of using DEICODE is the ability to reveal salient inter-community niche feature importance in compositional biplots. These biplot can be easily visualized in the existing QIIME architecture through [Emperor](https://docs.qiime2.org/2018.11/plugins/available/emperor/).
# Installation within a QIIME Environment
If you have not already done so, activate your QIIME environment.
```auto
source activate qiime2-20xx.x
```
DEICODE is available for installation through pip _or_ conda:
```auto
pip install deicode
```
**Note** : the conda install is only supported for Qiime\>=2019.1
```auto
conda install -c conda-forge deicode
```
# Tutorial
**Note** : This guide assumes you have installed QIIME using one of the procedures in the [install documents](https://docs.qiime2.org/2019.1/install/) and have installed [DEICODE](https://library.qiime2.org/plugins/q2-deicode).
## Introduction
In this tutorial you will learn how to interpret and perform Robust Aitchison PCA through QIIME. The focus of this tutorial is compositional beta diversity. There are many beta diversity metrics that have been proposed, all with varying benefits on varying data structures. However, presence/absence metric often prove to give better results than those that rely on abundances (i.e. unweighted vs. weighted UniFrac). One component of this phenomenon is that the interpretation of relative abundances can provide spurious results (see [the differential abundance analysis introduction](https://docs.qiime2.org/2019.1/tutorials/gneiss/)). One solution to this problem is to use a compositional distance metric such as [Aitchison distance](https://en.wikipedia.org/wiki/Aitchison_geometry).
As a toy example let’s build three taxa. These three taxa represent common distributions we see in microbiome datasets. Where the first taxon is increasing exponentially across samples, this is a trend that we would be interested in. However, taxon 2 and 3 have much higher counts and taxon 3 is randomly fluctuating across samples.
In our distances below we have Euclidean, Bray-Curtis, Jaccard, and Aitchison distances (from left to right). We can see that the abundance based metrics Euclidean and Bray-Curtis are heavily influenced by the abundance of taxon 3 and seem to randomly fluctuate. In the presence/absence metric, Jaccard, we see that the distance saturates to one very quickly. However, in the Aitchison distance we see a linear curve representing taxon 1. The reason the distance is linear is because Aitchison distance relies on log transforms (the log of the exponential trend of taxon 1 is linear).
From this toy example, it is clear that Aitchison distance better accounts for the proportions. However, we made the unrealistic assumption in our toy example that there were no zero counts. In real microbiome datasets there are a large number of zeros (i.e. sparsity). Sparsity complicates log ratio transformations because the log-ratio of zero is undefined. To solve this, pseudo counts are often used but that can often skew results (see [Naught all zeros in sequence count data are the same](https://www.biorxiv.org/content/10.1101/477794v1)).
Robust Aitchison PCA solves this problem in two steps:
**1.** Compostional preprocessing using the centered log ratio transform on only the non-zero values of the data (no pseudo count)
**2.** Dimensionality reduction through Robust PCA on only the non-zero values of the data ( [matrix completion](https://arxiv.org/pdf/0906.2027.pdf)).
To demonstrate this in action we will run an example dataset below, where the output can be viewed as a compositional biplot through Emperor.
## Example
In this example we will use Robust Aitchison PCA via DEICODE on the “Moving Pictures” tutorial, if you have not yet completed the tutorial it can be found [here](https://docs.qiime2.org/2019.1/tutorials/moving-pictures/). The dataset consists of human microbiome samples from two individuals at four body sites at five timepoints, the first of which immediately followed antibiotic usage ([Caporaso et al. 2011](https://www.ncbi.nlm.nih.gov/pubmed/21624126)). If you have completed this tutorial run the following command and skip the download section.
```shell
cd qiime2-moving-pictures-tutorial
```
If you have skipped the tutorial but would like to get started quickly, the data files needed for the DEICODE tutorial must be downloaded below.
```shell
mkdir qiime2-moving-pictures-tutorial
cd qiime2-moving-pictures-tutorial
```
##### Table [view](https://view.qiime2.org/?src=https%3A%2F%2Fdocs.qiime2.org%2F2019.1%2Fdata%2Ftutorials%2Fmoving-pictures%2Ftable.qza) | [download](https://docs.qiime2.org/2019.1/data/tutorials/moving-pictures/table.qza)
**save as:** table.qza
##### Sample Metadata [download](https://data.qiime2.org/2019.1/tutorials/moving-pictures/sample_metadata.tsv)
**save as:** sample-metadata.tsv
##### Feature Metadata [view](https://view.qiime2.org/?src=https%3A%2F%2Fdocs.qiime2.org%2F2019.1%2Fdata%2Ftutorials%2Fmoving-pictures%2Ftaxonomy.qza) | [download](https://docs.qiime2.org/2019.1/data/tutorials/moving-pictures/taxonomy.qza)
**save as:** taxonomy.qza
Using table.qza, of the type raw count table (FeatureTable[Frequency]), we will generate our beta diversity ordination file. There are a few parameters to DEICODE that we may want to consider. The first is filtering cutoffs, these are p-min-feature-count and p-min-sample-count. Both of these parameters accept integer values and remove feature or samples, respectively, with sums below this cutoff. The feature cut-off is useful in the case that features with very low total counts among all samples represent contamination or chimeric sequences. The sample cut off is useful for the case that some sample received very few reads relative to other samples.
**Note:** it is _not_ recommended to bin your features by taxonomic assignment (i.e. by genus level).
**Note:** it is _not_ recommended to rarefy your data before using DEICODE.
The other two parameters are --p-rank and --p-iterations. These parameters should rarely have to change from the default. However, the minimum value of --p-rank can be 1 and the maximum recommended value is 10. Similarly, the minimum value of --p-iterations is 1 and is recommended to be below 500.
Now that we understand the acceptable parameters, we are ready to run DEICODE.
```shell
qiime dev refresh-cache
```
```bash
qiime deicode rpca \
--i-table table.qza \
--p-min-feature-count 10 \
--p-min-sample-count 500 \
--o-biplot ordination.qza \
--o-distance-matrix distance.qza
```
**Output:**
- ordination.qza [download](https://github.com/biocore/DEICODE/raw/master/ipynb/tutorials/qiime2-moving-pictures-tutorial/ordination.qza)
- distance.qza [download](https://github.com/biocore/DEICODE/raw/master/ipynb/tutorials/qiime2-moving-pictures-tutorial/distance.qza)
Now that we have our ordination file, with type (PCoAResults % Properties(['biplot'])), we are ready to visualize the results. This can be done using the [Emperor](https://docs.qiime2.org/2019.1/plugins/available/emperor/) biplot functionality. In this case we will include metadata for our features (optional) and our samples (required).
```bash
qiime emperor biplot \
--i-biplot ordination.qza \
--m-sample-metadata-file sample-metadata.tsv \
--m-feature-metadata-file taxonomy.qza \
--o-visualization biplot.qzv \
--p-number-of-features 8
```
**Output:**
- biplot.qzv [download](https://github.com/biocore/DEICODE/raw/master/ipynb/tutorials/qiime2-moving-pictures-tutorial/biplot.qzv)
Biplots are exploratory visualization tools that allow us to represent the features (i.e. taxonomy or OTUs) that strongly influence the principal component axis as arrows. The interpretation of the compositional biplot differs slightly from classical biplot interpretation (we can view the qzv file at [view.qiime2](https://view.qiime2.org). The important features with regard to sample clusters are not a single arrow but by the log ratio between features represented by arrows pointing in different directions. A visualization tool for these log ratios is coming soon to QIIME.
From this visualization we noticed that BodySite seems to explain the clusters well. We can run [PERMANOVA](https://docs.qiime2.org/2019.1/plugins/available/diversity/beta-group-significance/) on the distances to get a statistical significance for this.
```bash
qiime diversity beta-group-significance \
--i-distance-matrix distance.qza \
--m-metadata-file sample-metadata.tsv \
--m-metadata-column BodySite \
--p-method permanova \
--o-visualization BodySite_significance.qzv
```
**Output:**
- BodySite\_significance.qzv [download](https://github.com/biocore/DEICODE/raw/master/ipynb/tutorials/qiime2-moving-pictures-tutorial/BodySite_significance.qzv)
Indeed we can now see that the clusters we saw in the biplot were significant by viewing the BodySite\_significance.qzv at [view.qiime2](https://view.qiime2.org).
## Citation
C. Martino et al., A Novel Sparse Compositional Technique Reveals Microbial Perturbations. mSystems. 4 (2019), doi:10.1128/mSystems.00016-19.
## Other Resources
[Documentation on GitHub](https://github.com/biocore/DEICODE)
The code for OptSpace was translated to python from a [MATLAB package](http://swoh.web.engr.illinois.edu/software/optspace/code.html) maintained by Sewoong Oh (UIUC).
---
### Author:  [@Nicholas\_Bokulich](https://forum.qiime2.org/u/Nicholas_Bokulich)
#### Post date: [February 14, 2019, 1:46pm UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/2 "2019-02-14T13:46:08Z")
3 off-topic replies have been split into a new topic: [How to make pcoa biplot in R using q2-deicode ordination](https://forum.qiime2.org/t/how-to-make-pcoa-biplot-in-r-using-q2-deicode-ordination/8377)
Please keep replies on-topic in the future.
---
### Author:  [@Nicholas\_Bokulich](https://forum.qiime2.org/u/Nicholas_Bokulich)
#### Post date: [March 8, 2019, 8:01pm UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/3 "2019-03-08T20:01:02Z")
An off-topic reply has been split into a new topic: [Deicode installation error](https://forum.qiime2.org/t/deicode-installation-error/8702)
Please keep replies on-topic in the future.
---
### Author:  [@thermokarst](https://forum.qiime2.org/u/thermokarst)
#### Post date: [March 16, 2019, 8:34pm UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/4 "2019-03-16T20:34:23Z")
An off-topic reply has been split into a new topic: [Help understanding DEICODE](https://forum.qiime2.org/t/help-understanding-deicode/8803)
Please keep replies on-topic in the future.
---
### Author:  [@cxf514](https://forum.qiime2.org/u/cxf514)
#### Post date: [October 3, 2019, 3:29pm UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/5 "2019-10-03T15:29:17Z")
thanks for the development of DEICODE, it is really powerful.
l would like to know when the visualization tool you said comes.
---
### Author:  [@yanxianl](https://forum.qiime2.org/u/yanxianl)
#### Post date: [October 3, 2019, 6:48pm UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/6 "2019-10-03T18:48:35Z")
It's already available in the QIIME2 library. Check it out [here](https://library.qiime2.org/plugins/qurro/22/).
---
### Author:  [@fedarko](https://forum.qiime2.org/u/fedarko)
#### Post date: [October 4, 2019, 2:07am UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/7 "2019-10-04T02:07:25Z")
Hi @cxf514! As @yanxianl mentioned, the visualization tool mentioned here ([Qurro](https://github.com/biocore/qurro)) is already available for QIIME 2.
We're still working on improving Qurro's documentation and functionality (...and making a QIIME 2 forum post about it), but feel free to try it out alongside your DEICODE results! Feel free to make a new post on the forum if you have any questions about the tool 🙂
---
### Author:  [@cxf514](https://forum.qiime2.org/u/cxf514)
#### Post date: [October 4, 2019, 2:32am UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/8 "2019-10-04T02:32:20Z")
you are a hero(^0^)/
---
### Author:  [@fedarko](https://forum.qiime2.org/u/fedarko)
#### Post date: [May 11, 2020, 6:24pm UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/9 "2020-05-11T18:24:12Z")
3 posts were split to a new topic: [Questions about interpreting DEICODE and Qurro output](https://forum.qiime2.org/t/questions-about-interpreting-deicode-and-qurro-output/14888)
---
### Author:  [@thermokarst](https://forum.qiime2.org/u/thermokarst)
#### Post date: [July 27, 2021, 11:09pm UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/10 "2021-07-27T23:09:53Z")
An off-topic reply has been split into a new topic: [DEICODE: can I use sample metadata for the arrows to indicate what is driving the dissimilarity](https://forum.qiime2.org/t/deicode-can-i-use-sample-metadata-for-the-arrows-to-indicate-what-is-driving-the-dissimilarity/20313)
Please keep replies on-topic in the future.
---
### Author:  [@Nicholas\_Bokulich](https://forum.qiime2.org/u/Nicholas_Bokulich)
#### Post date: [August 12, 2022, 7:13pm UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/11 "2022-08-12T19:13:51Z")
An off-topic reply has been split into a new topic: [feature request: could DEICODE accept a non-biom table?](https://forum.qiime2.org/t/feature-request-could-deicode-accept-a-non-biom-table/23886)
Please keep replies on-topic in the future.
---
### Author:  [@kam](https://forum.qiime2.org/u/kam)
#### Post date: [October 22, 2022, 10:00am UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/12 "2022-10-22T10:00:01Z")
Thanks for this great tool!
@cmartino you have wrote in the publication: "This method could possibly be adapted to or combined with other omics paradigms (e.g., metabolomics, metatranscriptomics, and metagenomics)".
Did you mean that robust compositional PCA is appropriate to use with other omics data (e.g. gene count, etc.)? Have you checked this method in comparison to other distances methods in other contexts then taxa abundance?
---
### Author:  [@cmartino](https://forum.qiime2.org/u/cmartino)
#### Post date: [October 27, 2022, 8:43pm UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/13 "2022-10-27T20:43:47Z")
Hi @kam,
We don't have any formal benchmarks currently published outside of taxonomic profiles obtained from amplicon or shotgun data. However, many (including myself) have used it with success on gene profiles and even metabolomics/proteomics data.
---
### Author:  [@kam](https://forum.qiime2.org/u/kam)
#### Post date: [January 11, 2023, 3:21pm UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/15 "2023-01-11T15:21:28Z")
Once again thanks for this extremely nice plugin, would like to have another question:
The distance matrix created gives values of more than 1, e.g 3,4.. How can I interpert it? given that in most beta diversity metrics the value is between 0 and 1.
---
### Author:  [@cmartino](https://forum.qiime2.org/u/cmartino)
#### Post date: [January 11, 2023, 3:44pm UTC](https://forum.qiime2.org/t/robust-aitchison-pca-beta-diversity-with-deicode/8333/16 "2023-01-11T15:44:46Z")
Thanks for using the tool. 🙂 Not all distances are bounded between 0 and 1, RPCA outputs an Aitchison distance (Euclidean distance on centered log-ratio transformed data). You can proceed how you normally would (e.g. PERMANOVA, between/within distance plots). You can read [here](https://link.springer.com/article/10.1023/A:1007529726302) and [here](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6755255/) for more about Aitchison distances.