Artifact API (using QIIME 2 with Python)¶

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)