Developing a QIIME 2 plugin¶

Create a function to register as a Method¶

A function that can be registered as a Method will have a Python 3 API, and the inputs and outputs for that function will be annotated with their data types using mypy syntax. mypy annotation does not impact functionality (though the syntax is new to Python 3), so these can be added to existing functions in your Python 3 software project. An example is q2_diversity.beta_phylogenetic, which takes a biom.Table, an skbio.TreeNode and a str as input, and produces an skbio.DistanceMatrix as output. The signature for this function is:

def beta_phylogenetic(table: biom.Table, phylogeny: skbio.TreeNode,
                      metric: str)-> skbio.DistanceMatrix:

As far as QIIME is concerned, it doesn’t matter what happens inside this function (as long as it adheres to the contract defined by the signature regarding the input and output types). For example, q2_diversity.beta_phylogenetic is making some calls to the skbio and biom APIs, but it could be doing anything, including making system calls (if your plugin is wrapping a command line application), executing an R library, etc.

Create a function to register as a Visualizer¶

Defining a function that can be registered as a Visualizer is very similar to defining one that can be registered as a Method with a few additional requirements.

First, the first parameter to this function must be output_dir. This parameter should be annotated with type str.

Next, at least one index.* file must be written to output_dir by the function. This index file will provide the starting point for your users to explore the Visualization object that is generated by the Visualizer. Index files with different extensions can be created by the function (e.g., index.html, index.tsv, index.png), but at least one must be created. You can write whatever files you want to output_dir, including tables, graphics, and textual descriptions of the results, but you should expect that your users will want to find those files through your index file(s). If your function does create many different files, an index.html containing links to those files is likely to be helpful.

Finally, the function cannot return anything, and its return type should be annotated as None.

q2_diversity.alpha_group_significance is an example of a function that can be registered as a Visualizer. In addition to its output_dir, it takes alpha diversity results in a pandas.Series and sample metadata in a qiime2.Metadata object and creates several different files (figures and tables) that are linked and/or presented in an index.html file. The signature of this function is:

def alpha_group_significance(output_dir: str, alpha_diversity: pd.Series,
                             metadata: qiime2.Metadata) -> None:

Registering a Method¶

First we’ll register a Method by calling plugin.methods.register_function as follows:

from q2_types import (FeatureTable, Frequency, Phylogeny,
                      Rooted, DistanceMatrix)
from qiime2.plugin import Str, Choices, Properties, Metadata

import q2_diversity
import q2_diversity._beta as beta

plugin.methods.register_function(
    function=q2_diversity.beta_phylogenetic,
    inputs={'table': FeatureTable[Frequency],
            'phylogeny': Phylogeny[Rooted]},
    parameters={'metric': Str % Choices(beta.phylogenetic_metrics())},
    outputs=[('distance_matrix', DistanceMatrix % Properties('phylogenetic'))],
    input_descriptions={
        'table': ('The feature table containing the samples over which beta '
                  'diversity should be computed.'),
        'phylogeny': ('Phylogenetic tree containing tip identifiers that '
                      'correspond to the feature identifiers in the table. '
                      'This tree can contain tip ids that are not present in '
                      'the table, but all feature ids in the table must be '
                      'present in this tree.')
    },
    parameter_descriptions={
        'metric': 'The beta diversity metric to be computed.'
    },
    output_descriptions={'distance_matrix': 'The resulting distance matrix.'},
    name='Beta diversity (phylogenetic)',
    description=("Computes a user-specified phylogenetic beta diversity metric"
                 " for all pairs of samples in a feature table.")
)

The values being provided are:

function: The function to be registered as a method.

inputs: A dictionary indicating the parameter name and its semantic type, for each input Artifact. These semantic types differ from the data types that you provided in your mypy annotation of the input, as semantic types describe the data, where the data types indicate the structure of the data. The currently available semantic types are detailed here, along with a discussion of the motivation for defining semantic types. In the example above we’re indicating that the table parameter must be a FeatureTable of Frequency (i.e. counts), and that the phylogeny parameter must be a Phylogeny that is Rooted. Notice that the keys in inputs map directly to the parameter names in q2_diversity.beta_phylogenetic.

parameters: A dictionary indicating the parameter name and its semantic type, for each input Parameter. These parameters are primitive values (i.e., non-Artifacts). In the example above, we’re indicating that the metric should be a string from a specific set (in this case, the set of known phylogenetic beta diversity metrics).

outputs: A list of tuples indicating each output name and its semantic type.

input_descriptions: A dictionary containing input artifact names and their corresponding descriptions. This information is used by interfaces to instruct users how to use each specific input artifact.

parameter_descriptions: A dictionary containing parameter names and their corresponding descriptions. This information is used by interfaces to instruct users how to use each specific input parameter. You should not include any default parameter values in these descriptions, as these will generally be added automatically by an interface.

output_descriptions: A dictionary containing output artifact names and their corresponding descriptions. This information is used by interfaces to inform users what each specific output artifact will be.

name: A human-readable name for the Method. This may be presented to users in interfaces.

description: A human-readable description of the Method. This may be presented to users in interfaces.

Registering a Visualizer¶

Registering Visualizers is the same as registering Methods, with two exceptions.

First, you call plugin.visualizers.register_function to register a Visualizer.

Next, you do not provide outputs or output_descriptions when making this call, as Visualizers, by definition, only return a single visualization. Since the visualization output path is a required parameter, you do not include this in an outputs list (it would be the same for every Visualizer that was ever registered, so it is added automatically).

Registering q2_diversity.alpha_group_significance as a Visualizer looks like the following:

plugin.visualizers.register_function(
    function=q2_diversity.alpha_group_significance,
    inputs={'alpha_diversity': SampleData[AlphaDiversity]},
    parameters={'metadata': Metadata},
    input_descriptions={
        'alpha_diversity': 'Vector of alpha diversity values by sample.'
    },
    parameter_descriptions={
        'metadata': 'The sample metadata.'
    },
    name='Alpha diversity comparisons',
    description=("Visually and statistically compare groups of alpha diversity"
                 " values.")
)