Empress

<!--Empress Logo-->

Introduction

Empress is a fast and scalable phylogenetic tree viewer.

Empress helps users explore the hierarchical relationships between features in a dataset. Any type of "feature" can be viewed in this way: historically these features have often represented evolutionary relationships of species in community surveys, but you can view pretty much any type of information with hierarchical organization. For example, we could view trees of amplicon sequence variants (ASVs) or operational taxonomic units (OTUs) generated from 16S rRNA marker gene sequencing data, trees generated from shotgun metagenomics sequencing data, or trees of metabolomics data generated using Qemistree (just to name a few options).

Empress supports categorically new functionality, such as integration and synchronized animations with ordination plots, as well as functionality common to established tree viewers (e.g. metadata coloring, clade collapsing, and barplots).

Screenshot

<div align="center"> <i>"Empire plot" visualizing a phylogenetic tree of amplicon sequence variants (ASVs) in Empress, left, alongside a PCoA biplot in Emperor, right. As one of the ways in which these displays are integrated, selecting a tip in the tree (representing an ASV) enlarges the samples containing this ASV in Emperor -- thereby providing more information than would be available from either display alone.</i> </div>

Installation & Basic Usage

Empress is available as either a standalone program or a QIIME 2 plugin. The standalone version will generate a folder with the HTML/JS/CSS files necessary to view the plot while the QIIME 2 version will generate a .qzv Visualization that can be viewed on https://view.qiime2.org/ or by using qiime tools view.

If you encounter problems while trying to install Empress, please check out the "Installation Troubleshooting" section further on in this document. (And if this information isn't sufficient, please feel free to open an issue in this repository or post a question on the QIIME 2 Forum!)

Standalone Version

Empress is available through PyPI. We recommend installing Empress into an environment (e.g. a conda environment) using a Python version of at least 3.6.

Run the following commands to install Empress:

pip install cython "numpy >= 1.12.0"
pip install empress

Try running the command empress --help to ensure that Empress has been installed properly. If you see details for the different Empress commands then the installation has succeeded and you are ready to start using Empress!

Available commands

Empress provides two commands: empress tree-plot and empress community-plot. Both commands generate an Empress visualization, but community-plot requires you to pass in a feature table and sample metadata while tree-plot only requires a tree file. See this section of the docs for some more details.

Input files

The standalone version of Empress takes the following filetypes as inputs. (Note that for empress tree-plot all of these except for the tree are optional, and for empress community-plot all except for the tree, feature table, and sample metadata are optional.)

| Input | Filetype | | ----- | -------- | | Tree | Newick | | Feature Table | BIOM | | Sample Metadata | TSV | | Feature Metadata | TSV | | PCoA | scikit-bio OrdinationResults |

Example standalone usage

empress tree-plot

# Option 1: Using "long" parameter names
empress tree-plot \
    --tree tree.nwk \
    --feature-metadata feature-metadata.tsv \
    --output-dir tree-viz

# Option 2: Using "short" parameter names
empress tree-plot -t tree.nwk -fm feature-metadata.tsv -o tree-viz

empress community-plot

# Option 1: Using "long" parameter names
empress community-plot \
    --tree tree.nwk \
    --table feature-table.biom \
    --sample-metadata sample-metadata.tsv \
    --feature-metadata feature-metadata.tsv \
    --pcoa ordination.txt \
    --filter-extra-samples \
    --output-dir community-tree-viz

# Option 2: Using "short" parameter names
empress community-plot \
    -t tree.nwk \
    -tbl feature-table.biom \
    -sm sample-metadata.tsv \
    -fm feature-metadata.tsv \
    -p ordination.txt \
    --filter-extra-samples \
    -o community-tree-viz

You can view the details of the command line arguments with empress tree-plot --help and empress community-plot --help. Note that the path provided to -o/--output-dir must not exist, as it will be created by Empress upon successful execution of the command. It is also worth noting that the standalone version of the Empress commands does not support providing multiple sample/feature metadata files. If you have, for example, multiple feature metadata files, you should combine them all into one file that you pass to Empress.

The output will be a directory containing an empress.html file and a support_files directory containing the JS/CSS files required to view the plot in your browser. If you provided a PCoA to the community-plot command there will also be an emperor-resources subdirectory containing the files required to view the Emperor plot alongside the tree. You can view the empress.html file in any modern browser to interact with it the same way you would the QIIME 2 Visualization.

QIIME 2 Version

See the QIIME 2 installation page for instructions on how to install QIIME 2. Once you have QIIME 2 installed, make sure the conda environment is activated by running:

conda activate qiime2-2020.8

You can replace qiime2-2020.8 above with whichever version of QIIME 2 you have currently installed.

Now, run the following command to install Empress using PyPI:

pip install empress

Once you have installed Empress, run the following commands to ensure that Empress was installed correctly. If you see information about Empress' QIIME 2 plugin, the installation was successful!

qiime dev refresh-cache
qiime empress --help

Example QIIME 2 usage

qiime empress tree-plot

qiime empress tree-plot \
    --i-tree tree.qza \
    --m-feature-metadata-file taxonomy.qza \
    --o-visualization tree-viz.qzv

qiime empress community-plot

qiime empress community-plot \
    --i-tree tree.qza \
    --i-feature-table feature-table.qza \
    --m-sample-metadata-file sample-metadata.tsv \
    --m-feature-metadata-file taxonomy.qza \
    --i-pcoa ordination.qza \
    --p-filter-extra-samples \
    --o-visualization community-tree-viz.qzv

Installation Troubleshooting

This is not a comprehensive list of problems that can happen during installation -- it's just the ones we've seen so far. If you run into other problems while installing Empress, please let us know so we can add a solution here!

Troubleshooting for Windows Subsystem for Linux (WSL) users

Problem: Empress' installation process depends on the binutils package already being installed. Although most Unix operating systems come with binutils installed by default, we've noticed that some Linux distributions / setups (including WSL) do not have binutils installed.

• Solution: if, when installing Empress, you encounter long errors that include something like ld: cannot find -lbitarr, try installing binutils (e.g. sudo apt-get install binutils) and then try installing Empress again.

• More information: See this issue.

Troubleshooting for macOS users

Problem: On macOS systems, we've found that not having Xcode installed can cause problems with Empress' installation process.

• Solution: If you are using macOS and you run into an error that includes something like command 'x86_64-apple-darwin13.4.0-clang' failed with exit status 1, try installing Xcode (e.g. through the app store) and then try installing Empress again.

• More information: See this issue.

Tutorial: Using Empress in QIIME 2

In this tutorial, we'll use Empress through QIIME 2 and demonstrate its basic usage with the Moving Pictures tutorial dataset. This dataset contains human microbiome samples from two individuals at four body sites across five timepoints.

First, a note about Empress' commands

Empress currently has two commands available:

$ qiime empress --help
Usage: qiime empress [OPTIONS] COMMAND [ARGS]...

  Description: This QIIME 2 plugin wraps Empress and supp