Package: qurro
Qurro: Quantitative Rank/Ratio Observations(Pronounced "churro.")What does this tool do?Lots of tools for analyzing " 'omic" datasets can producefeature rankings. These rankings can be used as a guide to look at thelog-ratiosof certain features in a dataset. Qurro is a tool for visualizing and exploring both of these types of data.What are feature rankings?The term "feature rankings" includesdifferentials, which we define as the estimated log-fold changes for features' abundances across different sample types. You can get this sort of output from lots of "differential abundance" tools, including but definitely not limited toALDEx2,Songbird,Corncob,DESeq2,edgeR, etc.The term "feature rankings" also includesfeature loadingsin abiplot(seeAitchison and Greenacre 2002); you can get biplots from runningDEICODE,
which is a tool that works well with microbiome datasets, or from a variety of other methods.Differentials and feature loadings alike can be interpreted as rankings -- you
can sort them numerically to "rank" features based on their association with
some sort of variation in your dataset.What can we do with feature rankings?A common use of these rankings is examining thelog-ratiosof
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
details as to why this approach is useful, check outthis open access paper.How does this tool help?Qurro is an interactive web application for visualizing feature rankings
and log-ratios.It does this
using a two-plot interface: on the left side of the screen, a "rank plot" shows
how features are ranked for a selected ranking, and on the right side 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).A paper describing Qurro is now available at NAR Genomics and Bioinformaticshere.How do I use this tool?Qurro can be used standalone (as a Python 3 script that generates a
folder containing a HTML/JS/CSS visualization) or as aQIIME 2plugin (that generates a QZV file that can be
visualized atview.qiime2.orgor by usingqiime tools view).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 toopen an issuein this repository!DemosSee theQurro websitefor a list of
interactive demos using real datasets.Screenshot: Visualizing KEGG orthologs in metagenomic data from the Red SeaThis visualization (which uses data fromthis study, with
differentials generated bySongbird)
can be viewed onlinehere.Installation and UsageYou can install Qurro usingpiporconda.System requirementsIf you're using Qurro within QIIME 2,you will need a QIIME 2 version of at
least 2020.11.If you're using Qurro outside of QIIME 2,you will need a Python version of
at least 3.6 and less than 3.10.In either case, Qurro should work with most modern web browsers; Firefox or Chrome are
recommended.Installing withpippipinstallcython"numpy >= 1.12.0"pipinstallqurroInstalling withcondacondainstall-cconda-forgequrroTemporary CaveatCertain 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.:])[(\|'or"NothingThis is due to some downstream issues with handling these sorts of characters
in field names. Seethis issuefor context.TutorialsIn-depth tutorialsThese tutorials are all good places to start, depending on what sort of data and
feature rankings you have.Color Composition tutorialData Summary:Color composition data from abstract paintingsFeature rankings: Feature loadings in an arbitrary compositional biplotQurro used through QIIME 2 or standalone?: Standalone"Moving Pictures" tutorialData Summary:Microbiome 16S rRNA marker gene sequencing data from four types of body site samplesFeature rankings: Feature loadings in aDEICODEbiplotQurro used through QIIME 2 or standalone?: QIIME 2Transcriptomics tutorialData Summary:Gene expression ("RNA-Seq") data from TCGA tumor and "solid tissue normal" samplesFeature rankings:ALDEx2differentialsQurro used through QIIME 2 or standalone?: StandaloneSelection tutorialThere are a lot of different ways to select features in Qurro, and the
interface can be difficult to get used to. This document describes all of these
methods, and provides some examples of where they could be useful in practice.Selection tutorialBasic command-line tutorialsThese tutorials show examples of using Qurro in identical ways both inside and
outside of QIIME 2.Sleep Apnea tutorialFeature rankings: feature loadings in aDEICODEbiplotRed Sea tutorialFeature rankings:SongbirddifferentialsQarcoalQarcoal(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.
Please seeqarcoal_example.ipynbfor a demonstration of using Qarcoal.PosterWe presentedthis posteron Qurro at the2019 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!AcknowledgementsDependenciesCode files for the following projects are distributed withinqurro/support_files/vendor/.
See thequrro/dependency_licenses/directory for copies of these software projects'
licenses (each of which includes a respective copyright notice).VegaVega-LiteVega-EmbedjQueryDataTablesRequireJSBootstrapBootstrap IconsWe make use of the "Question fill" icon's SVG, as well as some example code
for embedding this or other icons in CSS.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).Altairbiom-formatclickNumPypandasscikit-bioTesting DependenciesFor python testing/style checking, Qurro usespytest,pytest-cov,flake8, andblack. You'll also need to have QIIME 2
installed to run most of the python tests (note that, due to click vs. black
vs. QIIME 2 dependency issues, you should use a QIIME 2 environment of at least
2022.8; seeCONTRIBUTING.mdfor details).For JavaScript testing/style checking, Qurro usesMocha,Chai,mocha-headless-chrome,nyc,jshint,
andprettier.Qurro also usesTravis-CIandCodecov.The Jupyter notebooks in Qurro'sexample_notebooks/folder are automatically
rerun usingnbconvert,
also.Data SourcesThe test data located inqurro/tests/input/mackerel/were exported from
QIIME 2 artifacts inthis repository. These data are from Minich et al. 2020 [1].The test data located inqurro/tests/input/byrd/are fromthis repository.
These data, in turn, originate from Byrd et al.'s 2017 study on atopic
dermatitis [2].The test data located inqurro/tests/input/sleep_apnea/(and inexample_notebooks/DEICODE_sleep_apnea/input/)
are fromthis Qiita study,
which is associated with Tripathi et al.'s 2018 study on sleep apnea [4].The test data located inqurro/tests/input/moving_pictures/(and inexample_notebooks/moving_pictures/data/)
are fromthe QIIME 2 moving pictures tutorial.
Theordinationfiles in these folders were computed based on theDEICODE moving pictures tutorial.
These data (sans the DEICODE ordination) are associated with Caporaso et al. 2011 [5].Lastly, the data located inqurro/tests/input/red_sea(and inexample_notebooks/songbird_red_sea/input/, and shown in the
screenshot above) were taken from Songbird's GitHub repository in itsdata/redsea/folder, and are associated with Thompson et al. 2017 [3].LogoQurro's logo was created using theLalezarfont.
Also, shout out tothis gistfor showing how to center images in GitHub markdown files (which is more of a hassle than it sounds).Special ThanksThe design of Qurro was strongly inspired byEMPerorandq2-emperor, along withDEICODE. 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 :)Citing QurroIf you use Qurro in your research, please cite it!
The preferred citation for Qurro isthis manuscript at NAR Genomics and
Bioinformatics.
Here's the BibTeX:@article {fedarko2020,
    author = {Fedarko, Marcus W and Martino, Cameron and Morton, James T and González, Antonio and Rahman, Gibraan and Marotz, Clarisse A and Minich, Jeremiah J and Allen, Eric E and Knight, Rob},
    title = "{Visualizing ’omic feature rankings and log-ratios using Qurro}",
    journal = {NAR Genomics and Bioinformatics},
    volume = {2},
    number = {2},
    year = {2020},
    month = {04},
    issn = {2631-9268},
    doi = {10.1093/nargab/lqaa023},
    url = {https://doi.org/10.1093/nargab/lqaa023},
    note = {lqaa023},
    eprint = {https://academic.oup.com/nargab/article-pdf/2/2/lqaa023/33137933/lqaa023.pdf},
}References[1] Minich, J. J., Petrus, S., Michael, J. D., Michael, T. P., Knight, R., &
Allen, E. E. (2020). Temporal, environmental, and biological drivers of the
mucosal microbiome in a wild marine fish, Scomber japonicus.mSphere, 5(3),
e00401-20.Link.[2] 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.[3] 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.[4] 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.[5] 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.LicenseThis tool is licensed under theBSD 3-clause license.
Our particular version of the license is based onscikit-bio'slicense.