{"id":20934621,"url":"https://github.com/biocore/qurro","last_synced_at":"2025-07-18T05:35:23.938Z","repository":{"id":43043325,"uuid":"158270494","full_name":"biocore/qurro","owner":"biocore","description":"Visualize differentially ranked features (taxa, metabolites, ...) and their log-ratios across samples","archived":false,"fork":false,"pushed_at":"2025-03-13T21:15:06.000Z","size":84663,"stargazers_count":33,"open_issues_count":124,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-02T05:08:04.748Z","etag":null,"topics":["bioinformatics","microbiome","qiime","visualization"],"latest_commit_sha":null,"homepage":"https://biocore.github.io/qurro","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/biocore.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-19T18:14:53.000Z","updated_at":"2025-03-13T21:15:10.000Z","dependencies_parsed_at":"2022-09-13T16:02:44.286Z","dependency_job_id":null,"html_url":"https://github.com/biocore/qurro","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biocore%2Fqurro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biocore%2Fqurro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biocore%2Fqurro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biocore%2Fqurro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/biocore","download_url":"https://codeload.github.com/biocore/qurro/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248027407,"owners_count":21035594,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","microbiome","qiime","visualization"],"created_at":"2024-11-18T22:10:05.425Z","updated_at":"2025-04-09T11:10:37.017Z","avatar_url":"https://github.com/biocore.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Qurro: Quantitative Rank/Ratio Observations\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg width=\"40%\" src=\"https://raw.githubusercontent.com/biocore/qurro/master/docs/images/logos/qurro_logo.png\" alt=\"Qurro logo\" /\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://github.com/biocore/qurro/actions/workflows/qiime2.yml\"\u003e\u003cimg src=\"https://github.com/biocore/qurro/actions/workflows/qiime2.yml/badge.svg\" alt=\"QIIME 2 CI\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/biocore/qurro/actions/workflows/standalone.yml\"\u003e\u003cimg src=\"https://github.com/biocore/qurro/actions/workflows/standalone-oldpython.yml/badge.svg\" alt=\"Standalone CI (Python 3.6 and 3.7)\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/biocore/qurro/actions/workflows/standalone.yml\"\u003e\u003cimg src=\"https://github.com/biocore/qurro/actions/workflows/standalone.yml/badge.svg\" alt=\"Standalone CI (Python ≥ 3.8)\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://codecov.io/gh/biocore/qurro\"\u003e\u003cimg src=\"https://codecov.io/gh/biocore/qurro/branch/master/graph/badge.svg\" alt=\"Code Coverage\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://zenodo.org/badge/latestdoi/158270494\"\u003e\u003cimg src=\"https://zenodo.org/badge/158270494.svg\" alt=\"DOI\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/qurro\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/qurro.svg?color=006dad\" alt=\"PyPI\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://anaconda.org/conda-forge/qurro\"\u003e\u003cimg src=\"https://img.shields.io/conda/vn/conda-forge/qurro.svg?color=43b02a\" alt=\"conda-forge\" /\u003e\u003c/a\u003e\n\u003cp\u003e(Pronounced \"churro.\")\u003c/p\u003e\n\u003c/div\u003e\n\n## What does this tool do?\nLots of tools for analyzing \" 'omic\" datasets can produce\n__feature rankings__. These rankings can be used as a guide to look at the __log-ratios__ of certain features in a dataset. Qurro is a tool for visualizing and exploring both of these types of data.\n\n### What are feature rankings?\nThe term \"feature rankings\" includes __differentials__, 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 to [ALDEx2](https://bioconductor.org/packages/release/bioc/html/ALDEx2.html), [Songbird](https://github.com/biocore/songbird/), [Corncob](https://github.com/bryandmartin/corncob/), [DESeq2](https://bioconductor.org/packages/release/bioc/html/DESeq2.html), [edgeR](https://bioconductor.org/packages/release/bioc/html/edgeR.html), etc.\n\nThe term \"feature rankings\" also includes __feature loadings__ in a [biplot](https://en.wikipedia.org/wiki/Biplot) (see [Aitchison and Greenacre 2002](https://rss.onlinelibrary.wiley.com/doi/full/10.1111/1467-9876.00275)); you can get biplots from running [DEICODE](https://github.com/biocore/DEICODE),\nwhich is a tool that works well with microbiome datasets, or from a variety of other methods.\n\nDifferentials and feature loadings alike can be interpreted as rankings -- you\ncan sort them numerically to \"rank\" features based on their association with\nsome sort of variation in your dataset.\n\n### What can we do with feature rankings?\n\nA common use of these rankings is examining the __log-ratios__ of\nparticularly high- or low-ranked features across the samples in your dataset,\nand seeing how these log-ratios relate to your sample metadata (e.g. \"does\nthis log-ratio differ between 'healthy' and 'sick' samples?\"). For\ndetails as to why this approach is useful, check out\n[this open access paper](https://www.nature.com/articles/s41467-019-10656-5).\n\n### How does this tool help?\n\n__Qurro is an interactive web application for visualizing feature rankings\nand log-ratios.__ It does this\nusing a two-plot interface: on the left side of the screen, a \"rank plot\" shows\nhow features are ranked for a selected ranking, and on the right side of the\nscreen a \"sample plot\" shows the log-ratios of selected features' abundances\nwithin samples. There are a variety of controls available for selecting\nfeatures for a log-ratio, and changing the selected log-ratio updates both the\nrank plot (highlighting selected features) and the sample plot (changing the\ny-axis value of each sample to match the selected log-ratio).\n\n**A paper describing Qurro is now available at NAR Genomics and Bioinformatics\n[here](https://academic.oup.com/nargab/article/2/2/lqaa023/5826153).**\n\n### How do I use this tool?\n\nQurro can be used standalone (as a Python 3 script that generates a\nfolder containing a HTML/JS/CSS visualization) or as a\n[QIIME 2](https://qiime2.org/) plugin (that generates a QZV file that can be\nvisualized at [view.qiime2.org](https://view.qiime2.org/) or by using\n`qiime tools view`).\n\nQurro is still being developed, so backwards-incompatible changes might\noccur. If you have any bug reports, feature requests, questions, or if you just\nwant to yell at me, then feel free to\n[open an issue](https://github.com/biocore/qurro/issues) in this repository!\n\n## Demos\n\nSee the \u003ca href=\"https://biocore.github.io/qurro\"\u003eQurro website\u003c/a\u003e for a list of\ninteractive demos using real datasets.\n\n### Screenshot: Visualizing KEGG orthologs in metagenomic data from the Red Sea\n\n\u003cimg width=\"100%\" src=\"https://raw.githubusercontent.com/biocore/qurro/master/screenshots/redsea_data.png\" alt=\"Screenshot showing a Qurro visualization of ranked features (which in this dataset correspond to KEGG orthologs) and a scatterplot plot of the log ratio of certain features' abundances in samples.\" /\u003e\n\nThis visualization (which uses data from\n[this study](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5315489/), with\ndifferentials generated by [Songbird](https://github.com/biocore/songbird/))\ncan be viewed online [here](https://biocore.github.io/qurro/demos/red_sea/index.html).\n\n## Installation and Usage\n\nYou can install Qurro using [pip](https://pip.pypa.io/en/stable/)\nor [conda](https://docs.conda.io/en/latest/).\n\n### System requirements\n**If you're using Qurro within QIIME 2,** you will need a QIIME 2 version of at\nleast 2020.11. It has been tested with QIIME 2 versions up through the most recent\nrelease, as of writing (QIIME 2 2024.10).\n\n**If you're using Qurro outside of QIIME 2,** you will need a Python version of\nat least 3.6.\n\nIn either case, Qurro should work with most modern web browsers; Firefox or Chrome are\nrecommended.\n\n### Installing with `pip`\n```bash\npip install cython \"numpy \u003e= 1.12.0\"\npip install qurro\n```\n\n### Installing with `conda`\n```bash\nconda install -c conda-forge qurro\n```\n\n### Slight field name adjustments\n\nCertain 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:\n\n| Old Character(s) | New Character |\n| ------------- | ------------- |\n| `.`  | `_`  |\n| `:`  | `;`  |\n| `]`  | `)`  |\n| `[`  | `(`  |\n| `\\ ` | \u003ccode\u003e\\|\u003c/code\u003e  |\n| `'` or `\"` | Nothing |\n\nThis is due to some downstream issues with handling these sorts of characters\nin field names. See [this issue](https://github.com/biocore/qurro/issues/66)\nfor context.\n\n## Tutorials\n\n### In-depth tutorials\nThese tutorials are all good places to start, depending on what sort of data and\nfeature rankings you have.\n\n- [Color Composition tutorial](https://nbviewer.jupyter.org/github/biocore/qurro/blob/master/example_notebooks/color_compositions/color_example.ipynb)\n  - **Data Summary:** Color composition data from abstract paintings\n  - Feature rankings: Feature loadings in an arbitrary compositional biplot\n  - Qurro used through QIIME 2 or standalone?: Standalone\n\n- [\"Moving Pictures\" tutorial](https://nbviewer.jupyter.org/github/biocore/qurro/blob/master/example_notebooks/moving_pictures/moving_pictures.ipynb)\n  - **Data Summary:** Microbiome 16S rRNA marker gene sequencing data from four types of body site samples\n  - Feature rankings: Feature loadings in a [DEICODE](https://github.com/biocore/DEICODE) biplot\n  - Qurro used through QIIME 2 or standalone?: QIIME 2\n\n- [Transcriptomics tutorial](https://nbviewer.jupyter.org/github/biocore/qurro/blob/master/example_notebooks/ALDEx2_TCGA_LUSC/transcriptomic_example.ipynb)\n  - **Data Summary:** Gene expression (\"RNA-Seq\") data from TCGA tumor and \"solid tissue normal\" samples\n  - Feature rankings: [ALDEx2](https://bioconductor.org/packages/release/bioc/html/ALDEx2.html) differentials\n  - Qurro used through QIIME 2 or standalone?: Standalone\n\n### Selection tutorial\nThere are a lot of different ways to select features in Qurro, and the\ninterface can be difficult to get used to. This document describes all of these\nmethods, and provides some examples of where they could be useful in practice.\n\n- [Selection tutorial](https://nbviewer.jupyter.org/github/biocore/qurro/blob/master/example_notebooks/selection/selection.ipynb)\n\n### Basic command-line tutorials\nThese tutorials show examples of using Qurro in identical ways both inside and\noutside of QIIME 2.\n\n- [Sleep Apnea tutorial](https://nbviewer.jupyter.org/github/biocore/qurro/blob/master/example_notebooks/DEICODE_sleep_apnea/deicode_example.ipynb)\n  - Feature rankings: feature loadings in a [DEICODE](https://github.com/biocore/DEICODE) biplot\n\n- [Red Sea tutorial](https://nbviewer.jupyter.org/github/biocore/qurro/blob/master/example_notebooks/songbird_red_sea/songbird_example.ipynb)\n  - Feature rankings: [Songbird](https://github.com/biocore/songbird/) differentials\n\n## Qarcoal\n**Qarcoal** (pronounced \"charcoal\") is a new part of Qurro that lets you\ncompute log-ratios based on taxonomic searching directly from the command-line.\nThis can be useful for a variety of reasons.\n\nCurrently, Qarcoal is only available through Qurro's QIIME 2 plugin interface.\nPlease see [**`qarcoal_example.ipynb`**](https://nbviewer.jupyter.org/github/biocore/qurro/blob/master/example_notebooks/qarcoal/qarcoal_example.ipynb)\nfor a demonstration of using Qarcoal.\n\n## Poster\nWe presented [this poster](https://biocore.github.io/qurro/CRISP-poster.pdf) on Qurro at the\n[2019 CRISP Annual Review](https://crisp.engineering.virginia.edu/2019-crisp-annual-review).\nThe 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!\n\n## Acknowledgements\n\n### Dependencies\n\nCode files for the following projects are distributed within\n`qurro/support_files/vendor/`.\nSee the `qurro/dependency_licenses/` directory for copies of these software projects'\nlicenses (each of which includes a respective copyright notice).\n- [Vega](https://vega.github.io/vega/)\n- [Vega-Lite](https://vega.github.io/vega-lite/)\n- [Vega-Embed](https://github.com/vega/vega-embed)\n- [jQuery](https://jquery.com/)\n- [DataTables](https://datatables.net/)\n- [RequireJS](https://requirejs.org/)\n- [Bootstrap](https://getbootstrap.com/docs/4.3/getting-started/introduction/)\n- [Bootstrap Icons](https://icons.getbootstrap.com/)\n  - We make use of the \"Question fill\" icon's SVG, as well as some example code\n    for embedding this or other icons in CSS.\n- [Popper.js](https://popper.js.org/) (included within the Bootstrap JS \"bundle\" file)\n\nThe following software projects are required for Qurro's python code\nto function, although they are not distributed with Qurro (and are\ninstead installed alongside Qurro).\n- [Altair](https://altair-viz.github.io/)\n- [biom-format](http://biom-format.org/)\n- [click](https://palletsprojects.com/p/click/)\n- [NumPy](https://www.numpy.org/)\n- [pandas](https://pandas.pydata.org/)\n- [scikit-bio](http://scikit-bio.org/)\n\n### Testing Dependencies\n\nFor python testing/style checking, Qurro uses\n[pytest](https://docs.pytest.org/en/latest/),\n[pytest-cov](https://github.com/pytest-dev/pytest-cov),\n[flake8](http://flake8.pycqa.org/en/latest/), and\n[black](https://github.com/ambv/black). You'll also need to have QIIME 2\ninstalled to run most of the python tests (note that, due to click vs. black\nvs. QIIME 2 dependency issues, you should use a QIIME 2 environment of at least\n2022.8; see\n[`CONTRIBUTING.md`](https://github.com/biocore/qurro/blob/master/CONTRIBUTING.md)\nfor details).\n\nFor JavaScript testing/style checking, Qurro uses\n[Mocha](https://mochajs.org/), [Chai](https://www.chaijs.com/),\n[mocha-headless-chrome](https://github.com/direct-adv-interfaces/mocha-headless-chrome),\n[nyc](https://github.com/istanbuljs/nyc), [jshint](https://jshint.com/),\nand [prettier](https://prettier.io/).\n\nQurro also uses [GitHub Actions](https://github.com/features/actions) and\n[Codecov](https://codecov.io/).\n\nThe Jupyter notebooks in Qurro's `example_notebooks/` folder are automatically\nrerun using [nbconvert](https://nbconvert.readthedocs.io/en/latest/index.html),\nalso.\n\n### Data Sources\n\nThe test data located in `qurro/tests/input/mackerel/` were exported from\nQIIME 2 artifacts in [this repository](https://github.com/knightlab-analyses/qurro-mackerel-analysis). These data are from Minich et al. 2020 [1].\n\nThe test data located in `qurro/tests/input/byrd/` are from\n[this repository](https://github.com/knightlab-analyses/reference-frames).\nThese data, in turn, originate from Byrd et al.'s 2017 study on atopic\ndermatitis [2].\n\nThe test data located in `qurro/tests/input/sleep_apnea/`\n(and in `example_notebooks/DEICODE_sleep_apnea/input/`)\nare from [this Qiita study](https://qiita.ucsd.edu/study/description/10422),\nwhich is associated with Tripathi et al.'s 2018 study on sleep apnea [4].\n\nThe test data located in `qurro/tests/input/moving_pictures/` (and in\n`example_notebooks/moving_pictures/data/`)\nare from [the QIIME 2 moving pictures tutorial](https://docs.qiime2.org/2019.1/tutorials/moving-pictures/).\nThe `ordination` files in these folders were computed based on the\n[DEICODE moving pictures tutorial](https://library.qiime2.org/plugins/deicode/19/).\nThese data (sans the DEICODE ordination) are associated with Caporaso et al. 2011 [5].\n\nLastly, the data located in `qurro/tests/input/red_sea`\n(and in `example_notebooks/songbird_red_sea/input/`, and shown in the\nscreenshot above) were taken from Songbird's GitHub repository in its\n[`data/redsea/`](https://github.com/biocore/songbird/tree/master/data/redsea)\nfolder, and are associated with Thompson et al. 2017 [3].\n\n### Logo\n\nQurro's logo was created using the [Lalezar](https://github.com/BornaIz/Lalezar) font.\nAlso, shout out to [this gist](https://gist.github.com/DavidWells/7d2e0e1bc78f4ac59a123ddf8b74932d) for showing how to center images in GitHub markdown files (which is more of a hassle than it sounds).\n\n### Special Thanks\n\nThe design of Qurro was strongly inspired by\n[EMPeror](https://github.com/biocore/emperor) and\n[q2-emperor](https://github.com/qiime2/q2-emperor/), along with\n[DEICODE](https://github.com/biocore/DEICODE). A big shoutout to\nYoshiki Vázquez-Baeza for his help in planning this project, as well as to\nCameron Martino for a ton of work on getting the code in a distributable state\n(and making it work with QIIME 2). Thanks also to Jamie Morton, who wrote the\noriginal code for producing rank and sample plots from which this is derived.\n\nAnd thanks to a bunch of the Knight Lab for helping name the tool :)\n\n## Citing Qurro\n\nIf you use Qurro in your research, please cite it!\nThe preferred citation for Qurro is [this manuscript at NAR Genomics and\nBioinformatics](https://academic.oup.com/nargab/article/2/2/lqaa023/5826153).\nHere's the BibTeX:\n```\n@article {fedarko2020,\n    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},\n    title = \"{Visualizing ’omic feature rankings and log-ratios using Qurro}\",\n    journal = {NAR Genomics and Bioinformatics},\n    volume = {2},\n    number = {2},\n    year = {2020},\n    month = {04},\n    issn = {2631-9268},\n    doi = {10.1093/nargab/lqaa023},\n    url = {https://doi.org/10.1093/nargab/lqaa023},\n    note = {lqaa023},\n    eprint = {https://academic.oup.com/nargab/article-pdf/2/2/lqaa023/33137933/lqaa023.pdf},\n}\n```\n\n## References\n\n[1] Minich, J. J., Petrus, S., Michael, J. D., Michael, T. P., Knight, R., \u0026\nAllen, E. E. (2020). Temporal, environmental, and biological drivers of the\nmucosal microbiome in a wild marine fish, Scomber japonicus. _mSphere, 5_(3),\ne00401-20. [Link](https://journals.asm.org/doi/full/10.1128/mSphere.00401-20).\n\n[2] Byrd, A. L., Deming, C., Cassidy, S. K., Harrison, O. J., Ng, W. I., Conlan, S., ... \u0026 NISC Comparative Sequencing Program. (2017). Staphylococcus aureus and Staphylococcus epidermidis strain diversity underlying pediatric atopic dermatitis. _Science Translational Medicine, 9_(397), eaal4651.\n[Link](https://www.ncbi.nlm.nih.gov/pubmed/28679656).\n\n[3] Thompson, L. R., Williams, G. J., Haroon, M. F., Shibl, A., Larsen, P.,\nShorenstein, J., ... \u0026 Stingl, U. (2017). Metagenomic covariation along densely\nsampled environmental gradients in the Red Sea. _The ISME Journal, 11_(1), 138.\n[Link](https://www.ncbi.nlm.nih.gov/pubmed/27420030).\n\n[4] Tripathi, A., Melnik, A. V., Xue, J., Poulsen, O., Meehan, M. J., Humphrey, G., ... \u0026 Haddad, G. (2018). Intermittent hypoxia and hypercapnia, a hallmark of obstructive sleep apnea, alters the gut microbiome and metabolome. _mSystems, 3_(3), e00020-18.\n[Link](https://www.ncbi.nlm.nih.gov/pubmed/29896566).\n\n[5] Caporaso, J. G., Lauber, C. L., Costello, E. K., Berg-Lyons, D., Gonzalez, A., Stombaugh, J., ... \u0026 Gordon, J. I. (2011). Moving pictures of the human microbiome. _Genome Biology, 12_(5), R50.\n[Link](https://www.ncbi.nlm.nih.gov/pubmed/21624126).\n\n## License\n\nThis tool is licensed under the [BSD 3-clause license](https://en.wikipedia.org/wiki/BSD_licenses#3-clause_license_(%22BSD_License_2.0%22,_%22Revised_BSD_License%22,_%22New_BSD_License%22,_or_%22Modified_BSD_License%22)).\nOur particular version of the license is based on [scikit-bio](https://github.com/biocore/scikit-bio)'s [license](https://github.com/biocore/scikit-bio/blob/master/COPYING.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiocore%2Fqurro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbiocore%2Fqurro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiocore%2Fqurro/lists"}