Artifact API (using QIIME 2 with Python)¶
Note
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 programming 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 API is automatically generated, and its availability depends on which QIIME 2 plugins are currently installed. It 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.
Using Python to run QIIME 2¶
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.plugins import feature_table
>>> 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
Interoperability with other Python libraries¶
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 process rarefied feature table that was just created as a pd.DataFrame
object. You can do this as follows:
>>> 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
...
You can also view the artifact’s data as a biom.Table
object:
>>> 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
A powerful feature of QIIME 2 is that you can export different types of views from QIIME 2 artifacts as illustrated here, then operate on the resulting data types, and import those data back into QIIME 2. 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 2 API.
.. tip:: You will lose all artifact provenance in the process, because QIIME 2 can’t track what happens to data outside of QIIME 2.
You can import the pandas.DataFrame
back into a new QIIME 2 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 Features 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.pipelines.alpha(table=rarefied_table, metric='observed_features')
>>> 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_features, dtype: int64
Finally, we can save our Artifacts
as .qza
files and exit the interpreter as follows:
>>> rarefied_table.save('rare.qza')
'rare.qza'
>>> alpha_diversity.save('obs_features.qza')
'obs_features.qza'
>>> exit
Combining interfaces¶
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. 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 obs_features.qza --m-metadata-file sample-metadata.tsv --o-visualization obs-f-group-significance.qzv
The above command as an API call is:
>>> from qiime2 import Metadata
>>> metadata = Metadata.load('sample-metadata.tsv')
>>> group_significance = diversity.actions.alpha_group_significance(alpha_diversity=alpha_diversity, metadata=metadata)