Tutorial: A step-by-step guide to building your first QIIME 2 plugin#
Note
My approach to writing Developing with QIIME 2 is to publish early, and to publish often. This is well captured in this quote by Daniele Procida from Diátaxis:
It’s natural to want to complete large tranches of work before you publish them, so that you have something substantial to show each time. Avoid this temptation - every step in the right direction is worth publishing immediately. (source)
One caveat that I’ll add, since Developing with QIIME 2 is about developing software while Diátaxis is about developing documentation, is that functional code should only be “published” (e.g., applied in real world applications or shared with others who may do that) after it has been sufficiently tested. I’ll come back to software testing shortly.
This tutorial is a work-in-progress. đźšś
This tutorial will walk step-by-step through building a first QIIME 2 plugin, and is intended to be read from beginning to end.
The plugin you’ll create will provide support for some of the most fundamental algorithms in bioinformatics, and will ultimately contain a mix of QIIME 2 methods, visualizers, and pipelines. You’ll learn to define new artifact classes, which let you expand QIIME 2 in new directions, and how artifact classes relate to formats, transformers, semantic types. You’ll add parallel computing support to a method that is initially implemented without parallel support. You’ll develop executable usage examples, so your users can learn how to apply your plugin, and you can receive automated notifications if changes you (or others) make to your code are backward incompatible, necessitating changes to the documentation. And, as with all QIIME 2 plugins, the plugin you build will record data provenance when it’s used, support provenance replay, and will be immediately accessible through multiple interfaces including q2cli and the Python 3 API. You’ll also be able to run a few additional commands to generate Galaxy workflows for all of your plugin actions. Finally, you’ll receive guidance on how to move forward to create your own QIIME 2 plugin as a next step.
Let’s get started!
Note
If you’re already comfortable with plugin development and are looking for instructions to achieve a specific task, you may find more targeted instructions in the Plugin Development How-To Guides.