Export Command Structure

The command structure for export seems inconsistent with the rest of the qiime ecosystem. In a standard QIIME2 command, it seems to follow the following structure:

qiime plugin command \
     --i-input-file [file] \
     --o-output-file [file]

However, the export function doesn’t take an input flag:

qiime tools export \
  feature-table.qza \
  --output-dir exported-feature-table

This would be much easier to use if it were consistent.

1 Like

Thanks @jwdebelius: this makes a lot of sense to me, thanks for bringing it up! We will discuss and follow up with you. Thanks!

@jwdebelius, just one quick note on the distinction that I would like to point out — the subcommands available in qiime tools aren’t part of a plugin — they are built-in q2cli functions. This means that even if you don’t install any QIIME 2 plugins, you will still have the qiime tools subcommands available to you. Knowing that, does that impact your position on the command structure? As I mentioned above, I think you have a really good point, I just wonder if this distinction between built-ins and plugins has any impact on the discussion. Thanks!

As a user, the underlying software architecture is far less important to me than a consistent experience. If this is required for plug ins, it needs to be required for the core built-ins.
In fact, as a user, I’d like the flags used for tables to be consistent across all the functions I use, rather than vary between the core functionality, emperor, and diversity.

1 Like

That totally makes sense to me — I was attempting to highlight though that built-in commands might actually want to be treated differently than a plugin command from a user perspective, because the built-ins serve a completely different purpose. Put differently, maybe the “underlying software architecture” is less important to you (now), but maybe this actually will be an important thing for users to understand in the future.

To clarify, built-ins are things like importing and exporting data, peeking at artifact info, or viewing a visualization. These are things that don’t happen in a plugin, they exist at a more “fundamental” level of the ecosystem. Plugins represent actual microbiome bioinformatics functionality — plugins are where the analysis happen. I am not disagreeing with you, I think your suggestion makes a lot of sense, I just wanted to indicate that there actually is a difference between the two types of commands (built-in vs plugin), and perhaps a different command structure between the two could play an important role in indicating that distinction to end-users. Or, maybe that distinction doesn’t matter.

Right now installing the Core distribution of QIIME 2 sets the user up with a lot of plugins, exposing an end-to-end microbiome analysis pipeline. Perhaps in the future as we wind up with (hopefully) many more plugins, and many of them accomplishing the same types of things, this might look a little different to end-users. You might want to “choose your own adventure”, and assemble the plugins that are important to you (e.g., I might prefer to use deblur over dada2). That is the situation where I wonder if having a more clear difference in the types of functions might matter more to folks, because your installation of QIIME 2 might look very different than mine, in terms of plugins installed, but, I would probably expect the built-in functionality to remain the same across the two. Just some food for thought, and again this isn’t attempting to contradict your statement, I just want to highlight some of these more “long-term” considerations.


In addition to @thermokarst’s explanation about plugins vs builtin commands:

We intentionally designed the builtin commands (e.g. import, export, peek, etc.) to accept arguments instead of options so that the builtin commands match how Unix command line tools work. Unix tools typically accept required inputs as arguments and optional inputs as options. Since these builtin commands have well-defined required inputs, we chose to match the Unix style.

The plugin commands, however, intentionally only accept options, even for required inputs. This needs to happen because plugin methods/visualizers are defined dynamically by plugin developers – there isn’t a consistent structure to a command’s required inputs or outputs – each command can have a different number of required inputs, defined in different orders, along with different numbers of outputs. Thus, we chose to always use options for dynamic (plugin) commands. This strategy also makes the commands more explicit/descriptive by requiring users to supply option names (this was a design borrowed from QIIME 1).

This is entirely up to the plugin developers that are defining the plugin commands. We’ll try our best to use consistent option names (e.g. for feature tables, rep seqs, etc.) with the plugins we write, but due to QIIME 2’s decentralized development model we don’t have control over the option names that other plugin developers use.

If there are inconsistent option names you’d like to see changed, can you please create issue(s) on the relevant plugin repositories so that we can fix them?

1 Like

The distinction between core qiime 2 functionality and plugin is likely to be lost on most, if not all, users.
The explanation of the rationale just means that I have to remember which commands are core QIIME2 vs plugin.
Is it possible to have structure a click command with a flag, anyway, like there are named arguments in a python function?


I’m actually in favor of always using options over arguments. Having it be mixed honestly means I still have to look at the help text to figure out the output flag anyway. I’d rather see it always require options, or be entirely positional. This half-and-half kind of just means I end up writing half of my command before realizing I have no idea what the rest of it should be.

I’ve thought about this some more, I think I really like not having to provide option flags like:

qiime tools peek --input-artifact something.qza

I definitely prefer

qiime tools peek something.qza

And I would like it if our export command was also consistently argument-based (instead of --output-dir, which I can never remember):

qiime tools export something.qza output_dir/

because it’s basically what I expect as a unix user.


Who is the primary audience for this software package, and this command line interface?
Is this intended for clinicians, biologists, bioinformaticians, computer scientists, incorporation into other software?
Will everyone who uses it be as familiar with the unix enviroment as the developers are?

While this command, in particular, may be consistent with Linux, its inconsistent with the rest of the ecosystem. And, its inconsistent with the previous version of the software.

The primary audience for the QIIME 2 CLI (i.e. q2cli) are power users who have familiarity with the command line. Other QIIME 2 interfaces are intended for different audiences. For example, q2studio is a GUI intended for end users (e.g. biologists, clinicians, etc. who may not have much technical expertise), and the Artifact API is intended for data scientists, developers, computer scientists, etc. who are writing code in Python 3 / Jupyter Notebook. Check out this page for the available QIIME 2 interfaces.

Will everyone who uses it be as familiar with the unix enviroment as the developers are?

We assume that q2cli users have at least a basic understanding of how to use a Unix shell (this was also an assumption with QIIME 1). There are plenty of resources out there that can help bring users up to speed with the command line and gain experience with Unix commands.

We don’t assume CLI users have the same amount of CLI experience as QIIME 2 developers – they may have more or less experience than us, and our experience level varies by developer within the team.

I think we all agree on that. However, there’s a tradeoff between consistency and usability in this case. As @ebolyen noted, it’d be painful to have to type out long option names to use basic QIIME 2 tools such as qiime tools view, qiime tools peek, qiime tools export, and qiime tools extract.

Regardless of the CLI design, users will still need to run --help at least a few times to gain familiarity with the commands and what options they accept. Having these basic (and frequently used) commands match how most Unix tools work will help users remember the commands after they’ve interacted with the CLI a few times, and it keeps the commands succinct and avoids unnecessary typing.

I agree, but the goal here isn’t to match the QIIME 1 CLI.

1 Like