Clarification for "list" in qiime feature-data merge and qiime feature-data merge-seqs

In the CLI help docs for qiime feature-data merge-seqs (and similar for others I am sure) it says:

--i-data MULTIPLE ARTIFACT PATH List[FeatureData[Sequence]] The collection of feature sequences to be merged. [required]

And I think it’s a bit unclear.

I have done this several times…I’ve provided a list of qzas either spaced or in brackets and comma separated because that’s a list. :slight_smile: And either way I used the --i-data option only once thinking it would know I provided multiple items. I keep forgot to add the option flag multiple times for each item. I think clarification in the CLI would be nice because the word “List” is misleading in a sense.

Just a suggestion, nothing urgent! :sun_with_face:

1 Like

Hey there @Jennifer_Fouquier — I agree, it isn’t super clear. The reason is because QIIME 2 is interface agnostic, so this nomenclature of List[blah] business is meant to be applicable irrespective of how any particular interface chooses to implement it (e.g. a GUI might have some kind of multi-select, or drag-and-drop tiles/cards).

Maybe in the case of q2cli we could append the following at the end of the parameter text: Flag may be specified multiple times., or something along those lines. What do you think?

1 Like

Ah, I see.

I think what you suggest would improve things. Although could you say Flag must be specified multiple times … since it’s a merge, doesn’t that imply you need more than one input?

For this particular example, no, you don't need more than one input --- you can pass just one table to feature-table merge and it will be just fine with that (it is effectively a noop).

1 Like

@thermokarst, I wrote this up, then realized I already reported this, haha. :crazy_face:

I'm looking at qiime feature-table merge --help right now and I very strongly recommend that you add something like the following to the --i-tables help docs in the CLI. This clarification should be added to all commands where there is a list. It's unclear that it should be --i-tables my-artifact1.qza --i-tables my-artifact2.qza rather than --i-tables [my-artifact1.qza, my-artifact2.qza] or something along those lines which doesn't work. I have done this several times :slight_smile: Maybe it's just me, but this documentation is confusing.

Wherever there is a List[something] in the --help docs, I suggest adding: Multiple parameter flags should be used, each with their own input artifact.

So, for this example:

The collection of feature tables to be merged. Multiple parameter flags should be used, each with their own input artifact.

I've messed up on this quite a few times and I am imagining others are because it doesn't read very clear especially if you're used to normal lists like [item, item, item].

Thanks :slight_smile:

Screen Shot 2020-03-07 at 10.56.51 PM

2 Likes

Totally agreed! It is unclear and I had the same issue.

1 Like