Plugin & Registration

Plugin & Registration#

class qiime2.plugin.Plugin(name, version, website, package=None, project_name=None, citation_text=None, user_support_text=None, short_description=None, description=None, citations=None)[source]#

A QIIME 2 Plugin.

An instance of this class defines all features of a given plugin and is instantiated as a module global (i.e. a singleton).

Parameters:

  • name (str) – The name of the plugin (hyphens will be automatically replaced for the plugin ID)

  • version (str) – The version of the plugin (this should match the package version)

  • website (str) – A URL to find more information about this plugin

  • package (str | None) – The Python package name of your plugin. This is largely defunct and is set by the entry-point during plugin loading.

  • project_name (str | None) – The external name of the plugin (distinct from the internal name, i.e. q2-my-plugin vs my-plugin). Also defunct and set by the entry-point during plugin loading.

  • citation_text (Any | None) – Deprecated. Does nothing. Use citations instead.

  • user_support_text (str | None) – A message about where to find user support. The default will suggest users visit the QIIME 2 forum.

  • short_description (str | None) – A small (single-line) description to help identify the plugin in a list.

  • description (str | None) – A more complete description of the plugins purpose.

  • citations (CitationRecord or list of CitationRecord) – Citation(s) to associate with a result whenever this plugin is used. Can also use an entire Citations object.

Examples

>>> plugin = Plugin('my-plugin', __version__, website)
register_formats(*formats, citations=None)[source]#

Register file formats to the plugin

Parameters:
Return type:

None

Notes

SingleFileDirectoryFormat() returns a DirectoryFormat

register_views(*views, citations=None)[source]#

Register arbitrary views (Python classes or formats) to the plugin

Parameters:

  • *views (type) – Views which are created or defined by this plugin

  • citations (CitationRecord or list of CitationRecord) – Citation(s) to associate with a result whenever this format is used internally. Can also use an entire Citations object.

Return type:

None

register_validator(semantic_expression)[source]#

Decorator which registers a validator

Parameters:

semantic_expression (semantic type expression) – An expression (may include operators like union (|)) which will be compared to an artifact. If the artifact is in the domain of the type expression, it will be transformed into a view that matches the type annotation of the decorated function and that function will be executed.

Returns:

A decorator which can be applied to a function which takes data as the first argument and level as the second. data must be annotated with a type which will become the transformed view. level should accept the strings "min" and "max". It does not necessarily need to change behavior based on level, but it is encouraged where it could save the user time.

Return type:

decorator

Examples

>>> @plugin.register_validator(Foo | Bar)
... def validate_something(data: pd.DataFrame,
...                        level: Literal['min', 'max']):
...     if data.empty:
...         raise ValidationError("This data is empty.")
register_transformer(_fn=None, *, citations=None)[source]#

Decorator which registers a transformer to convert data

This decorator may be used with or without arguments.

Parameters:

  • _fn (Callable) – Ignore this parameter as it is the mechanism to allow argumentless decoration

  • citations (CitationRecord or list of CitationRecord) – Citation(s) to associate with a result whenever this transformer is used internally. Can also use an entire Citations object.

Returns:

A decorator which can be applied to a function which takes a single argument with a type annotation and a single return annotation. This decorated function will then be executed whenever data matching the type annotation exists and there is a need to view that data as the return annotation.

Return type:

decorator

Notes

Since the function is entirely defined by the input and output type, the name of the function is usually unimportant and only adds noise. We tend to use _<number> as the name, but any other name may be used.

Examples

>>> @plugin.register_transformer
... def _0(data: pd.DataFrame) -> CSVFormat:
...     ff = CSVFormat()
...     with ff.open() as fh:
...         data.write_csv(fh)
...     return ff

>>> @plugin.register_transformer(citations=[
...     citations['baerheim1994effect'],
...     citations['silvers1997effects']
... ])
... def _1(ff: CSVFormat) -> pd.DataFrame:
...     with ff.open() as fh:
...         return pd.read_csv(fh)
register_semantic_types(*type_fragments)[source]#

Register semantic type fragments to the plugin

Parameters:

*type_fragments (semantic types) – Semantic type fragments to register. If a plugin had defined types for this expression: BaseType[Variant1 | Variant2] then type_fragments would be BaseType, Variant1, Variant2

Return type:

None

Examples

>>> plugin.register_semantic_types(BaseType, Variant1, Variant2)
register_semantic_type_to_format(semantic_type, artifact_format=None, directory_format=None)[source]#

Connect a semantic type expression to a format. Deprecated

Permits an arbitrary type expression and expands it to all concrete variants which are then associated with the supplied directory_format.

As this does not support documentation or examples, it is recommended to use Plugin.register_artifact_class() instead, which takes a single concrete expression, but allows for additional specific information.

Parameters:

  • semantic_type (semantic type expression) – A semantic type expression which may include operators.

  • artifact_format (type) – Super deprecated

  • directory_format (subclass of DirectoryFormat) – A directory format which will define the /data/ directory of a stored artifact.

Return type:

None

register_artifact_class(semantic_type, directory_format, description=None, examples=None)[source]#

Register an artifact class which defines an Artifact

Parameters:

  • semantic_type (type expression) – A concrete type expression which will be the type of this artifact class.

  • directory_format (subclass of DirectoryFormat) – A directory format which will define the /data/ directory of a stored artifact.

  • description (str) – A description of what this artifact will represent.

  • examples (dict[str, callable]) – A dict of example name to usage example functions which take a single argument (the usage driver, a.k.a. use). Each function which will demonstrate importing this data when executed.

Return type:

None

Examples

>>> plugin.register_artifact_class(
...     semantic_type=BaseType[Variant1],
...     directory_format=CSVDirFormat,
...     description="This data represents something important.",
...     examples={
...         'example1': example_function_variant1,
...         'example2': example_function_variant2
...     }
... )

Action registration#

The following classes exist only on an instantiated Plugin object and are generally accessed via plugin.methods, plugin.visualizers, and plugin.pipelines. At this time, register_function is the only interesting method for a plugin developer. Otherwise these objects are essentially dictionaries to makes generating interfaces convenient.

class qiime2.plugin.plugin.PluginMethods(plugin)[source]#

Accessed via plugin.methods

register_function(function, inputs, parameters, outputs, name, description, input_descriptions=None, parameter_descriptions=None, output_descriptions=None, citations=None, deprecated=False, examples=None)[source]#

Register a method to the associated plugin.

Parameters:

  • function (callable) – A function which will be called when the user uses this method.

  • inputs (dict[str, type expression]) – A dictionary of function-parameter names to semantic type expressions. The keys of the dictionary must match the parameter names which are on the function. Collections and type variables are also permitted so long as they contain semantic types.

  • parameters (dict[str, type expression]) – A dictionary of function parameter names to primitive type expressions. The keys of the dictionary must match the parameter names which are on the function. Collections and type variables are also permitted so long as they contain primitive types.

  • outputs (dict[str, type expression]) – A dictionary of named outputs to concrete semantic types. The keys of the dictionary will become the parameter names for these outputs and must match the number of annotated outputs on the function. Collections and type variables are also permitted so long as they contain semantic types. (In older versions of QIIME 2 this was a list of tuples as dictionaries were not yet ordered.)

  • name (str) – A short description, ideally a human-oriented name or title.

  • description (str) – A longer description of the action.

  • input_descriptions (dict[str, str]) – A dictionary of input names (see inputs) to descriptions.

  • parameter_descriptions (dict[str, str]) – A dictionary of parameter names (see parameters) to descriptions.

  • output_descriptions (dict[str, str]) – A dictionary of output names (see outputs) to descriptions.

  • citations (CitationRecord or list of CitationRecord) – Citation(s) to associate with a result whenever this action is used. Can also use an entire Citations object.

  • deprecated (bool) – Whether this action is deprecated and should be migrated away from.

  • examples (dict[str, callable]) – A dict of example name to usage example functions which take a single argument (the usage driver, a.k.a. use). Each function will carry out some example situation for this action when executed.

Return type:

None

Examples

>>> from qiime2.plugin import Int
>>> plugin.methods.register_function(
...     function=my_method,
...     inputs={
...         'ints': IntSequence1,
...         'optional1': IntSequence1,
...         'optional2': IntSequence1 | IntSequence2
...     },
...     parameters={
...         'num1': Int,
...         'num2': Int
...     },
...     outputs={
...         'output': IntSequence1
...     },
...     name='My cool method',
...     description='It does something very clever and interesting.'
... )
class qiime2.plugin.plugin.PluginVisualizers(plugin)[source]#

Accessed via plugin.visualizers

register_function(function, inputs, parameters, name, description, input_descriptions=None, parameter_descriptions=None, citations=None, deprecated=False, examples=None)[source]#

Register a visualizer to the associated plugin.

Parameters:

  • function (callable) – A function which will be called when the user uses this method. This function receives an output_dir as the first argument.

  • inputs (dict[str, type expression]) – A dictionary of function-parameter names to semantic type expressions. The keys of the dictionary must match the parameter names which are on the function. Collections and type variables are also permitted so long as they contain semantic types.

  • parameters (dict[str, type expression]) – A dictionary of function parameter names to primitive type expressions. The keys of the dictionary must match the parameter names which are on the function. Collections and type variables are also permitted so long as they contain primitive types.

  • name (str) – A short description, ideally a human-oriented name or title.

  • description (str) – A longer description of the action.

  • input_descriptions (dict[str, str]) – A dictionary of input names (see inputs) to descriptions.

  • parameter_descriptions (dict[str, str]) – A dictionary of parameter names (see parameters) to descriptions.

  • citations (CitationRecord or list of CitationRecord) – Citation(s) to associate with a result whenever this action is used. Can also use an entire Citations object.

  • deprecated (bool) – Whether this action is deprecated and should be migrated away from.

  • examples (dict[str, callable]) – A dict of example name to usage example functions which take a single argument (the usage driver, a.k.a. use). Each function will carry out some example situation for this action when executed.

Notes

Unlike methods and pipelines, there are no registered outputs as every visualizer returns a single Visualization output.

Examples

>>> plugin.visualizers.register_function(
...     function=my_visualizer,
...     inputs={'ints': IntSequence1 | IntSequence2},
...     parameters={},
...     name='Visualize most common integers',
...     description='Produces a ranked list of integers.',
...     citations=[citations['witcombe2006sword']]
... )
class qiime2.plugin.plugin.PluginPipelines(plugin)[source]#

Accessed via plugin.pipelines

register_function(function, inputs, parameters, outputs, name, description, input_descriptions=None, parameter_descriptions=None, output_descriptions=None, citations=None, deprecated=False, examples=None)[source]#

Register a pipeline to the associated plugin.

Parameters:

  • function (callable) – A function which will be called when the user uses this method. This function receives a Context object ctx as its first argument.

  • inputs (dict[str, type expression]) – A dictionary of function-parameter names to semantic type expressions. The keys of the dictionary must match the parameter names which are on the function. Collections and type variables are also permitted so long as they contain semantic types.

  • parameters (dict[str, type expression]) – A dictionary of function parameter names to primitive type expressions. The keys of the dictionary must match the parameter names which are on the function. Collections and type variables are also permitted so long as they contain primitive types.

  • outputs (dict[str, type expression]) – A dictionary of named outputs to concrete semantic types. The keys of the dictionary will become the parameter names for these outputs and must match the number of annotated outputs on the function. Collections and type variables are also permitted so long as they contain semantic types. (In older versions of QIIME 2 this was a list of tuples as dictionaries were not yet ordered.)

  • name (str) – A short description, ideally a human-oriented name or title.

  • description (str) – A longer description of the action.

  • input_descriptions (dict[str, str]) – A dictionary of input names (see inputs) to descriptions.

  • parameter_descriptions (dict[str, str]) – A dictionary of parameter names (see parameters) to descriptions.

  • output_descriptions (dict[str, str]) – A dictionary of output names (see outputs) to descriptions.

  • citations (CitationRecord or list of CitationRecord) – Citation(s) to associate with a result whenever this action is used. Can also use an entire Citations object.

  • deprecated (bool) – Whether this action is deprecated and should be migrated away from.

  • examples (dict[str, callable]) – A dict of example name to usage example functions which take a single argument (the usage driver, a.k.a. use). Each function will carry out some example situation for this action when executed.

Examples

>>> from qiime2.plugin import Collection
>>> plugin.pipelines.register_function(
...     function=my_pipeline,
...     inputs={'ints': Collection[IntSequence1]},
...     parameters={},
...     outputs={'output': Collection[IntSequence1]},
...     name='Do thing multiple times',
...     description='Takes a collection and returns a better one'
... )