Visualizes differentially ranked features and log-ratios of their sample abundances
Qurro: Quantitative Rank/Ratio Observations
What does this tool do?
(mostly taken from our paper abstract/intro.)
Lots of tools for analyzing " 'omic" datasets can produce feature rankings. Regardless of if they're differentials (corresponding to the log-fold change in relative abundance re: a covariate) produced by a tool like Songbird, ALDEx2, etc., or the feature loadings in a (compositional) biplot produced by a tool like DEICODE, either of these input types can be sorted numerically to "rank" features based on their association with some sort of variation in your dataset.
A common use of these rankings is examining the log-ratios of particularly high- or low-ranked features across the samples in your dataset, and seeing how these log-ratios relate to your sample metadata (e.g. "does this log-ratio differ between 'healthy' and 'sick' samples?"). For more details (why rankings, why log-ratios, ...), check out this open access paper.
Qurro is an interactive web application for visualizing feature rankings and log-ratios. It does this using a two-plot interface: on the left of the screen, a "rank plot" shows how features are ranked for a selected ranking, and on the right of the screen a "sample plot" shows the log-ratios of selected features' abundances within samples. There are a variety of controls available for selecting features for a log-ratio, and changing the selected log-ratio updates both the rank plot (highlighting selected features) and the sample plot (changing the y-axis value of each sample to match the selected log-ratio).
How do I use it?
Qurro can be used standalone (as a Python 3 script that generates a
folder containing a HTML/JS/CSS visualization) or as a
QIIME 2 plugin (that generates a QZV file that can be
visualized at view.qiime2.org or by using
qiime tools view). Starting with Qurro v0.3.0, Qurro requires a QIIME 2
version of at least 2019.7.
Qurro should work with most modern web browsers. Firefox or Chrome are recommended.
Qurro is still being developed, so backwards-incompatible changes might occur. If you have any bug reports, feature requests, questions, or if you just want to yell at me, then feel free to open an issue in this repository!
See the Qurro website for a list of interactive demos using real datasets.
Screenshot: Visualizing KEGG orthologs in metagenomic data from the Red Sea
Installation and Usage
You can install Qurro using pip:
pip install numpy pip install qurro
A python version of at least 3.5 is required to use Qurro.
Certain characters in column names in the sample metadata, feature metadata (if passed), and feature differentials (if passed) will be replaced with similar characters or just removed entirely:
|Old Character(s)||New Character|
This is due to some downstream issues with handling these sorts of characters in field names. See this issue for context.
"Moving Pictures" Tutorial
In the style of the QIIME 2 and DEICODE moving pictures tutorials, there is a draft moving pictures tutorial (showing how to use Qurro within QIIME 2, and how to interact with the generated Qurro visualization) available here. This tutorial is still a work in progress, so feel free to contact us if you have any outstanding questions (or any suggestions for improving this tutorial).
Running Qurro from the command line
Examples of using Qurro (both inside and outside of QIIME 2) are available in Qurro's example Jupyter notebooks, which are located here:
deicode_example.ipynbdemonstrates using DEICODE and then using Qurro to visualize DEICODE's output.
songbird_example.ipynbdemonstrates using Songbird and then using Qurro to visualize Songbird's output.
Qarcoal (pronounced "charcoal") is a new part of Qurro that lets you compute log-ratios based on taxonomic searching directly from the command-line. This can be useful for a variety of reasons.
Currently, Qarcoal is only available through Qurro's QIIME 2 plugin interface.
for a demonstration of using Qarcoal.
We presented this poster on Qurro at the 2019 CRISP Annual Review. The data shown here is already slightly outdated compared to the actual Qurro paper (e.g. the differentials are slightly different), but feel free to check out the poster anyway!
A manuscript describing Qurro is in preparation. In the meantime, you can cite the DOI of Qurro's source code (provided by Zenodo). See this link for citation instructions.
Code files for the following projects are distributed within
qurro/dependency_licenses/ directory for copies of these software projects'
licenses (each of which includes a respective copyright notice).
- Popper.js (included within the Bootstrap JS "bundle" file)
The following software projects are required for Qurro's python code to function, although they are not distributed with Qurro (and are instead installed alongside Qurro).
For python testing/style checking, Qurro uses
black. You'll also need to have QIIME 2
installed to run most of the python tests (your QIIME 2 version should be at
least 2019.7, due to the
FeatureData[Differential] type being merged into
q2-types starting with this release).
The Jupyter notebooks in Qurro's
example_notebooks/ folder are automatically
rerun using nbconvert,
The test data located in
qurro/tests/input/mackerel/ were exported from
QIIME 2 artifacts in this repository. These data are from Minich et al. 2019 .
The test data located in
qurro/tests/input/byrd/ are from
These data, in turn, originate from Byrd et al.'s 2017 study on atopic
The test data located in
are from this Qiita study,
which is associated with Tripathi et al.'s 2018 study on sleep apnea .
The test data located in
are from the QIIME 2 moving pictures tutorial.
ordination.qza file in this folder was computed based on the
DEICODE moving pictures tutorial.
These data (sans the DEICODE ordination) are associated with Caporaso et al. 2011 .
Lastly, the data located in
example_notebooks/songbird_red_sea/input/, and shown in the
screenshot above) were taken from Songbird's GitHub repository in its
folder, and are associated with Thompson et al. 2017 .
The design of Qurro was strongly inspired by EMPeror and q2-emperor, along with DEICODE. A big shoutout to Yoshiki Vázquez-Baeza for his help in planning this project, as well as to Cameron Martino for a ton of work on getting the code in a distributable state (and making it work with QIIME 2). Thanks also to Jamie Morton, who wrote the original code for producing rank and sample plots from which this is derived.
And thanks to a bunch of the Knight Lab for helping name the tool :)
 Minich, J. J., Petrus, S., Michael, J. D., Michael, T. P., Knight, R., & Allen, E. E. (2019). Temporal, environmental, and biological drivers of the mucosal microbiome in a wild marine fish, Scomber japonicus. bioRxiv, page 721555. Link.
 Byrd, A. L., Deming, C., Cassidy, S. K., Harrison, O. J., Ng, W. I., Conlan, S., ... & NISC Comparative Sequencing Program. (2017). Staphylococcus aureus and Staphylococcus epidermidis strain diversity underlying pediatric atopic dermatitis. Science translational medicine, 9(397), eaal4651. Link.
 Thompson, L. R., Williams, G. J., Haroon, M. F., Shibl, A., Larsen, P., Shorenstein, J., ... & Stingl, U. (2017). Metagenomic covariation along densely sampled environmental gradients in the Red Sea. The ISME journal, 11(1), 138. Link.
 Tripathi, A., Melnik, A. V., Xue, J., Poulsen, O., Meehan, M. J., Humphrey, G., ... & Haddad, G. (2018). Intermittent hypoxia and hypercapnia, a hallmark of obstructive sleep apnea, alters the gut microbiome and metabolome. mSystems, 3(3), e00020-18. Link.
 Caporaso, J. G., Lauber, C. L., Costello, E. K., Berg-Lyons, D., Gonzalez, A., Stombaugh, J., ... & Gordon, J. I. (2011). Moving pictures of the human microbiome. Genome biology, 12(5), R50. Link.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size qurro-0.5.0-py3-none-any.whl (473.0 kB)||File type Wheel||Python version py3||Upload date||Hashes View hashes|
|Filename, size qurro-0.5.0.tar.gz (451.5 kB)||File type Source||Python version None||Upload date||Hashes View hashes|