Add documentation for non-argument module inputs by itrujnara · Pull Request #4210 · nf-core/website

itrujnara · 2026-05-13T09:34:11Z

This PR adds a new section in module input/output specifications to describe best (and discouraged) practices for module inputs that are not tool arguments. This change aims to make existing practices explicit and promote consistency rather than create new rules. It is based on my perception of the consensus, so please let me know if anything is inaccurate.
The changes have been preliminarily checked for compliance with the documentation style guide with GPT-5.4-mini.

@netlify /docs/specifications/components/modules/input-output-options

…tput options documentation

netlify · 2026-05-13T09:34:16Z

✅ Deploy Preview for nf-core-docs ready!

Name	Link
🔨 Latest commit	`5d1655f`
🔍 Latest deploy log	https://app.netlify.com/projects/nf-core-docs/deploys/6a154ec586f2e800087135d6
😎 Deploy Preview	https://deploy-preview-4210--nf-core-docs.netlify.app/docs/specifications/components/modules/input-output-options
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2026-05-13T09:34:16Z

✅ Deploy Preview for nf-core-main-site ready!

Name	Link
🔨 Latest commit	`5d1655f`
🔍 Latest deploy log	https://app.netlify.com/projects/nf-core-main-site/deploys/6a154ec569afe90008ab301a
😎 Deploy Preview	https://deploy-preview-4210--nf-core-main-site.netlify.app/docs/specifications/components/modules/input-output-options
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

mashehu · 2026-05-13T09:36:47Z

+
+Input channel `val` declarations MAY be used to control behaviours of the module that cannot be expressed with arguments of the underlying tool.
+
+- If a module implements multiple subcommands of a tool, the subcommand SHOULD be provided through a channel.


isn't the rule that subcommands should be their own module?

Generally yes, but there are some modules where a subcommand or subsubcommand is passed as an input (specifically, per Codex and confirmed manually: HELITRONSCANNER_SCAN, LONGSTITCH, COOLER_CLOAD, MIDAS_RUN, QSV_CAT, UMICOLLAPSE, SAMBAMBA_DEPTH, VAMB_BIN, ANNOSINE). I am not sure whether this is an accepted practice or unnoticed abuse. I don't feel too strongly about this point, so I am happy to leave it out if there is strong opposition.

I would say unnoticed deviations

I'll wait a bit for differential opinions, but if others agree with you I'll remove it since I don't want to start a civil war here

Yeah I agree, this sounds like things that slipped through review.

The only case I can imagine this being valid if it all subcommands share exactly the same options and arguments ,(so they apply to every subcommand), but then this would be very unlikely as they you might as well just control this via another argument.

Alright, changed it. I used SHOULD, since there might be very specific cases where this makes sense.

itrujnara · 2026-05-13T10:05:19Z

@nf-core-bot fix linting

…put options

…for `val` channel inputs

…put options documentation

itrujnara · 2026-05-13T12:14:45Z

@nf-core-bot fix linting

…l inputs documentation

itrujnara · 2026-05-13T12:57:25Z

@nf-core-bot fix linting

muffato

I'm not entirely sold on removing all getExtension(). I feel this proposal would just shift the name parsing to (sub-)workflows.

That said, I agree with removing ambiguity from the modules. Modules should offer choice when there is choice (instead of picking one). And when modules are trying too hard to guess, when there's a risk they may get it wrong, modules should require the caller to be explicit about what they want.

Here are some further comments.

Co-authored-by: Matthieu Muffato <cortexspam-github@yahoo.fr>

…umentation

mahesh-panchal

I'm good with this. 👍🏽

jfy133 · 2026-06-10T07:16:00Z

+Input channel `val` declarations MAY be used to control behaviours of the module that cannot be expressed with arguments of the underlying tool.
+
+- If a module can output multiple file formats, the output format SHOULD be provided through a channel. The module SHOULD NOT infer the output format from the input path.
+  :::info{title="Rationale" collapse}


Suggested change

:::info{title="Rationale" collapse}

:::info{title="Rationale" collapse}

This could be an example moved to the previous section

jfy133 · 2026-06-10T07:16:17Z

+
+- If a module can output multiple file formats, the output format SHOULD be provided through a channel. The module SHOULD NOT infer the output format from the input path.
+  :::info{title="Rationale" collapse}
+  Modules can encounter numerous input name scenarios. Custom string operations necessarily make assumptions about the name of the file (for example that the name of a compressed file has at least two dots). Providing an explicit format input returns full control to the pipeline developer and reduces the risk of unexpected behaviour.


Suggested change

Modules can encounter numerous input name scenarios. Custom string operations necessarily make assumptions about the name of the file (for example that the name of a compressed file has at least two dots). Providing an explicit format input returns full control to the pipeline developer and reduces the risk of unexpected behaviour.

Modules can encounter numerous input name scenarios.

Custom string operations necessarily make assumptions about the name of the file (for example that the name of a compressed file has at least two dots).

Providing an explicit format input returns full control to the pipeline developer and reduces the risk of unexpected behaviour.

I don't fully understand this point - what do you mean by 'nuermous input name scenarios'? and 'custom string operations' - for what? Is this sentence meant to be a justification here why you should have an explicit extension val channel to control this (as in the alternative methods cenarios are bad)?

This stems from my observations while reworking the bgzip modules. Some implementations assumed that the input name would always be something like variants.vcf.gz, so the module could "fish out" the output extension by splitting on dots and taking the second item from the end. However, it is not guaranteed that it will always be the case, and files could have names like database.gz, where database is likely not the desired extension. At least in my opinion, the module should be agnostic to the exact file name and use inputs to delegate the details to the pipeline. I hope I have explained it clearly enough in the draft.

HRm OK, I think you've made the explainations a bit too generic...

So does it ultimately boil down to:

If a module can emit mutually exclusive output formats of the same output file (e.g. bam/sam/cram), this SHOULD be explicitly defined using a dedicated input val channel?

jfy133 · 2026-06-10T07:18:44Z


+## Non-argument `val` channel inputs
+
+Input channel `val` declarations MAY be used to control behaviours of the module that cannot be expressed with arguments of the underlying tool.


Suggested change

Input channel `val` declarations MAY be used to control behaviours of the module that cannot be expressed with arguments of the underlying tool.

Input channel `val` declarations MAY be used to control optional but critical behaviours of the module that cannot be expressed with arguments of the underlying tool.

Is this what you mean?

At the moment reading this I'm not sure how this differs from the much more concise point 1 of the previous section (although we could have a an example):

Mandatory non-file inputs are options that the tool MUST have to be able to be run.

This is not quite what I mean. This section aims to codify existing practice for inputs like val action, val compress, and val out_fmt, which are common in modules, but lack appropriate documentation. These input are not really "an argument to the tool", but are still an important argument to the module.

Ah I think I'm starting to follow now.

I guess then just a single additional sentence of:

'This can include parameters to control execution of the tool, outside of the tool parameters itself - such as an optional post-execution compression step (to adhere to nf-core specification XYZ)' or something like this?

jfy133 · 2026-06-10T07:22:02Z

+
+- If the output format of a module is necessarily the same as the input format, the module MAY infer the output format from the input path.
+
+- If a module contains an optional pipe (for example: compression, sorting), the pipe SHOULD be controlled with a Boolean input channel.


OK the more I read about this, this feels mostly more about how to define output names, in which case I think the title of the section should be changed accordingly and rephrased to be more active of what you SHOULD do (a lot of this seems to be more defensive).

E.g., a seciton on output naming would be more like:

Should use ${prefix}

Avoid a default prefix as far as possible (pipeline developers should control this)

Should not include custom strings except if necessary to define extension (controlled by input channel)

Or something like that

Also technically this also overlaps with this section actually: https://nf-co.re/docs/specifications/components/modules/naming-conventions#command-file-output-naming

This is not meant to be a section on outputs, but rather on inputs. The current documentation largely suggests that every input to the module should be an input to the tool, which is clearly not the case. The involvement of output names is due to the drama of val out_fmt vs. ext.suffix (the former being the preferred practice according to maintainer discussions).

Basically what I want here is to move ideas from random Slack threads to the documentation

The current documentation largely suggests that every input to the module should be an input to the tool, which is clearly not the case.

I don't think this is necessarily true: https://nf-co.re/docs/specifications/components/modules/input-output-options#required-val-channel-inputs ('essential for executuion of the tool' does not necessarily reuqire this to be an input to the tool itself - but we could make this clearer if yo uwanted?)

itrujnara · 2026-06-11T11:16:21Z

@jfy133 could you please clarify whether you suggest to:

keep the new section, but phares it differently, or
scrap the new section and instead add information to the section above?

feat(docs): add non-argument val channel inputs section to input/ou…

5091b7a

…tput options documentation

mashehu reviewed May 13, 2026

View reviewed changes

nf-core-bot and others added 2 commits May 13, 2026 10:07

[automated] Fix code linting

a3c89df

fix(docs): clarify usage of val inputs and subcommands in input/out…

0b6d36f

…put options

mahesh-panchal reviewed May 13, 2026

View reviewed changes

Comment thread sites/docs/src/content/docs/specifications/components/modules/input-output-options.md

Comment thread sites/docs/src/content/docs/specifications/components/modules/input-output-options.md

itrujnara added 2 commits May 13, 2026 14:09

feat(docs): enhance input/output options documentation with examples …

93b093c

…for `val` channel inputs

feat(docs): add example section for val channel inputs in input/out…

443237e

…put options documentation

nf-core-bot and others added 2 commits May 13, 2026 12:16

[automated] Fix code linting

ee660ec

fix(docs): remove redundant example section heading from val channe…

6f977eb

…l inputs documentation

[automated] Fix code linting

e602cc2

muffato reviewed May 13, 2026

View reviewed changes

itrujnara and others added 4 commits May 18, 2026 09:24

Apply suggestions from code review

7c91833

Co-authored-by: Matthieu Muffato <cortexspam-github@yahoo.fr>

fix(docs): clarify output format handling in val channel inputs doc…

79ab1ee

…umentation

Merge branch 'main' into main

ab8e427

Merge branch 'main' into main

5d1655f

mahesh-panchal approved these changes May 26, 2026

View reviewed changes

muffato approved these changes May 27, 2026

View reviewed changes

mashehu approved these changes May 27, 2026

View reviewed changes

jfy133 reviewed Jun 10, 2026

View reviewed changes


		Input channel `val` declarations MAY be used to control behaviours of the module that cannot be expressed with arguments of the underlying tool.

		- If a module implements multiple subcommands of a tool, the subcommand SHOULD be provided through a channel.

	:::info{title="Rationale" collapse}

	:::info{title="Rationale" collapse}


		## Non-argument `val` channel inputs

		Input channel `val` declarations MAY be used to control behaviours of the module that cannot be expressed with arguments of the underlying tool.


		- If the output format of a module is necessarily the same as the input format, the module MAY infer the output format from the input path.

		- If a module contains an optional pipe (for example: compression, sorting), the pipe SHOULD be controlled with a Boolean input channel.

Uh oh!

Conversation

itrujnara commented May 13, 2026 • edited by nf-core-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for nf-core-docs ready!

Uh oh!

netlify Bot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for nf-core-main-site ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

itrujnara May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

itrujnara commented May 13, 2026

Uh oh!

Uh oh!

Uh oh!

itrujnara commented May 13, 2026

Uh oh!

itrujnara commented May 13, 2026

Uh oh!

muffato left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mahesh-panchal left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

itrujnara commented Jun 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

itrujnara commented May 13, 2026 •

edited by nf-core-bot

Loading

netlify Bot commented May 13, 2026 •

edited

Loading

netlify Bot commented May 13, 2026 •

edited

Loading

itrujnara May 13, 2026 •

edited

Loading