Register a QIIME 2 plugin

Register a QIIME 2 plugin#

This document will describe how to register a plugin, allowing this plugin to interact with the QIIME 2 framework.

Overview#

There are several high-level steps to registering a QIIME 2 plugin:

  1. A QIIME 2 plugin must define one or more Python 3 functions that will be accessible through QIIME.

  2. The plugin must be a Python 3 package that can be installed with setuptools.

  3. The plugin must then instantiate a qiime2.plugin.Plugin object and define some information including the name of the plugin and its URL. In the plugin package’s setup.py file, this instance will be defined as an entry point.

  4. The plugin must then register its functions as QIIME 2 Actions, which will be accessible to users through any of the QIIME 2 interfaces.

  5. Optionally, the plugin could be distributed through Anaconda or pypi as that will simplify installation for QIIME 2 users.

These steps are covered in detail below.

Writing a simple QIIME 2 plugin should be a straightforward process. For example, the q2-emperor plugin, which connects Emperor to QIIME 2, is written in a little over 100 lines of code (excluding unit tests and assets). It is a standalone plugin that defines how and which functionality in Emperor should be accessible through QIIME 2. Plugins will vary in their complexity. For example, a plugin that defines a lot of new functionality would likely be quite a bit bigger. q2-diversity is a good example of this. Unlike q2-emperor, there is some specific functionality (and associated unit tests) defined in this project, and it depends on several other Python 3 compatible libraries.

Before starting to write a plugin, you should install QIIME 2 and some plugins to familiarize yourself with the system and to provide a means for testing your plugin.

Instantiating a plugin#

The next step is to instantiate a QIIME 2 Plugin object. This might look like the following:

from qiime2.plugin import Plugin
import q2_diversity

plugin = Plugin(
    name='diversity',
    version=q2_diversity.__version__,
    website='https://github.com/qiime2/q2-diversity',
    package='q2_diversity',
    description=('This QIIME 2 plugin supports metrics for calculating '
                'and exploring community alpha and beta diversity through '
                'statistics and visualizations in the context of sample '
                'metadata.'),
    short_description='Plugin for exploring community diversity.',
)

This will provide QIIME with essential information about your Plugin.

The name parameter is the name that users will use to access your plugin from within different QIIME 2 interfaces. It should be a “command-line-friendly” name, so should not contain spaces or punctuation. (Avoiding uppercase characters and using dashes (-) instead of underscores (_) are preferable in the plugin name, but not required).

version should be the version number of your package (the same that is used in its setup.py).

website should be the page where you’d like end users to refer for more information about your package.

package should be the Python package name for your plugin.

description should give a brief description of this plugin’s functionality. This will be displayed when that plugin’s help documentation is accessed via the QIIME 2 framework.

short_description should give a very brief description of this plugin’s functionality. This will be displayed when the QIIME 2 help documentation is accessed.

While not shown in the previous example, plugin developers can optionally provide the following parameters to qiime2.plugin.Plugin:

  • citations: A list of bibtex-formatted citations. These are provided in a separate citations.bib file, loaded via the Citations API, and accessed by using their bibtex indices as keys. Citations can be listed during plugin or action registration, or both, but will usually only be listed for individual actions unless if a single reference is appropriate for all actions in that plugin. q2-diversity has no such plugin-wide citation listed here.

  • user_support_text: free text describing how users should get help with the plugin (e.g. issue tracker, StackOverflow tag, mailing list, etc.). If not provided, users are referred to the website for support. Plugin developers are free to support their plugins on the QIIME 2 Forum, so you can include that URL as the user_support_text for your plugin. If you do that, you should get in the habit of monitoring the QIIME 2 Forum for technical support questions.

The Plugin object can live anywhere in your project, but by convention it will be in a file called plugin_setup.py. You can see a complete working example in q2-dwq2 here.

Defining your plugin object as an entry point#

Finally, you need to tell QIIME where to find your instantiated Plugin object. This is done by defining it as an entry_point in your project’s setup.py file. In q2-diversity, this is done as follows:

setup(
    ...
    entry_points={
        'qiime2.plugins': ['q2-diversity=q2_diversity.plugin_setup:plugin']
    }
)

The relevant key in the entry_points dictionary will be 'qiime2.plugins', and the value will be a single element list containing a string formatted as <distribution-name>=<import-path>:<instance-name>. <distribution-name> is the name of the Python package distribution (matching the value passed for name in this call to setup); <import-path> is the import path for the Plugin instance you created above; and <instance-name> is the name for the Plugin instance you created above.