Artifact API (using QIIME 2 with Python)¶
This guide assumes you have performed the steps in the Moving Pictures tutorial. The
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
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
>>> 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)
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
>>> 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
.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
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)