From 8e15c25e9a07cab55c1c83c81db3ef25b2a7c9b9 Mon Sep 17 00:00:00 2001 From: "Maxime U. Garcia" Date: Fri, 18 Sep 2026 11:56:27 +0200 Subject: [PATCH 1/2] docs: add meta.strandedness to permitted meta keys --- .../docs/developing/components/meta-map.md | 20 ++++++++++++------- .../components/modules/general.md | 17 ++++++++++------ 2 files changed, 24 insertions(+), 13 deletions(-) diff --git a/sites/docs/src/content/docs/developing/components/meta-map.md b/sites/docs/src/content/docs/developing/components/meta-map.md index 3f5df72faa..c9d103f704 100644 --- a/sites/docs/src/content/docs/developing/components/meta-map.md +++ b/sites/docs/src/content/docs/developing/components/meta-map.md @@ -31,12 +31,13 @@ A meta map sits in a tuple within a Nextflow channel object, next to the one or nf-core developers may define and within a pipelines or local subworkflows any name for a meta map key, and record any metadata they require for the execution of the pipeline. -nf-core only defines 2 'standard' meta map keys. +nf-core defines 2 'standard' meta map keys and 1 additional permitted key. -| key | purpose | -| ----------------- | ------------------------------------------------------------------------------------------------ | -| `meta.id` | recording unique file identifiers associated with a file (e.g. 'sample' names in bioinformatics) | -| `meta.single_end` | genomic sequencing pipelines handling paired-end sequencing data. | +| key | purpose | +| ------------------- | ------------------------------------------------------------------------------------------------ | +| `meta.id` | recording unique file identifiers associated with a file (e.g. 'sample' names in bioinformatics) | +| `meta.single_end` | genomic sequencing pipelines handling paired-end sequencing data. | +| `meta.strandedness` | RNA-seq and other stranded library protocols. Permitted in modules, but not a standard key. | There are no other standard or required key names that nf-core developers need to use. @@ -47,11 +48,16 @@ No other 'standard' meta keys will be officially defined in the future. This is to provide maximum flexibility to pipeline developers. ::: +:::warning +New modules SHOULD NOT use `meta.strandedness` directly. Use `ext.args` in `modules.config` instead. +The only exception is sibling modules of a tool that already uses the pattern (e.g., RNA-seq alignment tools in the same family). +::: + ## Usage in nf-core components ### Modules -The two standard meta map keys (`id` and `single_end`) are the [only keys allowed](../../specifications/components/modules/general#types-of-meta-fields) to be explicitly referred to in an nf-core/module. +The keys `id`, `single_end`, and `strandedness` are the [only keys allowed](../../specifications/components/modules/general#types-of-meta-fields) to be explicitly referred to in an nf-core/module. nf-core/modules refer to meta maps in process `input:` blocks via an entry within a tuple. @@ -82,7 +88,7 @@ All other usage of meta map keys within a module must come via the `ext.args` va ### Subworkflows -No meta maps keys are to be assumed to be present in input channels other than the standard [key names](#key-names), similarly to [modules](#modules). +No meta maps keys are to be assumed to be present in input channels beyond the [permitted key names](#key-names), similarly to [modules](#modules). In contrast to modules, nf-core/subworkflows are allowed to generate new meta map keys, that can be optionally emitted at the end of the subworkflow. diff --git a/sites/docs/src/content/docs/specifications/components/modules/general.md b/sites/docs/src/content/docs/specifications/components/modules/general.md index 8eca54069b..ed47f7489f 100644 --- a/sites/docs/src/content/docs/specifications/components/modules/general.md +++ b/sites/docs/src/content/docs/specifications/components/modules/general.md @@ -211,9 +211,14 @@ Meta variables SHOULD NOT use custom names. 'Custom' hardcoded `meta` fields MUST NOT be used in modules. Do not refer to them within the module as expected input, nor generate new fields as output. -The only accepted 'standard' meta map keys are `meta.id` or `meta.single_end`. +The only accepted meta map keys are `meta.id`, `meta.single_end`, and `meta.strandedness`. Discuss proposals for other 'standard' fields for other disciplines with the maintainers team on slack under the [#modules channel](https://nfcore.slack.com/archives/CJRH30T6V). +:::warning +New modules SHOULD NOT use `meta.strandedness` directly. Use `ext.args` in `modules.config` instead. +The only exception is sibling modules of a tool that already uses the pattern (e.g., RNA-seq alignment tools in the same family). +::: + :::info{title="Rationale" collapse} Write modules to allow as much flexibility to pipeline developers as possible. @@ -226,7 +231,7 @@ In the module code DO NOT: ```nextflow title="main.nf" """script my_command \\ - -r ${meta.strandedness} \\ + -r ${meta.library_type} \\ input.txt \\ output.txt """ @@ -235,7 +240,7 @@ my_command \\ ... but rather: ```groovy title="modules.conf" -ext.args = { "-r ${meta.strandedness}" } +ext.args = { "-r ${meta.library_type}" } ``` And then in the module code: @@ -258,17 +263,17 @@ However, once a module is included into a pipeline, they can be customised at th This can be performed with `nf-core modules patch`. If a hardcoded meta key name is an absolute necessity in a module, it MAY be incorporated and maintained with a patch file. -In this example, `-r ${meta.strandedness}` is hardcoded in the `my_command` module. +In this example, `-r ${meta.library_type}` is hardcoded in the `my_command` module. First install the tool into your pipeline with `nf-core modules install my_command`. -Edit the `main.nf` to include `-r ${meta.strandedness}` and save it. +Edit the `main.nf` to include `-r ${meta.library_type}` and save it. ```nextflow title="main.nf" script """ my_command \\ - -r ${meta.strandedness} \\ + -r ${meta.library_type} \\ ${args} \\ input.txt \\ output.txt From 0f8d93034850453d6f7c51a71ea4cfd740fdf19e Mon Sep 17 00:00:00 2001 From: Maxime U Garcia Date: Fri, 18 Sep 2026 12:16:19 +0200 Subject: [PATCH 2/2] Apply suggestion from @maxulysse --- sites/docs/src/content/docs/developing/components/meta-map.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites/docs/src/content/docs/developing/components/meta-map.md b/sites/docs/src/content/docs/developing/components/meta-map.md index c9d103f704..e8a17a97df 100644 --- a/sites/docs/src/content/docs/developing/components/meta-map.md +++ b/sites/docs/src/content/docs/developing/components/meta-map.md @@ -31,7 +31,7 @@ A meta map sits in a tuple within a Nextflow channel object, next to the one or nf-core developers may define and within a pipelines or local subworkflows any name for a meta map key, and record any metadata they require for the execution of the pipeline. -nf-core defines 2 'standard' meta map keys and 1 additional permitted key. +nf-core defines only two 'standard' meta map keys and one additional permitted key. | key | purpose | | ------------------- | ------------------------------------------------------------------------------------------------ |