how to add example data to a plugin?


How should you add --example-data in the plugin?


1 Like

Hey @crusher083,

--example-data is a relatively new feature which is automatically populated from Usage Examples.

Here's an example which defines some examples, and the registration happens here.

We also have a new registration for defining "artifact classes" which also supports examples, although q2cli doesn't know about it yet, so you won't see anything exciting right away. But since you're making a new plugin, it's worth keeping in mind. That API will be available in the next release.

The way all of this works under the hood is we define some function (the usage example) which interacts with a use (Usage) object. We call this use object, the "usage driver" and its something interfaces implement (not plugins).

The driver can do anything from render Galaxy UI instructions in reStructured Text, to generating command line calls, to executing the code itself.

All of this happens with the same usage example, interfaces just inject a different Driver depending on their immediate goal. For --example-data there is a driver which chooses to materialize all of an example's initial data while skipping everything else.

An important detail is the definition of these initial data are given by factories which return some QIIME 2 object (like in the Python API). So that might be qiime2.Metadata, qiime2.Artifact, or some subclass of FileFormat/DirectoryFormat. Because these factories are just functions without arguments, the usage Drivers can choose to evaluate the function (thus creating the data) or not to, depending on the goal.