Visualization API

Hi @spencerimp! Before answering your specific question, the Artifact API tutorial may be helpful if you’re using the Python 3 API provided by QIIME 2. The tutorial is very basic and needs a lot more content added, but it may give you some ideas when using the Python 3 API (stay tuned for an expanded “Artifact API” tutorial in the future!).

Your question also deals with viewing artifacts as metadata – check out this section of the metadata tutorial for details about that. The tutorial doesn’t cover how to do this with the Python 3 API; I’ll cover that below.

Okay, now on to answering your original question! Assuming you have the following CLI command:

$ qiime metadata tabulate --m-input-file taxonomy.qza --o-visualization taxonomy.qzv

Here’s how you can accomplish the same thing with the Python 3 API. I’ve included some comments in the code explaining what’s happening.

# Import `qiime2` so that we have access to the `Artifact` and `Metadata`
# APIs below. You could also use `from qiime2 import Artifact, Metadata`
# but I like to keep things namespaced.
import qiime2

# Import the `tabulate` visualizer from the `q2-metadata` plugin.
# Note that this is a different import than the one you were using.
from qiime2.plugins.metadata.visualizers import tabulate

# If you're using IPython/Jupyter, you can learn more about the
# visualizer/method you imported with `?`. For example, this command
# will show you the visualizer's docstring describing its inputs
# and outputs.
tabulate?

# Load the input artifact that we're going to visualize with
# `tabulate`.
taxonomy = qiime2.Artifact.load('taxonomy.qza')

# Since `tabulate` accepts a `Metadata` object as input
# (not an `Artifact`), we need to view the artifact as metadata.
# Create a `Metadata` object from the input artifact --
# this preserves the input artifact's provenance in the
# visualization that's created by `tabulate` too!
taxonomy_md = qiime2.Metadata.from_artifact(taxonomy)

# Now that we have a `Metadata` object, run the `tabulate`
# visualizer.
output_viz, = tabulate(taxonomy_md)

# `output_viz` is a `qiime2.Visualization` object. We can save it
# to a `.qzv` file. You can also use `.export_data()` if you wish to
# directly export the visualization, similar to what `qiime tools export`
# does.
output_viz.save('taxonomy.qzv')

Hope this helps! Let me know if you have any additional questions.

3 Likes