Interface Development & The Artifact API (SDK)

QIIME 2 supports automatically-generated interfaces. For examples of this, check out the Artifact API and q2cli, the canonical examples of QIIME 2 interfaces.


class qiime2.sdk.Result

Base class for QIIME 2 result classes (Artifact and Visualization).

This class is not intended to be instantiated. Instead, it acts as a public factory and namespace for interacting with Artifacts and Visualizations in a generic way. It also acts as a base class for code reuse and provides an API shared by Artifact and Visualization.

property citations
export_data(output_dir)
extension = None
classmethod extract(filepath, output_dir)

Unzip contents of Artifacts and Visualizations.

property format
classmethod load(filepath)

Factory for loading Artifacts and Visualizations.

classmethod peek(filepath)
save(filepath)
property type
property uuid
validate(level=NotImplemented)
class qiime2.sdk.Results

Tuple class representing the named results of an Action.

Provides an interface similar to a namedtuple type (e.g. fields are accessible as attributes).

Users should not need to instantiate this class directly.

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

class qiime2.sdk.Artifact
property citations
export_data(output_dir)
extension = '.qza'
classmethod extract(filepath, output_dir)

Unzip contents of Artifacts and Visualizations.

property format
has_metadata()

Checks for metadata within an artifact

Returns

True if the artifact has metadata (i.e. can be viewed as qiime2.Metadata), False otherwise.

Return type

bool

classmethod import_data(type, view, view_type=None)
classmethod load(filepath)

Factory for loading Artifacts and Visualizations.

classmethod peek(filepath)
save(filepath)
property type
property uuid
validate(level='max')

Validates the data contents of an artifact

Raises

ValidationError – If the artifact is invalid at the specified level of validation.

view(view_type)
class qiime2.sdk.Visualization
property citations
export_data(output_dir)
extension = '.qzv'
classmethod extract(filepath, output_dir)

Unzip contents of Artifacts and Visualizations.

property format
get_index_paths(relative=True)
classmethod load(filepath)

Factory for loading Artifacts and Visualizations.

classmethod peek(filepath)
save(filepath)
property type
property uuid
validate(level=NotImplemented)
class qiime2.sdk.Action

QIIME 2 Action

asynchronous
get_import_path()
property source

The source code for the action’s callable.

Returns

The source code of this action’s callable formatted as Markdown text.

Return type

str

type = 'action'
class qiime2.sdk.Method

QIIME 2 Method

get_import_path()
property source

The source code for the action’s callable.

Returns

The source code of this action’s callable formatted as Markdown text.

Return type

str

type = 'method'
class qiime2.sdk.Visualizer

QIIME 2 Visualizer

get_import_path()
property source

The source code for the action’s callable.

Returns

The source code of this action’s callable formatted as Markdown text.

Return type

str

type = 'visualizer'
class qiime2.sdk.Pipeline

QIIME 2 Pipeline

get_import_path()
property source

The source code for the action’s callable.

Returns

The source code of this action’s callable formatted as Markdown text.

Return type

str

type = 'pipeline'
class qiime2.sdk.PluginManager
entry_point_group = 'qiime2.plugins'
get_directory_format(semantic_type)
property importable_formats

Return formats that are importable.

A format is importable in a QIIME 2 deployment if it can be transformed into at least one of the canonical semantic type formats.

property importable_types

Return set of concrete semantic types that are importable.

A concrete semantic type is importable if it has an associated directory format.

classmethod iter_entry_points()

Yield QIIME 2 plugin entry points.

If the QIIMETEST environment variable is set, only the framework testing plugin entry point (dummy-plugin) will be yielded. Otherwise, all available plugin entry points (excluding dummy-plugin) will be yielded.

qiime2.sdk.parse_type(string, expect=None)

Convert a string into a type expression

Parameters
  • string (str) – The string type expression to convert into a TypeExpression

  • expect ({'semantic', 'primitive', 'visualization'}, optional) – Will raise a TypeError if the resulting TypeExpression is not a member of expect.

Returns

Return type

type expression

qiime2.sdk.parse_format(format_str)
qiime2.sdk.type_from_ast(ast, scope=None)

Convert a type ast (from .to_ast()) to a type expression.

Parameters
  • ast (json compatible object) – The abstract syntax tree produced by to_ast on a type.

  • scope (dict) – A dictionary to use between multiple calls to share scope between different types. This allows type variables from the same type map to be constructed from an equivalent type map. Scope should be shared within a given call signature, but not between call signatures.

Returns

Return type

type expression

class qiime2.sdk.Context(parent=None)
get_action(plugin: str, action: str)

Return a function matching the callable API of an action.

This function is aware of the pipeline context and manages its own cleanup as appropriate.

make_artifact(type, view, view_type=None)

Return a new artifact from a given view.

This artifact is automatically tracked and cleaned by the pipeline context.

class qiime2.sdk.Citations
clear() → None. Remove all items from od.
copy() → a shallow copy of od
fromkeys(S[, v]) → New ordered dictionary with keys from S.

If not specified, the value defaults to None.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.
items() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D's keys
classmethod load(path, package=None)
move_to_end()

Move an existing element to the end (or beginning if last==False).

Raises KeyError if the element does not exist. When last=True, acts like a fast version of self[key]=self.pop(key).

pop(k[, d]) → v, remove specified key and return the corresponding

value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem()

Remove and return a (key, value) pair from the dictionary.

Pairs are returned in LIFO order if last is true or FIFO order if false.

save(f)
setdefault(k[, d]) → od.get(k,d), also set od[k]=d if k not in od
update([E, ]**F) → None. Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values