Usage API

The Usage API provides an interface-agnostic way for QIIME 2 plugin developers to define examples of how to use their plugin’s actions. This enables the programmatic generation of examples for all QIIME 2 interfaces, eliminating the need to maintain specific examples for multiple interfaces.


class qiime2.sdk.usage.Usage

Usage is the base class for Usage driver implementations and should be customized for the interface or implementation.

class UsageAction(*, plugin_id: str, action_id: str)
Parameters
  • plugin_id (str) – Plugin ID.

  • action_id (str) – Action ID.

get_action()Tuple[Union[sdk.Method, sdk.Pipeline], Type[core.PipelineSignature]]

Get this example’s action and signature.

Returns

  • action_f (QIIME 2 Method, Visualizer, or Pipeline) – The plugin action.

  • action_f.signature (QIIME 2 Method, Visualizer, or Pipeline Signature) – The method signature for the plugin action.

validate(inputs: qiime2.sdk.usage.UsageInputs, outputs: qiime2.sdk.usage.UsageOutputNames)None

Ensure that all required inputs and outputs are declared and reference appropriate scope records, if necessary.

Parameters
class UsageInputs(**kwargs: Any)

A convenience object for assisting with construction of input options and performing signature validation.

Parameters

kwargs (Example inputs) – Inputs to be passed in to Usage.action.

build_opts(signature: Type[core.PipelineSignature], scope: Scope)dict

Build a dictionary mapping example ScopeRecord``s and primitives to action inputs and parameters, respectively. Values are derived from either an input's ``ScopeRecord (ScopeRecord.value), or the value a keyword argument passed into the UsageInputs constructor.

Parameters
  • signature (QIIME 2 Method, Visualizer, or Pipeline Signature) – The plugin action’s signature.

  • scope (Scope) – A Usage example’s current scope.

Returns

Input identifiers and their example values.

Return type

dict

validate(signature: Type[core.PipelineSignature])None

Ensure that all required inputs are accounted for and that there are no unnecessary or extra parameters provided.

Parameters

signature (QIIME 2 Method, Visualizer, or Pipeline Signature) – The plugin action’s signature.

Raises

ValueError – If there are missing or extra inputs or parameters.

class UsageOutputNames(**kwargs: str)
Parameters

kwargs (str) – A mapping between the Action’s output name and the desired scope record identifier in which to “store” the results.

build_opts(action_signature: Type[core.PipelineSignature], scope: Scope)dict

Build a dictionary mapping action output identifiers to example output value.

Parameters
  • action_signature (QIIME 2 Method, Visualizer, or Pipeline Signature) – The plugin action’s signature.

  • scope (Scope) – A Usage example’s current scope.

Returns

Output identifiers and their example values.

Return type

dict

get(key)str

Get an example output’s identifier.

Returns

The identifier for an example output.

Return type

str

validate(signature: Type[core.PipelineSignature])None

Ensure that all required outputs are accounted for and that there are no unnecessary or extra outputs provided.

Parameters

signature – Action signature.

Raises

ValueError – If the example has missing or extra outputs as per the action signature.

validate_computed(computed_outputs: Dict[str, Union[qiime2.sdk.result.Artifact, qiime2.sdk.result.Visualization, qiime2.metadata.metadata.Metadata]])None

Check that outputs are still valid after being processed by a Usage driver’s _action_ method.

Parameters

computed_outputs (dict of outputs) – Outputs returned by the Usage driver’s _action_ method.

Raises

ValueError – If there are missing or extra outputs as per the action signature.

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

This method is a proxy for invoking a QIIME 2 Action. Whether or not the Action is actually invoked is dependent on the driver executing the example.

Parameters
  • action (UsageAction) – Specifies the Plugin and Action for a Usage example.

  • inputs (UsageInputs) – Specifies the inputs to an Action for a Usage example.

  • outputs (UsageOutputNames) – Species the outputs of an Action for a Usage example.

Examples

qiime2.core.testing.examples : Usage examples

get_metadata_column(column_name: str, record: qiime2.sdk.usage.ScopeRecord)qiime2.sdk.usage.ScopeRecord

Get a Metadata column from previously initialized example Metadata.

Parameters
  • column_name (str) – The name of a column in example Metadata.

  • record (ScopeRecord) – The record associated with example Metadata.

Returns

record – A new scope record for example Metadata column column_name.

Return type

ScopeRecord

get_result(ref: str)qiime2.sdk.usage.ScopeRecord

Get the record for a Usage example output. This is a convenience method used to access records generated after running Usage.action.

Parameters

ref (str) – Output identifier.

Raises
  • KeyError – If ref is not associated with a record generated by Usage.action.

  • TypeError – If the source type is not an Action.

init_data(ref: str, factory: Callable[qiime2.sdk.result.Artifact])qiime2.sdk.usage.ScopeRecord

Initialize example Artifact data from a factory. Whether or not the example data is actually created is dependent on the driver executing the example.

Parameters
  • ref (str) – Unique identifier for example data.

  • factory (callable) – A factory that returns an example Artifact.

Returns

record – A record with information about example data.

Return type

ScopeRecord

init_data_collection(ref: str, collection_type: Union[list, set], *records: qiime2.sdk.usage.ScopeRecord)qiime2.sdk.usage.ScopeRecord

Initialize a collection of data for a Usage example.

Parameters
  • ref (str) – Unique identifier for example data collection.

  • collection_type (list or set) – The type of collection required by an action.

  • records (ScopeRecords belonging to the collection) – The records associated with data to be initialized in the collection.

Returns

record – A record with information about an example of collection data.

Return type

ScopeRecord

init_metadata(ref: str, factory: Callable[qiime2.metadata.metadata.Metadata])qiime2.sdk.usage.ScopeRecord

Initialize Metadata for a Usage example. Whether or not the example metadata is actually created is dependent on the driver executing the example.

Parameters
  • ref (str) – Unique identifier for example metadata.

  • factory (callable) – A factory that returns example Metadata.

Returns

record – A record with information about example Metadata.

Return type

ScopeRecord

merge_metadata(ref: str, *records: List[qiime2.sdk.usage.ScopeRecord])qiime2.sdk.usage.ScopeRecord

Merge previously initialized example Metadata.

Parameters
  • ref (str) – Unique identifier for merged Metadata.

  • records (ScopeRecords) – Records for the example Metadata to be merged.

Returns

record – A new record with information about the merged example Metadata.

Return type

ScopeRecord