QIIME 2 Scripts Page

Ideas and Suggestions
1

Good Afternoon!

I have a quick suggestion regarding the webpage for QIIME 2. In QIIME 1, there is easy access to a scripts page that outlines quite coherently the various scripts one can use in QIIME, what they do and how to use them. I believe having a similar page on the QIIME 2 webpage would be extremely helpful for new users, such as myself.

Thank you for your time,
Sirtaj Singh

1 Like
2

The QIIME 2 analogue is this page. Is there something we can change to make it more visible, or is there something missing here?

3

Thank you for the link! The list looks great and is quite comprehensive, but I do think that some sample scripts on these pages would be useful as well.

For example, on the demux visualizers page, having something along the lines of the following may be useful:
qiime demux summarize \ --i-data demux.qza \ --o-visualization demux.qzv

This addition may help learners such as myself better understand the syntax of QIIME 2, as well as the effect different parameters would have on the outcome of the code. Something similar to this can be found in Qiime 1.

4 Likes
4

That’s a great idea! We have an open issue for supporting script usage examples in the plugin docs, and more generally to allow plugin developers to attach their own docs, tutorials, etc. to plugins. Thanks @Sirtaj-Singh!

3 Likes
5

Agreed - my lab is struggling with the same issue!

6

Disclaimer: I’m pretty new to using Qiime 2, and am slowly modifying directions from the Tutorials to suit my own data analysis needs. So somethings that might be obvious to the “seasoned Qiime-2” community are still in the exponential growth phase of my own learning curve…

Something that might be improved to help other newbs: I noticed an issue in the “Available Plugins” page under Qiime 2017.8 that caused much head-scratching…

While trying to modify the denoise-paired script provided under the DADA2 section of the “Atacama Soils Tutorial” using the denoise-paired detail page under “Available Plugins” I ran into two separate issues:

  1. It took me a while to figure out that --i and --p and --o refer to the Input, Parameter and Output “headings” of the table respectively - it might be useful to indicate this somewhere so people who are new to Qiime 2 scripting “language”
  2. All the “options” for Parameters have underscores between the words (e.g. “n_threads” to change the number of cores available) but when you add this command to run in qiime, it must be “n-threads” with a hyphen (like all the other commands in the tutorial), NOT an underscore (which none of the commands in the tutorial use). This should definitely be fixed in the documentation (unless there’s some reason to include underscores when you really need hyphens?)… That way us newbs can start to massage the analysis workflow to better suit our own needs…

Thanks!

8

Hi @alibba!

Welcome to the QIIME 2 community! These points you brought up are fantastic and something we've discussed fixing in the past, so you're not alone here!

That's a great idea! The "raw" parameter names are included on these plugin pages -- these are the names assigned by QIIME 2 plugin developers and have to follow certain naming conventions since the plugins are written in the Python programming language. The "raw" parameter names use underscores instead of hyphens because hyphens are disallowed in Python identifiers (e.g. parameter names).

Each QIIME 2 interface (e.g. the command line interface you're using, q2studio, the Python "Artifact API") has the opportunity to change these "raw" parameter names into something that makes sense for the interface. For example, q2cli (the command line interface) converts underscores to hyphens and prefixes each name with --i-, --p-, --m-, or --o- depending on what type of parameter it is.

Right now we don't have examples of what the parameter names look like in different interfaces; only the "raw" parameter names are displayed. I agree this is confusing and should be fixed -- we've talked about this issue in the past and are really excited to support it at some point down the road. I created an issue so we can keep track of this feature.

Thanks again for getting in touch, and Happy QIIMEing! :sun_with_face:

10

A minor note, I notice that the Qiime2 website plug-in documentations have underscore separated parameters whereas in terminal we would be using a dash.
i.e. from the site: demultiplexed_seqs whereas it should be demultiplexed-seqs.
Unless this is by design for some reason I think it might throw off some people migrating from Qiime1 being used to the underscores.

ps. I apologize in advance for numerous postings today, just dumping some of my notes I took during our recent Q2 workshop.

1 Like
11

Hi @Mehrbod_Estaki! I moved your post into this existing thread that expands on your observations a bit more. Please review this and let us know if you have any questions. Thanks!

1 Like
12

No, this is great. Apologies for the redundant comment then, I did try looking it up before posting but must have missed this thread.

1 Like
13

As of the QIIME 2 2017.9 release, the available plugins page now displays help text for the CLI and Python “Artifact API” – the issues regarding differences in naming (e.g. dashes vs underscores; parameter name prefixes vs none, etc.) should be resolved. For an example, check out the dada2 denoise-single page! :tada:

1 Like
14

Note: we will follow up here when the other features discussed in this topic are available in a release (i.e. script usage examples, “choose-your-own-interface” widget in the tutorials).