Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add script recommendations #2888

Merged
merged 15 commits into from
Dec 18, 2024
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions sites/docs/src/content/docs/guidelines/components/modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -324,6 +324,64 @@ See the [Bash manual on file operators](https://tldp.org/LDP/abs/html/fto.html)

Alternate suggestions include using `grep -c` to search for a valid string match, or other tool which will appropriately error when the expected output is not successfully created.

### Script inclusion

:::note
pinin4fjords marked this conversation as resolved.
Show resolved Hide resolved
You SHOULD NOT use [Nextflow module binaries](https://www.nextflow.io/docs/latest/module.html#module-binaries) where possible, as these are not fully portable across all execution contexts.
pinin4fjords marked this conversation as resolved.
Show resolved Hide resolved
:::

If a module's `script:` block contains not command invocations, but script content, whatever the language (e.g. Bash, R, Python), and if that content is non-trivial in length (>> 10 lines), that MUST be supplied via a [Nextflow module template](https://www.nextflow.io/docs/latest/module.html#module-templates). This makes it clearer when changes have been made to the scientific logic in the script, or to the workflow-relevant logic in the module.
pinin4fjords marked this conversation as resolved.
Show resolved Hide resolved

#### Template location
pinin4fjords marked this conversation as resolved.
Show resolved Hide resolved

The template MUST go in a directory called `templates/` that sits alongside the `main.nf` of the module.
pinin4fjords marked this conversation as resolved.
Show resolved Hide resolved

The template file MUST be named after module itself with a language appropriate file suffix. e.g. the `deseq2/differential` nf-core module will use the `deseq2_differential.R`
jfy133 marked this conversation as resolved.
Show resolved Hide resolved

The template file can be referred to within the module itself using the following notation:
jfy133 marked this conversation as resolved.
Show resolved Hide resolved

```nextflow
script:
template 'deseq2_differential/R'
jfy133 marked this conversation as resolved.
Show resolved Hide resolved
```

An example can be seen with `deseq2/differential` [here](https://github.com/nf-core/modules/blob/master/modules/nf-core/deseq2/differential/main.nf#L47).
jfy133 marked this conversation as resolved.
Show resolved Hide resolved

The resulting structure would look like this.

```tree
deseq2
└── differential
├── environment.yml
├── main.nf
├── meta.yml
├── templates
│   └── deqseq2_differential.R
└── tests
├── main.nf.test
├── main.nf.test.snap
└── tags.yml
```

#### Template contents
pinin4fjords marked this conversation as resolved.
Show resolved Hide resolved

:::warning
Be aware that in any script template that Nextflow needs to be escaped in the same way you would in a standard bash `script:` block!
:::

The script template file MUST generate a `versions.yml` file in the language-appropriate way that contains versions of the base language and all relevant libraries and packages.
pinin4fjords marked this conversation as resolved.
Show resolved Hide resolved

The generated `versions.yml` MUST have the same structure as a standard nf-core module `versions.yml`.

For example, for R you can refer to the `deseq2/differential` module [here](https://github.com/nf-core/modules/blob/4c2d06a5e79abf08ba7f04c58e39c7dad75f094d/modules/nf-core/deseq2/differential/templates/deseq_de.R#L509-L534).
jfy133 marked this conversation as resolved.
Show resolved Hide resolved

#### Script template stub
pinin4fjords marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Member

@jfy133 jfy133 Dec 9, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#### Script template stub
#### Module template stub


A script template module MUST also include a stub block following a standard nf-core module structure (i.e., using e.g. `touch` to generate empty files, and versions. You can see the `deseq2/differential` module example [here](https://github.com/nf-core/modules/blob/4c2d06a5e79abf08ba7f04c58e39c7dad75f094d/modules/nf-core/deseq2/differential/main.nf#L34-L49).
pinin4fjords marked this conversation as resolved.
Show resolved Hide resolved

An inline command to call the version for libraries for the `versions.yml` MAY be used in this case. For an R example see [deseq2/differential](https://github.com/nf-core/modules/blob/4c2d06a5e79abf08ba7f04c58e39c7dad75f094d/modules/nf-core/deseq2/differential/main.nf#L47).
pinin4fjords marked this conversation as resolved.
Show resolved Hide resolved


### Stubs

#### Stub block must exist
Expand Down
Loading