diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d039e25..e4ecfc54 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -71,6 +71,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - [#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` - [#166](https://github.com/nf-core/references/pull/166) - Rename the datasheet `source`, `source_version`, and derived `source_vcf` meta fields to `reference_source`, `annotation_version`, and `annotation_source` (#65) +- [#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 3b7c697a..ff079a73 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -388,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.