Usage API (for example authors)

This page outlines elements of the Usage API which are used by example authors (and overriden by interface drivers) to describe some example situation in the framework for documentation, testing, or interface generating purposes.

Initializers

These methods prepare some data for use in an example.

Usage.init_artifact(name: str, factory: Callable[[], qiime2.sdk.result.Artifact]) qiime2.sdk.usage.UsageVariable

Communicate that an artifact will be needed.

Driver implementations may use this to intialize data for an example.

Parameters
  • name (str) – The cannonical name of the variable to be returned.

  • factory (Callable which returns qiime2.sdk.Artifact) – A function which takes no parameters, and returns an artifact. This function may do anything internally to create the artifact.

Returns

This particular return class can be changed by a driver which overrides usage_variable().

Return type

UsageVariable

Examples

>>> # A factory which will be used in the example to generate data.
>>> def factory():
...     import qiime2
...     # This type is only available during testing.
...     # A real example would use a real type.
...     a = qiime2.Artifact.import_data('IntSequence1', [1, 2, 3])
...     return a
...
>>> my_artifact = use.init_artifact('my_artifact', factory)
>>> my_artifact
<ExecutionUsageVariable name='my_artifact', var_type='artifact'>
Usage.init_metadata(name: str, factory: Callable[[], qiime2.metadata.metadata.Metadata]) qiime2.sdk.usage.UsageVariable

Communicate that metadata will be needed.

Driver implementations may use this to intialize data for an example.

Parameters
  • name (str) – The cannonical name of the variable to be returned.

  • factory (Callable which returns qiime2.Metadata) – A function which takes no parameters, and returns metadata. This function may do anything internally to create the metadata.

Returns

Variable of type ‘metadata’.

Return type

UsageVariable

Examples

>>> # A factory which will be used in the example to generate data.
>>> def factory():
...     import qiime2
...     import pandas as pd
...     df = pd.DataFrame({'a':[1, 2, 3]}, index=['a', 'b', 'c'])
...     df.index.name = 'id'
...     md = qiime2.Metadata(df)
...     return md
...
>>> my_metadata = use.init_metadata('my_metadata', factory)
>>> my_metadata
<ExecutionUsageVariable name='my_metadata', var_type='metadata'>
Usage.init_format(name: str, factory: Callable[[], qiime2.core.format.FormatBase], ext: Optional[str] = None) qiime2.sdk.usage.UsageVariable

Communicate that a file/directory format will be needed.

Driver implementations may use this to intialize data for an example.

Parameters
  • name (str) – The cannonical name of the variable to be returned.

  • factory (Callable which returns a file or directory format.) – A function which takes no parameters, and returns a format. This function may do anything internally to create the format.

  • ext (str) – The extension to prefer if the format is preserved on disk.

Returns

Variable of type ‘format’.

Return type

UsageVariable

Examples

>>> # A factory which will be used in the example to generate data.
>>> def factory():
...     from qiime2.core.testing.format import IntSequenceFormat
...     from qiime2.plugin.util import transform
...     ff = transform([1, 2, 3], to_type=IntSequenceFormat)
...
...     ff.validate()  # good practice
...     return ff
...
>>> my_ints = use.init_format('my_ints', factory, ext='.hello')
>>> my_ints
<ExecutionUsageVariable name='my_ints', var_type='format'>

Importing

These methods demonstrate how to import an artifact.

Usage.import_from_format(name: str, semantic_type: str, variable: qiime2.sdk.usage.UsageVariable, view_type: Optional[qiime2.core.format.FormatBase] = None) qiime2.sdk.usage.UsageVariable

Communicate that an import should be done.

Parameters
  • name (str) – The name of the resulting variable.

  • semantic_type (str) – The semantic type to import as.

  • variable (UsageVariable) – A variable of type ‘format’ which possesses a factory to materialize the actual data to be imported.

  • view_type (format or str) – The view type to import as, in the event it is different from the default.

Returns

Variable of type ‘artifact’.

Return type

UsageVariable

Examples

>>> # A factory which will be used in the example to generate data.
>>> def factory():
...     from qiime2.core.testing.format import IntSequenceFormat
...     from qiime2.plugin.util import transform
...     ff = transform([1, 2, 3], to_type=IntSequenceFormat)
...
...     ff.validate()  # good practice
...     return ff
...
>>> to_import = use.init_format('to_import', factory, ext='.hello')
>>> to_import
<ExecutionUsageVariable name='to_import', var_type='format'>
>>> ints = use.import_from_format('ints',
...                               semantic_type='IntSequence1',
...                               variable=to_import,
...                               view_type='IntSequenceFormat')
>>> ints
<ExecutionUsageVariable name='ints', var_type='artifact'>

See also

init_format

Metadata

These methods demonstrate how to manipulate metadata.

Usage.get_metadata_column(name: str, column_name: str, variable: qiime2.sdk.usage.UsageVariable) qiime2.sdk.usage.UsageVariable

Communicate that a column should be retrieved.

Parameters
  • name (str) – The name of the resulting variable.

  • column_name (str) – The column to retrieve.

  • variable (UsageVariable) – The metadata to retrieve the column from. Must be a variable of type ‘metadata’.

Returns

Variable of type ‘column’.

Return type

UsageVariable

Raises

AssertionError – If the variable is not of type ‘metadata’.

Examples

>>> def factory():
...     import qiime2
...     import pandas as pd
...     df = pd.DataFrame({'column_a':[1, 2, 3]},
...                       index=['a', 'b', 'c'])
...     df.index.name = 'id'
...     return qiime2.Metadata(df)
...
>>> md_for_column = use.init_metadata('md_for_column', factory)
>>> md_for_column
<ExecutionUsageVariable name='md_for_column', var_type='metadata'>
>>> my_column = use.get_metadata_column('my_column', 'column_a',
...                                     md_for_column)
>>> my_column
<ExecutionUsageVariable name='my_column', var_type='column'>

See also

init_metadata

Usage.view_as_metadata(name: str, variable: qiime2.sdk.usage.UsageVariable) qiime2.sdk.usage.UsageVariable

Communicate that an artifact should be views as metadata.

Parameters
  • name (str) – The name of the resulting variable.

  • variable (UsageVariable) – The artifact to convert to metadata. Must be a variable of type ‘artifact’.

Returns

Variable of type ‘metadata’.

Return type

UsageVariable

Raises

AssertionError – If the variable is not of type ‘artifact’.

Examples

>>> artifact_for_md, = use.action(
...     use.UsageAction('dummy_plugin', 'params_only_method'),
...     use.UsageInputs(name='c', age=100),
...     use.UsageOutputNames(out='artifact_for_md'))
>>> artifact_for_md
<ExecutionUsageVariable name='artifact_for_md', var_type='artifact'>
>>> metadata = use.view_as_metadata('metadata', artifact_for_md)
>>> metadata
<ExecutionUsageVariable name='metadata', var_type='metadata'>
Usage.merge_metadata(name: str, *variables: qiime2.sdk.usage.UsageVariable) qiime2.sdk.usage.UsageVariable

Communicate that these metadata should be merged.

Parameters
  • name (str) – The name of the resulting variable.

  • *variables (UsageVariable) – Multiple variables of type ‘metadata’ to merge.

Returns

Variable of type ‘metadata’.

Return type

UsageVariable

Raises

AssertionError – If a variable is not of type ‘metadata’.

Examples

>>> def factory1():
...     import qiime2
...     import pandas as pd
...     df = pd.DataFrame({'a':[0]}, index=['0'])
...     df.index.name = 'id'
...     md = qiime2.Metadata(df)
...     return md
...
>>> def factory2():
...     import qiime2
...     import pandas as pd
...     df = pd.DataFrame({'b':[10]}, index=['0'])
...     df.index.name = 'id'
...     md = qiime2.Metadata(df)
...     return md
...
>>> some_artifact, = use.action(
...     use.UsageAction('dummy_plugin', 'params_only_method'),
...     use.UsageInputs(name='c', age=100),
...     use.UsageOutputNames(out='some_artifact'))
...
>>> md1 = use.init_metadata('md1', factory1)
>>> md2 = use.init_metadata('md2', factory2)
>>> md3 = use.view_as_metadata('md3', some_artifact)
>>> merged = use.merge_metadata('merged', md1, md2, md3)
>>> merged
<ExecutionUsageVariable name='merged', var_type='metadata'>

Annotations

These methods do not return anything, but may be displayed in other ways.

Usage.comment(text: str)

Communicate that a comment should be made.

Default implementation is to do nothing.

Parameters

text (str) – The inspired commentary.

Examples

>>> use.comment("The thing is, they always try to walk it in...")
Usage.help(action: qiime2.sdk.usage.UsageAction)

Communicate that help text should be displayed.

Default implementation is to do nothing.

Parameters

action (UsageAction) – The particular action that should have help-text rendered.

Examples

>>> use.help(use.UsageAction('dummpy_plugin', 'split_ints'))
Usage.peek(variable: qiime2.sdk.usage.UsageVariable)

Communicate that an artifact should be peeked at.

Default implementation is to do nothing.

Parameters

variable (UsageVariable) – A variable of ‘artifact’ type which should be peeked.

Raises

AssertionError – If the variable is not of type ‘artifact’.

Examples

>>> def factory():
...     import qiime2
...     return qiime2.Artifact.import_data('IntSequence1', [1, 2, 3])
...
>>> a_boo = use.init_artifact('a_boo', factory)
>>> use.peek(a_boo)

Actions

These methods invoke a plugin’s action.

Usage.action(action: qiime2.sdk.usage.UsageAction, inputs: qiime2.sdk.usage.UsageInputs, outputs: qiime2.sdk.usage.UsageOutputNames) qiime2.sdk.usage.UsageOutputs

Communicate that some action should be performed.

Parameters
  • action (UsageAction) – The action to perform.

  • inputs (UsageInputs) – The inputs to provide. These are a map of parameter names to arguments. Arguments may be primitive literals, or variables.

  • outputs (UsageOutputNames) – Defines what to name each output variable. The keys much match the action’s output signature.

Returns

A wrapper around the usual qiime2.sdk.Results object. Unpacking this output can be seen in the examples below.

Return type

UsageOutputs

Examples

>>> results = use.action(
...     use.UsageAction(plugin_id='dummy_plugin',
...                     action_id='params_only_method'),
...     use.UsageInputs(name='foo', age=42),
...     use.UsageOutputNames(out='bar')
... )
>>> results
UsageOutputs (name = value)
--------------------------------------------------------------
out = <ExecutionUsageVariable name='bar', var_type='artifact'>
>>> # "out" happens to be the name of this output, it isn't a general
>>> # name for all results.
>>> results.out
<ExecutionUsageVariable name='bar', var_type='artifact'>
>>> # unpack as an iterator
>>> bar, = results
>>> bar
<ExecutionUsageVariable name='bar', var_type='artifact'>
>>> bar is results.out
True

Parameter Objects for Usage.action()

These three classes define a deferred action that should be taken by some interface driver.

class qiime2.sdk.usage.UsageAction(plugin_id: str, action_id: str)

An object which represents a deferred lookup for a QIIME 2 action.

One of three “argument objects” used by Usage.action(). The other two are UsageInputs and UsageOutputNames.

__init__(plugin_id: str, action_id: str)

Constructor for UsageAction.

The parameters should identify an existing plugin and action of that plugin.

Important

There should be an existing plugin manager by the time this object is created, or an error will be raised. Typically instantiation happens by executing an example, so this will generally be true.

Parameters
  • plugin_id (str) – The (typically under-scored) name of a plugin, e.g. “my_plugin”.

  • action_id (str) – The (typically under-scored) name of an action, e.g. “my_action”.

Raises

qiime2.sdk.UninitializedPluginManagerError – If there is not an existing plugin manager to define the available plugins.

Examples

>>> results = use.action(
...     use.UsageAction(plugin_id='dummy_plugin',
...                     action_id='params_only_method'),
...     use.UsageInputs(name='foo', age=42),
...     use.UsageOutputNames(out='bar1')
... )
>>> results.out
<ExecutionUsageVariable name='bar1', var_type='artifact'>
class qiime2.sdk.usage.UsageInputs(**kwargs)

A dict-like mapping of parameters to arguments for invoking an action.

One of three “argument objects” used by Usage.action(). The other two are UsageAction and UsageOutputNames.

Parameters should match the signature of the associated action, and arguments may be UsageVariable s or primitive values.

__init__(**kwargs)

Constructor for UsageInputs.

Parameters

**kwargs (primitive or UsageVariable) – The keys used should match the signature of the action. The values should be valid arguments of the action or variables of such arguments.

Examples

>>> results = use.action(
...     use.UsageAction(plugin_id='dummy_plugin',
...                     action_id='params_only_method'),
...     use.UsageInputs(name='foo', age=42),
...     use.UsageOutputNames(out='bar2')
... )
>>> results.out
<ExecutionUsageVariable name='bar2', var_type='artifact'>
class qiime2.sdk.usage.UsageOutputNames(**kwargs)

A dict-like mapping of action outputs to desired names.

One of three “argument objects” used by Usage.action(). The other two are UsageAction and UsageInputs.

All names must be strings.

Note

The order defined by this object will dictate the order of the variables returned by Usage.action().

__init__(**kwargs)

Constructor for UsageOutputNames.

Parameters

**kwargs (str) – The name of the resulting variables to be returned by Usage.action().

Raises

TypeError – If the values provided are not strings.

Examples

>>> results = use.action(
...     use.UsageAction(plugin_id='dummy_plugin',
...                     action_id='params_only_method'),
...     use.UsageInputs(name='foo', age=42),
...     use.UsageOutputNames(out='bar3')
... )
>>> results.out
<ExecutionUsageVariable name='bar3', var_type='artifact'>

Results and Assertions

The outputs of qiime2.sdk.usage.Usage.action() are stored in a vanity class qiime2.sdk.usage.UsageOutputs which contain qiime2.sdk.usage.UsageVariable’s. Assertions are preformed on these output variables.

class qiime2.sdk.usage.UsageOutputs(fields, values)

A vanity class over qiime2.sdk.Results.

Returned by Usage.action() with order defined by UsageOutputNames.

class qiime2.sdk.usage.UsageVariable(name: str, factory: Callable[[], Any], var_type: Literal['artifact', 'visualization', 'metadata', 'column', 'format'], usage: qiime2.sdk.usage.Usage)

A variable which represents some QIIME 2 generate-able value.

These should not be used to represent primitive values such as strings, numbers, booleans, or lists/sets thereof.

assert_has_line_matching(path: str, expression: str)

Communicate that the result of this variable should match a regex.

The default implementation is to do nothing.

Parameters
  • path (str) – The relative path in a result’s /data/ directory to check.

  • expression (str) – The regular expression to evaluate for a line within path.

Note

Should not be called on non-artifact variables.

Examples

>>> bar, = use.action(
...     use.UsageAction(plugin_id='dummy_plugin',
...                     action_id='params_only_method'),
...     use.UsageInputs(name='foo', age=42),
...     use.UsageOutputNames(out='bar4')
... )
>>> bar.assert_has_line_matching('mapping.tsv', r'foo\s42')
assert_output_type(semantic_type: str)

Communicate that this variable should have a given semantic type.

The default implementation is to do nothing.

Parameters

semantic_type (QIIME 2 Semantic Type or str) – The semantic type to match.

Note

Should not be called on non-artifact variables.

Examples

>>> bar, = use.action(
...     use.UsageAction(plugin_id='dummy_plugin',
...                     action_id='params_only_method'),
...     use.UsageInputs(name='foo', age=42),
...     use.UsageOutputNames(out='bar5')
... )
>>> bar.assert_output_type('Mapping')