I am an experienced Python developer but new to Qiime2. I have walked through the tutorials, which show the applications with command line as a nice wrapper. However, I still prefer the API (i.e. call Python packages directly instead of a wrapper in Python calls the command line wrapper).
So far, I can replace most command lines with APIs, but there is one thing I could not figure out: exporting .qzv files. For examples, How do I translate the following command line with Python code?
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:
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.
Thanks for pointing out the usage of qiime2.plugins, and that really helps. I will refactor my code with this format (instead of checking the individual plugins q2_xxxx).
Sounds good! We definitely need more documentation on the Artifact API, but let me explain the difference in imports briefly:
You were importing what we call the view API, which is the underlying function that’s registered on a QIIME 2 plugin. In this example, the view API function you were importing is from q2_metadata import tabulate. When a view API function is registered on the plugin, QIIME 2 automatically wraps the function in a new signature that is available for import under qiime2.plugins.<plugin-name>. These wrapped functions are what we call the Artifact API. In general, you’ll want to use the Artifact API functions instead of the view API functions because the Artifact API accepts and returns Artifact or Visualization objects, whereas the view API accepts whatever “raw” Python objects were defined by the plugin author (e.g. a biom.Table object instead of a FeatureTable[Frequency] artifact).