Plugin Development API

This section details the public API for plugin development. Broadly speaking, everything that is necessary to build a QIIME 2 plugin is available in qiime2.plugin or qiime2.metadata.

Individual Topics

• Plugin & Registration
• Formats
• Types
• Citations
• Testing
• Utilities
• Pipeline Context Object
• Usage Examples

Plugin API List

Plugin Object

qiime2.plugin.Plugin

A QIIME 2 Plugin.

Registration

plugin.PluginMethods.register_function	Register a method to the associated plugin.
plugin.PluginVisualizers.register_function	Register a visualizer to the associated plugin.
plugin.PluginPipelines.register_function	Register a pipeline to the associated plugin.
Plugin.register_validator	Decorator which registers a validator
Plugin.register_transformer	Decorator which registers a transformer to convert data
Plugin.register_formats	Register file formats to the plugin
Plugin.register_views	Register arbitrary views (Python classes or formats) to the plugin
Plugin.register_semantic_types	Register semantic type fragments to the plugin
Plugin.register_semantic_type_to_format	Connect a semantic type expression to a format.
Plugin.register_artifact_class	Register an artifact class which defines an Artifact

Formats

qiime2.plugin.TextFileFormat
qiime2.plugin.BinaryFileFormat
qiime2.plugin.DirectoryFormat
qiime2.plugin.SingleFileDirectoryFormat
qiime2.plugin.ValidationError

Types

qiime2.plugin.SemanticType	Create a new semantic type.
qiime2.plugin.Properties	A one or more semantic properties to add to an existing type.
qiime2.plugin.Visualization	The type of a QIIME 2 Visualization.
qiime2.plugin.Bool	A boolean value (True/False).
qiime2.plugin.Str	A string of Unicode characters (i.e. text).
qiime2.plugin.Int	An integer without any particular bounds.
qiime2.plugin.Float	A 64 bit floating point number.
qiime2.plugin.Threads	The number of logical threads to use (OS threads/CPUs/Cores).
qiime2.plugin.Jobs	The number of jobs to submit as an integer that is greater than zero (exclusive).
qiime2.plugin.Choices	A predicate which defines a set of allowable values.
qiime2.plugin.Range	A predicate which defines a contiguous range of allowable values.
qiime2.plugin.Start	Shorthand to generate a Range
qiime2.plugin.End	Shorthand to generate a Range
qiime2.plugin.Metadata	Tabular metadata where unique identifiers can be associated with columns.
qiime2.plugin.MetadataColumn	A column of a qiime2.Metadata.
qiime2.plugin.Categorical	The categorical variant for MetadataColumn.
qiime2.plugin.Numeric	The Numeric variant for MetadataColumn.
qiime2.plugin.Set	Deprecated - use List or Collection instead
qiime2.plugin.List	An alias for a Collection with numeric auto-incrementing keys.
qiime2.plugin.Collection	An ordered set of key-value pairs.
qiime2.plugin.TypeMap	A table of input types which match to output types.
qiime2.plugin.TypeMatch	A trivial TypeMap such that every entry maps to itself.

Citations

qiime2.plugin.Citations	A simple subclass of collections.OrderedDict but iterates over values instead of keys by default.
qiime2.plugin.CitationRecord	A collections.namedtuple() of bibtex entry type and entry fields.

Testing

qiime2.plugin.testing.TestPluginBase	Test harness for simplifying testing QIIME 2 plugins.
qiime2.plugin.testing.assert_no_nans_in_tables	Checks for NaNs present in any of the tables in the indicated file then resets to the head of the file.

Utilities

qiime2.util.duplicate	Alternative to shutil.copyfile() this will use os.link() when possible.
qiime2.util.redirected_stdio	A context manager to redirect stdio to a new file (if provided).
qiime2.plugin.util.transform
qiime2.plugin.util.get_available_cores	Finds the number of currently available (logical) cores.

Additional Objects

These objects are not part of the qiime2.plugin module, but are commonly used by plugins (and users).

Metadata

qiime2.Metadata	Store metadata associated with identifiers in a study.
qiime2.MetadataColumn	Abstract base class representing a single metadata column.
qiime2.NumericMetadataColumn	A single metadata column containing numeric data.
qiime2.CategoricalMetadataColumn	A single metadata column containing categorical data.

Pipeline Context Object (ctx)

Context.get_action(plugin, action)	Return a function matching the callable API of an action.
Context.make_artifact(type, view[, view_type])	Return a new artifact from a given view.

Usage Examples

Usage.init_artifact	Communicate that an artifact will be needed.
Usage.init_artifact_from_url	Obtain an artifact from a url.
Usage.init_artifact_collection	Communicate that a result collection containing artifacts will be needed.
Usage.init_metadata	Communicate that metadata will be needed.
Usage.init_metadata_from_url	Obtain metadata from a url.
Usage.init_format	Communicate that a file/directory format will be needed.
Usage.import_from_format	Communicate that an import should be done.
Usage.construct_artifact_collection	Return a UsageVariable of type artifact_collection given a list or dict of its members.
Usage.get_artifact_collection_member	Accesses and returns a member of a ResultCollection as a UsageVariable.
Usage.get_metadata_column	Communicate that a column should be retrieved.
Usage.view_as_metadata	Communicate that an artifact should be views as metadata.
Usage.merge_metadata	Communicate that these metadata should be merged.
Usage.comment	Communicate that a comment should be made.
Usage.help	Communicate that help text should be displayed.
Usage.peek	Communicate that an artifact should be peeked at.
Usage.action	Communicate that some action should be performed.
Usage.UsageAction	An object which represents a deferred lookup for a QIIME 2 action.
Usage.UsageInputs	A dict-like mapping of parameters to arguments for invoking an action.
Usage.UsageOutputNames	A dict-like mapping of action outputs to desired names.
UsageOutputs	A vanity class over qiime2.sdk.Results.
UsageVariable	A variable which represents some QIIME 2 generate-able value.
UsageVariable.assert_has_line_matching	Communicate that the result of this variable should match a regex.
UsageVariable.assert_output_type	Communicate that this variable should have a given semantic type.