Home » API Reference »

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.Action

QIIME 2 Action

asynchronous

get_import_path(include_self=True)

parallel

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

result()

Noop to provide standardized interface with ProxyResult.

save(filepath, ext=None)

Save to a file.

Parameters:

• filepath (str) – Path to save file at.

• extension (str) – Preferred file extension (.qza, .qzv, .txt, etc). If no preferred extension input is included, Artifact extension will default to .qza and Visualization extension will default to .qzv. Including a period in the extension is optional, and any additional periods delimiting the filepath and the extension will be reduced to a single period.

Returns:

Filepath and extension (if provided) that the file was saved to.

Return type:

str

See also

load

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.Citations

clear() → None.  Remove all items from od.

copy() → a shallow copy of od

fromkeys(value=None)

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

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(key, last=True)

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

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(last=True)

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(key, default=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

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

class qiime2.sdk.Context(parent=None, parallel=False)

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.

exception qiime2.sdk.ImplementationError

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class qiime2.sdk.Method

QIIME 2 Method

get_import_path(include_self=True)

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.Pipeline

QIIME 2 Pipeline

get_import_path(include_self=True)

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(add_plugins=True)

add_plugin(plugin, package=None, project_name=None, consistency_check=True)

entry_point_group = 'qiime2.plugins'

property exportable_formats

Formats that are exportable. A format is exportable in a QIIME 2 deployment if it can be transformed from at least one of the canonical semantic type formats.

forget_singleton()

Allows later instatiation of PluginManager to produce new object

This is done by clearing class member which saves the instance. This will NOT invalidate or remove the object this method is called on.

get_directory_format(semantic_type)

get_formats(self, *, filter=None, semantic_type=None)

filterenum | “IMPORTABLE” | “EXPORTABLE”

filter is an enum integer that will be used to determine user input to output specified formats

semantic_typeTypeExpression | String

The semantic type is used to filter the formats associated with that specific semantic type

This method will filter out the formats using the filter provided by the user and the semantic type. The return is a dictionary of filtered formats keyed on their string names.

get_plugin(*, id=None, name=None)

get_semantic_types()

property importable_formats

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.

classmethod reuse_existing()

property type_formats

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)

result()

Noop to provide standardized interface with ProxyResult.

save(filepath, ext=None)

Save to a file.

Parameters:

• filepath (str) – Path to save file at.

• extension (str) – Preferred file extension (.qza, .qzv, .txt, etc). If no preferred extension input is included, Artifact extension will default to .qza and Visualization extension will default to .qzv. Including a period in the extension is optional, and any additional periods delimiting the filepath and the extension will be reduced to a single period.

Returns:

Filepath and extension (if provided) that the file was saved to.

Return type:

str

See also

load

property type

property uuid

validate(level=NotImplemented)

class qiime2.sdk.ResultCollection(collection=None)

property extension

items()

keys()

classmethod load(directory)

Determines how to load a Collection of QIIME 2 Artifacts in a directory and dispatches to helpers

result()

Noop to provide standardized interface with ProxyResultCollection.

save(directory)

Saves a collection of QIIME 2 Results into a given directory with an order file.

NOTE: The directory given must not exist

save_unordered(directory)

Saves a collection of QIIME 2 Results into a given directory without an order file. This is used by q2galaxy where an order file will be interpreted as another dataset in the collection which is not desirable

NOTE: The directory given must not exist

property type

validate(view, level=None)

values()

class qiime2.sdk.Results(fields, values)

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, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

exception qiime2.sdk.UninitializedPluginManagerError

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception qiime2.sdk.ValidationError

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

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)

result()

Noop to provide standardized interface with ProxyResult.

save(filepath, ext=None)

Save to a file.

Parameters:

• filepath (str) – Path to save file at.

• extension (str) – Preferred file extension (.qza, .qzv, .txt, etc). If no preferred extension input is included, Artifact extension will default to .qza and Visualization extension will default to .qzv. Including a period in the extension is optional, and any additional periods delimiting the filepath and the extension will be reduced to a single period.

Returns:

Filepath and extension (if provided) that the file was saved to.

Return type:

str

See also

load

property type

property uuid

validate(level=NotImplemented)

class qiime2.sdk.Visualizer

QIIME 2 Visualizer

get_import_path(include_self=True)

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'

qiime2.sdk.parse_format(format_str)

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.

Return type:

type expression

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.

Return type:

type expression