Usage Examples

Usage Examples#

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, factory)[source]#

Communicate that an artifact will be needed.

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

Parameters:

name (str) – The canonical 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_artifact_from_url(name, url)[source]#

Obtain an artifact from a url.

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

Parameters:

name (str) – The canonical name of the variable to be returned.
url (str) – The url of the Artifact that should be downloaded for the example. If a QIIME 2 epoch (e.g., 2022.11) is part of the URL, as might be the case if obtaining an Artifact from docs.qiime2.org, it can be templated in by including {qiime2.__release__} in an F-string defining the URL.

Returns:

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

Return type:

UsageVariable

Usage.init_artifact_collection(name, factory)[source]#

Communicate that a result collection containing artifacts will be needed.

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

Parameters:

name (str) – The canonical name of the variable to be returned.
factory (Callable which returns qiime2.sdk.ResultCollection) – A function which takes no parameters, and returns a result collection that contains artifacts. This function may do anything internally to create the result collection.

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.ResultCollection(
...         {'Foo': qiime2.Artifact.import_data('IntSequence1', [1, 2, 3]),
...          'Bar': qiime2.Artifact.import_data('IntSequence1', [4, 5, 6])})
...     return a
...
>>> int_seq_collection = use.init_artifact_collection('int_seq_collection', factory)
>>> int_seq_collection
<ExecutionUsageVariable name='int_seq_collection', var_type='artifact_collection'>

Usage.init_metadata(name, factory)[source]#

Communicate that metadata will be needed.

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

Parameters:

name (str) – The canonical 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_metadata_from_url(name, url)[source]#

Obtain metadata from a url.

Driver implementations may use this to intialize example metadata.

Parameters:

name (str) – The canonical name of the variable to be returned.
url (str) – The url of the Artifact that should be downloaded for the example. If a QIIME 2 epoch (e.g., 2022.11) is part of the URL, as might be the case if obtaining an Artifact from docs.qiime2.org, it can be templated in by including {qiime2.__release__} in an F-string defining the URL.

Returns:

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

Return type:

UsageVariable

Examples

>>> import qiime2
>>> url = ('https://data.qiime2.org/usage-examples/moving-pictures/'
...        'sample-metadata.tsv')
>>> print(url)
https://data.qiime2.org/usage...
>>> md = use.init_metadata_from_url('md', url)
>>> md
<ExecutionUsageVariable name='md', var_type='metadata'>

Usage.init_format(name, factory, ext=None)[source]#

Communicate that a file/directory format will be needed.

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

Parameters:

name (str) – The canonical 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, semantic_type, variable, view_type=None)[source]#

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

Collections#

These methods demonstrate how to manipulate collections.

Usage.construct_artifact_collection(name, members)[source]#

Return a UsageVariable of type artifact_collection given a list or dict of its members.

Parameters:

name (str) – The name of the resulting variable.
members (list or dict) – The desired members of the ResultCollection.

Returns:

Of type artifact_collection.

Return type:

UsageVariable

Examples

>>> mapping_1, = use.action(
...     use.UsageAction('dummy_plugin', 'params_only_method'),
...     use.UsageInputs(name='c', age=100),
...     use.UsageOutputNames(out='mapping_1')
... )
>>> mapping_1
<ExecutionUsageVariable name='mapping_1', var_type='artifact'>
>>> collection_1 = use.construct_artifact_collection(
...     'collection_1', {'a': mapping_1, 'b': mapping_1}
... )
>>> collection_1
<ExecutionUsageVariable name='collection_1', var_type='artifact_collection'>

Usage.get_artifact_collection_member(name, variable, key)[source]#

Accesses and returns a member of a ResultCollection as a UsageVariable.

Parameters:

name (str) – The name of the resulting variable.
variable (UsageVariable) – The UsageVariable of type artifact_collection from which to access the desired member.
key (str) – The key of the desired member in the ResultCollection.

Returns:

Of type artifact.

Return type:

UsageVariable

Examples

>>> mapping_2, = use.action(
...     use.UsageAction('dummy_plugin', 'params_only_method'),
...     use.UsageInputs(name='c', age=100),
...     use.UsageOutputNames(out='mapping_2')
... )
>>> mapping_2
<ExecutionUsageVariable name='mapping_2', var_type='artifact'>
>>> collection_2 = use.construct_artifact_collection(
...     'collection_2', {'a': mapping_2, 'b': mapping_2}
... )
>>> collection_2
<ExecutionUsageVariable name='collection_2', var_type='artifact_collection'>
>>> first_member = use.get_artifact_collection_member(
...     'first_member', collection_2, 'a'
... )
>>> first_member
<ExecutionUsageVariable name='first_member', var_type='artifact'>

Metadata#

These methods demonstrate how to manipulate metadata.

Usage.get_metadata_column(name, column_name, variable)[source]#

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, variable)[source]#

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'>

See also

init_artifact, get_metadata_column

Usage.merge_metadata(name, *variables)[source]#

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'>

See also

init_metadata, view_as_metadata

Annotations#

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

Usage.comment(text)[source]#

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)[source]#

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('dummy_plugin', 'split_ints'))

Usage.peek(variable)[source]#

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, inputs, outputs)[source]#

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.

Usage.UsageAction: Type[UsageAction] = <class 'qiime2.sdk.usage.UsageAction'>[source]#

class qiime2.sdk.usage.UsageAction(plugin_id, action_id)[source]#

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.

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'>

Usage.UsageInputs: Type[UsageInputs] = <class 'qiime2.sdk.usage.UsageInputs'>[source]#

class qiime2.sdk.usage.UsageInputs(**kwargs)[source]#

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.

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'>

Usage.UsageOutputNames: Type[UsageOutputNames] = <class 'qiime2.sdk.usage.UsageOutputNames'>[source]#

class qiime2.sdk.usage.UsageOutputNames(**kwargs)[source]#

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().

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 Usage.action are stored in a vanity class UsageOutputs which contain UsageVariables. Assertions are performed on these output variables.

class qiime2.sdk.usage.UsageOutputs(fields, values)[source]#

A vanity class over qiime2.sdk.Results.

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

class qiime2.sdk.usage.UsageVariable(name, factory, var_type, usage)[source]#

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.

UsageVariable.assert_has_line_matching(path, expression, key=None)[source]#

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.
key (str) – The key to match against a given semantic type if the output is a ResultCollection.

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')
...
>>> # 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.ResultCollection(
...         {'Foo': qiime2.Artifact.import_data('SingleInt', 1),
...          'Bar': qiime2.Artifact.import_data('SingleInt', 2)})
...     return a
...
>>> int_collection = use.init_artifact_collection('int_collection6', factory)
>>> bar, = use.action(
...     use.UsageAction(plugin_id='dummy_plugin',
...                     action_id='dict_of_ints'),
...     use.UsageInputs(ints=int_collection),
...     use.UsageOutputNames(output='bar5')
... )
>>> bar.assert_has_line_matching('file1.txt', r'1', 'Foo')
>>> bar.assert_has_line_matching('file1.txt', r'2', 'Bar')
>>> bar.assert_has_line_matching('file2.txt', r'1', 'Foo')
>>> bar.assert_has_line_matching('file2.txt', r'2', 'Bar')

UsageVariable.assert_output_type(semantic_type, key=None)[source]#

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.
key (str) – The key to match against a given semantic type if the output is a ResultCollection.

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='bar6')
... )
>>> bar.assert_output_type('Mapping')
...
>>> # 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.ResultCollection(
...         {'Foo': qiime2.Artifact.import_data('SingleInt', 1),
...          'Bar': qiime2.Artifact.import_data('SingleInt', 2)})
...     return a
...
>>> int_collection = use.init_artifact_collection('int_collection7', factory)
>>> bar, = use.action(
...     use.UsageAction(plugin_id='dummy_plugin',
...                     action_id='dict_of_ints'),
...     use.UsageInputs(ints=int_collection),
...     use.UsageOutputNames(output='bar7')
... )
>>> bar.assert_output_type(semantic_type='SingleInt', key='Foo')
...

Usage Examples

Contents

Usage Examples#

Initializers#

Importing#

Collections#

Metadata#

Annotations#

Actions#

Parameter Objects for Usage.action#

Results and Assertions#

Parameter Objects for `Usage.action`#