From 9e5e044950b33ebbb1730e3b7aa4fb21e5fac29e Mon Sep 17 00:00:00 2001 From: Maxime U Garcia Date: Sat, 24 Oct 2026 11:19:46 +0200 Subject: [PATCH 1/2] Document reference selection for consuming pipelines Describe the shared resolution order in docs/usage.md: the first source that supplies a usable record wins, each source runs only when the previous ones did not supply fasta, and selecting a datasheet and a catalogue entry at once is an error. Pipeline-specific parameter names stay in each consuming pipeline; nf-core/bamtofastq documents its own and links here. Generated by OpenCode --- CHANGELOG.md | 1 + docs/usage.md | 12 ++++++++++++ 2 files changed, 13 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c0ef4ef..9e181047 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -70,6 +70,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - [#163](https://github.com/nf-core/references/pull/163) - Update nf-schema to 3.0.0 and migrate `paramsHelp`, `paramsSummaryLog`, and `paramsSummaryMap` to their single-options-map signatures - [#164](https://github.com/nf-core/references/pull/164) - Replace `update_references_file` string rewriting with nf-schema `allowParamsSubstitution`, so datasheets can carry `${params.references_base_path}` placeholders - [#165](https://github.com/nf-core/references/pull/165) - Document `--references_base_path`, multiple genomes, and the asset file format in `docs/usage.md` +- [#167](https://github.com/nf-core/references/pull/167) - Document reference selection precedence for consuming pipelines in `docs/usage.md` ### Removed diff --git a/docs/usage.md b/docs/usage.md index ac9f86a7..3dcb8f05 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -229,6 +229,18 @@ The placeholder carries the leading slash, so the value must not end with one. A Datasheets without placeholders are unchanged and need no edit. This parameter only rewrites paths inside the datasheet; the location of the datasheet itself is set with `--input`. +### Reference selection in consuming pipelines + +A pipeline that consumes references resolves them from the first source that supplies a usable record. Any source may contribute any subset of keys, such as `fasta`, `fasta_fai`, `genome`, or `species`: + +- Explicit parameters, for example `--fasta` and `--fasta_fai`. +- A references datasheet, passed as a file, or located from a base URL plus a genome key. +- An iGenomes catalogue entry for the selected `--genome`. + +Each source runs only when the previous ones did not supply `fasta`, so an explicit parameter prevents an unnecessary datasheet fetch. Selecting a datasheet and selecting a catalogue entry at the same time is an error: the sources are mutually exclusive, and pipelines reject the combination rather than guess an order. + +Parameter names for these sources belong to each consuming pipeline and are documented in its own usage pages. nf-core/bamtofastq, for example, selects the datasheet with `--references` and the catalogue with `--genome` plus `--igenomes_ignore`, and points back here for this shared resolution order. + ## Running the pipeline The typical command for running the pipeline is as follows: From ec235d09062310e7c1eb02106034a2a4e9d33424 Mon Sep 17 00:00:00 2001 From: Maxime U Garcia Date: Wed, 28 Oct 2026 17:04:05 +0100 Subject: [PATCH 2/2] Clarify per-key reference resolution in usage docs Resolution is per key, the datasheet and iGenomes catalogue are one mutually exclusive step, and the section moves to its own top-level heading. Drop bamtofastq parameter names in favour of a link. Co-Authored-By: Claude Opus 5.5 --- docs/usage.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 84eaa20e..ff079a73 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -229,18 +229,6 @@ The placeholder carries the leading slash, so the value must not end with one. A Datasheets without placeholders are unchanged and need no edit. This parameter only rewrites paths inside the datasheet; the location of the datasheet itself is set with `--input`. -### Reference selection in consuming pipelines - -A pipeline that consumes references resolves them from the first source that supplies a usable record. Any source may contribute any subset of keys, such as `fasta`, `fasta_fai`, `genome`, or `species`: - -- Explicit parameters, for example `--fasta` and `--fasta_fai`. -- A references datasheet, passed as a file, or located from a base URL plus a genome key. -- An iGenomes catalogue entry for the selected `--genome`. - -Each source runs only when the previous ones did not supply `fasta`, so an explicit parameter prevents an unnecessary datasheet fetch. Selecting a datasheet and selecting a catalogue entry at the same time is an error: the sources are mutually exclusive, and pipelines reject the combination rather than guess an order. - -Parameter names for these sources belong to each consuming pipeline and are documented in its own usage pages. nf-core/bamtofastq, for example, selects the datasheet with `--references` and the catalogue with `--genome` plus `--igenomes_ignore`, and points back here for this shared resolution order. - ## Running the pipeline The typical command for running the pipeline is as follows: @@ -400,3 +388,14 @@ We recommend adding the following line to your environment to limit this (typica ```bash NXF_OPTS='-Xms1g -Xmx4g' ``` + +## Reference selection in consuming pipelines + +A pipeline that consumes these references resolves each key, such as `fasta` or `fasta_fai`, separately. Each key takes its value from the first source in this order that supplies it: + +1. Explicit parameters, for example `--fasta` and `--fasta_fai`. +2. One references datasheet or one iGenomes catalogue entry. The datasheet is passed as a file, or located from a base URL plus a genome key. Selecting both a datasheet and a catalogue entry is an error. + +An explicit `--fasta` with no `--fasta_fai` therefore takes `fasta_fai` from the datasheet or catalogue entry. + +Each consuming pipeline names its own parameters for these sources and documents them in its usage pages. See the [nf-core/bamtofastq usage documentation](https://nf-co.re/bamtofastq/usage) for an example.