Using QIIME 2#
Your guide to becoming a QIIME 2 Framework power user. 🌳
Development status of this content
Using QIIME 2 is in relatively early development. As a result some URLs may change, and some content maybe incomplete or have formatting problems.
Start reading here 👋#
As the ecosystem of QIIME 2 distributions and plugins continues to grow, it has become necessary to make a split in the documentation between general-purpose information that describes how to use the QIIME 2 Framework (🌳), and how to apply the tools that build on it to achieve your data analysis goals.
We know that you’re interested in QIIME 2 primarily for the latter – to achieve specific analysis goals related to microbiome data science – so we’ll start by providing references to where you can find that information.
Distribution-specific documentation#
If you’re looking for documentation on how to analyze microbiome marker gene (i.e., amplicon) data, you should refer to the QIIME 2 amplicon distribution documentation.
That documentation is in transition and can now be found at https://amplicon-docs.readthedocs.io.
If you’re looking for the “old” QIIME 2 amplicon distribution documentation (https://docs.qiime2.org), you can find that here.
We’re now focusing our documentation effort on https://amplicon-docs.readthedocs.io, but some content is not yet transferred, so the old docs are still relevant.
If you want to analyze microbiome metagenomic data, refer to the MOSHPIT documentation at https://moshpit.readthedocs.io. (MOSHPIT was referred to as the QIIME 2 metagenome distribution during its early development.)
If you’re looking for documentation on the tiny distribution, you’re most likely interested in plugin development.
Welcome!
Your best reference will be Developing with QIIME 2, our free, online Research Software Engineering text.
Plugin-specific documentation#
Stand-alone plugins are those that are not included in existing distributions, and these will generally provide their own documentation linked from the new QIIME 2 Library. The list of these is growing, but some current (as of 28 February 2025) examples include:
Data-set specific documentation#
We expect to increasingly have documentation that is focused on analysis of specific interesting data sets. A good current example of this is the QIIME 2 Cancer AutoFMT Tutorial (q2-cat-book). Another one that is planned will be based on the Meilander et al. (2024) “gut-to-soil” study, and will build from our Artifact Archive on Zenodo.
These will sometimes cross distributions and stand-alone plugins, for example integrating tools from MOSHPIT, q2-boots, and perhaps even metabolomics plugins, to illustrate microbiome multi-omics analysis workflows.
More on that soon!
Becoming a QIIME 2 Framework power user 💃🏻#
So what is Using QIIME 2?
Using QIIME 2 serves as a source for you to refer to when you need to accomplish specific tasks that are general to using the QIIME 2 Framework.
The distributions and plugins described above are all built on the QIIME 2 Framework, so Using QIIME 2 presents information that is general to all of them.
That includes things like using Artifacts as metadata, replaying provenance[1], creating and using an artifact cache, configuring and using our Parsl-based parallel computing framework, and more.
Using QIIME 2 will also include chapters that can help you understand the system when you want to go deeper, including things like what QIIME 2 Artifacts (e.g., .qza files) and Visualizations (e.g., .qzv files) are[2], and why you need to import your data before using QIIME 2[3]. Understanding these topics will help you carry out advanced biological data science workflows and manage the corresponding data, but they aren’t strictly necessary for performing data with tools that build on QIIME 2.
If you’re ready to become a QIIME 2 Framework power user, read on…
Note
At this time (28 February 2025), Using QIIME 2 is still in relatively early development as we write new content and pull from existing resources. Searching and reading the QIIME 2 Forum can help you answer many of your own questions as it now represents nearly 10 years of questions, answers, and discussion about microbiome data science.
Organization of Using QIIME 2#
Using QIIME 2 is organized under the Diátaxis framework [1], which categorizes content into sections containing Tutorials, How-To-Guides, Explanations, and References. Each serves a different goal for the reader:
Chapter |
Purpose |
|---|---|
Tutorials |
Provide a guided exploration of a topic for learning. |
How To Guides |
Provide step-by-step instructions on how to accomplish specific goals. |
Explanations |
Provide a discussion intended to aid in understanding a specific topic. |
References |
Provide specific information (e.g., a list of utilities available through q2cli). |
You can navigate these sections on the left sidebar.
Acknowledgements#
Using QIIME 2 is the result of past, present, and future (🤞) collaborative efforts.
The authors would like to thank those who have contributed to the writing of the original QIIME 2 User Documentation. Some of the content in Using QIIME 2 is sourced directly from that material.
The QIIME 2 Forum moderators and community members have also been instrumental to the development of ideas and content presented here.
Finally, as this project gets further along, you can see who has contributed directly to Using QIIME 2.
Getting Help#
For the most up-to-date information on how to get help with QIIME 2, as a user or developer, see here.
Funding 🙏#
This work was funded in part by NIH National Cancer Institute Informatics Technology for Cancer Research grant 1U24CA248454-01.
This book is built with MyST Markdown and Jupyter Book, which are supported in part with funding from the Alfred P. Sloan Foundation.
Initial support for the development of QIIME 2 was provided through a grant from the National Science Foundation.
License#
Using QIIME 2 led by Greg Caporaso is licensed under CC BY-NC-ND 4.0 
.