Input/output options

The key words “MUST”, “MUST NOT”, “SHOULD”, etc. are to be interpreted as described in RFC 2119.

1 Required path channel inputs

Input channel path declarations MUST be defined for all possible input files (i.e., both required and optional files).

  • Directly associated auxiliary files to an input file MAY be defined within the same input channel alongside the main input channel (e.g., BAM and BAI).
  • Other generic auxiliary files used across different input files MAY be defined using a dedicated input channel (e.g., reference files).

2 Required val channel inputs

Input channel val declarations SHOULD be defined for all mandatory non-file inputs that are essential for the functioning of the tool (e.g., parameters, flags etc).

  • Mandatory non-file inputs are options that the tool MUST have to be able to be run.
  • These non-file inputs are typically booleans or strings, and must be documented as such in the corresponding entry in the meta.yaml.
  • Options, flags, parameters that are not required by the tool to function should NOT be included - rather these can be passed via ext.args.
Rationale

In 2023, it was decided by a vote amongst interested parties to allow non-file mandatory input channels.

It is important to have documented (using the existing display on the website) the bare minimum information required for a module to run. It also allows module code to consume parameter values without parsing them out of the ext.args string and reduces possible risks of entire breakage of modules with future expected config changes at a Nextflow level.

Downsides to this approach are readability (now multiple places must be checked on how to modify a module execution - modules.conf ext.args, the module invocation in pipeline code etc.), and reduced user freedom. However it was felt that it was more important for stability in and ‘installation’ and ‘execution’ of modules was preferred (e.g., for tools that require position arguments etc.)

Inputs particular cases

When one and only one of multiple argument are required:

  • If they all are string argument : use 1 argument that will be equal to the string.

    For example, parameter model of glimpse2 chunk.

  • If some are files put them all in one channel and test if only one is present.

    For example, grouping output parameters of glimpse2 concordance:

    if (((file1 ? 1:0) + (val1 ? 1:0) + (val2 ? 1:0)) != 1) error "One and only one argument required"{:bash}

3 Output channel emissions

Named file extensions MUST be emitted for ALL output channels. For example, path "*.txt", emit: txt.

4 Optional inputs

Optional inputs are not currently supported by Nextflow. However, passing an empty list ([]) instead of a file as a module parameter can be used to work around this issue.

For example, having a module (MY_MODULE) that can take a cram channel and an optional fasta channel as input, can be used in the following ways:

MY_MODULE(cram, [])     // fasta is optional, the module will run without the fasta present
MY_MODULE(cram, fasta)  // execution of the module will need an element in the fasta channel

5 Optional outputs

Optional outputs SHOULD be marked as optional:

tuple val(meta), path('*.tab'), emit: tab,  optional: true

6 One output channel per output file type

Each output file type SHOULD be emitted in its own channel (and no more than one), along with the meta map if provided ( the exception is the versions.yml ).

In some cases the file format can be different between files of the same type or for the same function (e.g., indices: .bai and .crai). These different file formats SHOULD be part of the same output channel since they are they serve the same purpose and are mutually exclusive.

tuple val(meta), path("*.{bai,crai}"), emit: index
Rationale

This approach allows specific output types to be identified and accessed within their designated channel.

So when the output definition of module called SAMTOOLS_INDEX looks like this:

tuple val(meta), path("*.{bai,crai}"), emit: index

The output files can be accessed like this:

SAMTOOLS_INDEX.out.index

Regardless whether they are a bai or crai as downstream SAMTOOLS modules should accept either without an issue.
On this page