Fork me on GitHub

Artifact APIΒΆ


This guide assumes you have performed the steps in the Moving Pictures tutorial. The table.qza and sample-metadata.tsv files generated in that tutorial are used here.

The Artifact API is a Python 3 application programmer interface (API) for QIIME 2. The Artifact API supports interactive computing with QIIME 2 using the Python 3 programming language. This API is intended for advanced/technical users. The Artifact API has been optimized for use in the Jupyter Notebook, which is currently our primary target for use of this API. The Artifact API is a part of the QIIME 2 framework; no additional software needs to be installed to use it. This API is automatically generated, and its availability depends on which QIIME 2 plugins are currently installed. To see this in action, begin by uninstalling the q2-feature-table plugin.

conda uninstall q2-feature-table

Then, open a Python interpreter such as IPython and enter the following command. You should get an error message telling you that the plugin you’re trying to access is not available. Leave the interpreter by typing exit.

>>> from qiime2.plugins import feature_table
ImportError: cannot import name 'feature_table'
>>> exit

Next, reinstall the q2-feature-table and q2-diversity plugins (q2-diversity was uninstalled automatically when we uninstalled q2-feature-table above because it depends on q2-feature-table).

conda install --override-channels -c qiime2 -c defaults q2-feature-table q2-diversity

Open your interpreter, and you should now be able to import this plugin:

>>> from qiime2.plugins import feature_table

We’ll now explore some of the same methods and visualizers introduced in the Moving Pictures tutorial, this time in the Python interpreter instead of the command line interface. First, we’ll load a QIIME 2 Artifact, in this case a feature table. We’ll then pass that to the q2-feature-table plugin’s rarefy method, which will return a new Artifact.

>>> from qiime2 import Artifact
>>> unrarefied_table = Artifact.load('table.qza')
>>> rarefy_result = feature_table.methods.rarefy(table=unrarefied_table, sampling_depth=100)
>>> rarefied_table = rarefy_result.rarefied_table

While we recommend working with QIIME 2 Artifacts directly, it is possible to access the underlying data in one or more compatible views (Python objects/data structures or file formats). For example, you may want to access the rarefied feature table that was just created as a biom.Table object. You can do this as follows:

>>> import biom
>>> biom_table = rarefied_table.view(biom.Table)
>>> print(biom_table.head())
# Constructed from biom file
#OTU ID      L1S105  L1S140  L1S208  L1S257  L1S281
b32621bcd86cb99e846d8f6fee7c9ab8     25.0    31.0    27.0    29.0    23.0
99647b51f775c8ddde8ed36a7d60dbcd     0.0     0.0     0.0     0.0     0.0
d599ebe277afb0dfd4ad3c2176afc50e     0.0     0.0     0.0     0.0     0.0
51121722488d0c3da1388d1b117cd239     0.0     0.0     0.0     0.0     0.0
1016319c25196d73bdb3096d86a9df2f     11.0    17.0    12.0    4.0     2.0

You can also view the artifact’s data as a pandas.DataFrame object:

>>> import pandas as pd
>>> df = rarefied_table.view(pd.DataFrame)
>>> df.head()
        b32621bcd86cb99e846d8f6fee7c9ab8  99647b51f775c8ddde8ed36a7d60dbcd  \
L1S105                              25.0                               0.0
L1S140                              31.0                               0.0
L1S208                              27.0                               0.0
L1S257                              29.0                               0.0
L1S281                              23.0                               0.0

A powerful feature of QIIME 2 is that you can export different types of views from QIIME artifacts as illustrated here, then operate on the resulting data types, and import those data back into QIIME. This is useful if there are some operations that are available on the view’s data type (e.g., the pandas.DataFrame) that are not available through the QIIME API. An important caveat is that you will lose all artifact provenance in the process, because QIIME can’t track what happens to data outside of QIIME. You can import the pandas.DataFrame back into a new QIIME artifact as follows:

imported_artifact = Artifact.import_data("FeatureTable[Frequency]", df)

The rarefied_table artifact can be passed to methods of other QIIME 2 plugins. Here we’ll compute the Observed OTUs alpha diversity metric using the q2-diversity plugin. The resulting Artifact will be of type SampleData[AlphaDiversity], and we can access a pd.Series as a view of this Artifact.

>>> from qiime2.plugins import diversity
>>> alpha_result = diversity.methods.alpha(table=rarefied_table, metric='observed_otus')
>>> alpha_diversity = alpha_result.alpha_diversity
>>> alpha_diversity.view(pd.Series)
L1S105    24
L1S140    19
L1S208    25
L1S257    30
L1S281    29
L1S57     23
L1S76     20
L1S8      17
Name: observed_otus, dtype: int64

Finally, we can save our Artifacts as .qza files and exit the interpreter as follows:

>>> exit

Another powerful feature of QIIME 2 is that you can combine interfaces. For example, you could develop a Python script that automatically processes files for you to generate results as we just did, and then perform analysis of those files using the command line interface or the QIIME 2 Studio. For instance, you could now continue your analysis and view some results on the command line as follows:

qiime diversity alpha-group-significance --i-alpha-diversity oo.qza --m-metadata-file sample-metadata.tsv  --o-visualization oo-group-significance.qzv