Contributing/editing citations

In the various citations that are auto-generated by QIIME 2, I have occasionally found lacunae. Perhaps this is trivial, but the culture around here seems to emphasize meticulous citing habits, which I share and support. The classic post Alpha and Beta Diversity Explanations and Commands does an excellent job, but users have to know about it, whereas the systematic approach would be to close gaps in the auto-generated citations. So how are the citations made by the details tab in, or by running qiime citations [filename] or the [command] --citations option? E.g., I ask because for my Chao1 and Simpson qzvs, at least, Chao's and Simpson's papers aren't cited. Or running PERMANOVA on Aitchison distances, Anderson's paper for PERMANOVA is cited, but not Aitchison's.

Can users contribute/influence these outputs directly, even though this is no wiki? Or do we just submit a suggestion for every lapse we see/change we'd like to see? I'd rather pitch in directly than complain, but I understand caution in limiting who can edit qiime's outputs.


:heart: :heart: :heart:, @wburgess! QIIME 2 is open source, and we super love it when community members contribute.

Citations are created in plugins (e.g. q2-diversity, q2-diversity-lib). Plugin developers create a bibtex-formatted collection of citations. Then, in, they load those citations and register citations to the relevant QIIME 2 Actions. There are details in the dev-docs.

Chao1 and Simpson don't have citations yet, because they don't actually have their own QIIME 2 Methods (QIIME 2 passes the calculations off to skbio with a single catch-all function). Without a method there's nowhere to register the appropriate citation. We'd love to have methods implemented for these.

A contribution would look like this:

  • fork your own copy of q2-diversity-lib, and create a new working branch
  • define a chao1 function here
  • register it here (this will require some thinking about how the measure works)
  • move chao1 from 'UNIMPL' to 'IMPL' here and add a name translation
  • write unit tests for your new function (kinda like these)
  • open a pull request to q2-diversity-lib/main
  • address any comments from reviewers
  • when your code is approved it will get merged into the official codebase

If this is something you're interested in tackling, let me know. I'd be happy to answer questions about the process, or point you to resources that will help.

Chris :shrimp: