Add option to dynamically insert tool citations into MultiQC report

[jfy133]

Extends the methods description in the MultiQC report to optionally generate text dynamically depending on what steps in the pipeline are run, to include citations/references of the tools used in the given pipeline run.

This hopefully will improve method reporting and credit to all the authors of the tools used in pipelines, as it more actively shows citation information of these tools over citations.md or meta.yaml, neither of which are exposed to users. It also makes it easier for users to report these as the pipeline author can make the text only have references of tools used in the run, so the user does not have to scroll through 10s of bibliographic references in citations.md to find the ones of the tools they actually used.

Real life proof of concept can be seen here: nf-core/taxprofiler#308

Things to consider:

• Functions require duplication of if/else statements, which may get out of sync if a pipeline developer isn't careful
  • I didn't have time to work how to collapse the two functions into one so only one set of if/else statements are required (e.g. have the function output two maps, one containing the in-text citation and the other bib. info)
• Does not include version information of the tool
  • Not yet possible to retrieve this information from within nf-core pipelines
• Requires a large amount of input from the pipeline developer to re-construct if/else statements
  • This is a painpoint, but also no solution at the moment as can't easily pick up what modules are actually run
  • Reference information is present in meta.yml but we have no way to parse these (let alone dynamically depending on which tool used)
  • Also inclusion of this remains optional
• Template does not include example of optional insertion
  • But provided docs on this in the comment
• Forces pipeline developers to check for formatting consistency of references
  • I don't yet see any NXF compatible plugin/library for rendering e.g. bibtext

However I believe this is a good starting point that overtime could be more automated in future template updates, as it at least provides a place/mechanism to include in the report (regardless of how the text is generated).

Partly addresses #236

PR checklist

• This comment contains a description of changes (with reason)
• CHANGELOG.md is updated
• If you've fixed a bug or added code that should be tested, add tests!
• Documentation in docs is updated

[codecov]

Codecov Report

Merging #2326 (5f0087f) into dev (37c3d06) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##              dev    #2326   +/-   ##
=======================================
  Coverage   72.86%   72.86%           
=======================================
  Files          78       78           
  Lines        8774     8774           
=======================================
  Hits         6393     6393           
  Misses       2381     2381           

[mirpedrol]

This is very nice!
I wonder if we could parse a file such as CITATIONS.md given that we already have it (or a JSON/YAML version of it) instead of having the developer manually add the citations in the groovy script. I'm sure I'm not the first one to consider this, and there might be some challenges in implementing it 😄 Anyway, this looks like a good start! 🚀

[mirpedrol]

Add link to this PR :)

[jfy133]

Whoops thanks!

[jfy133]

This is very nice! I wonder if we could parse a file such as CITATIONS.md given that we already have it (or a JSON/YAML version of it) instead of having the developer manually add the citations in the groovy script. I'm sure I'm not the first one to consider this, and there might be some challenges in implementing it smile Anyway, this looks like a good start! rocket

What @maxulysse and I have talked about is in teh future is actually taking somehow the DOI from meta.yml (citations.md is too inconsistent in terms of formatting across pipelines etc, if even filled in 😬 ).

What I was actually thinking was (in the future!) if we should embed the DOI within the process itself (as well as the version) as specific ext fields.... that would make it much easier to collect what is actually executed...

[mashehu]

What @maxulysse and I have talked about is in teh future is actually taking somehow the DOI from meta.yml (citations.md is too inconsistent in terms of formatting across pipelines etc, if even filled in 😬 ).

Taking the doi from the meta.yml sounds totally doable to me (and all should be even of the same formatting thanks to the schema). Just need to have it flexible enough to handle modules without DOIs.

[jfy133]

What @maxulysse and I have talked about is in teh future is actually taking somehow the DOI from meta.yml (citations.md is too inconsistent in terms of formatting across pipelines etc, if even filled in grimacing ).

Taking the doi from the meta.yml sounds totally doable to me (and all should be even of the same formatting thanks to the schema). Just need to have it flexible enough to handle modules without DOIs.

How would we filter for just modules that ran though?

[mashehu]

I imagine to do it similar to how we do software versions.

[JoseEspinosa]

Very good job! ❤️
I agree that parsing the DOIs of the executed modules from the yml will be a very nice addition.