Filling the documentation for your module

By adding a module to nf-neuro, you are contributing to a repository of modules that others can import into their Nextflow pipeline. Therefore, to make it easier for future users of your module, it is important to document it properly. This will be done using two different files: environment.yml and meta.yml. We will go through each of them in this current tutorial page.

Edit the environment.yml

This file is used by nf-core to manage conda environments for modules. It is not used by nf-neuro for now, but must be created following a basic format for your module to lint properly. Keeping the denoising/nlmeans as an example module, it should follow this specific schema:

name: denoising_nlmeans
channels: [] # Empty, since we do not use conda.
dependencies: [] # Empty, since we do not use conda.

Edit the meta.yml

This file is the core documentation behind your module, so it is important that you take time to complete it properly. Otherwise, it will be hard for future users to reuse your module. The first sections of the file contains basic informations regarding your modules:

---
name: "denoising_nlmeans" # Normally automically generated by nf-core tools.
description: |
  Denoise a dataset with the Non Local Means algorithm
keywords:
  - nifti
  - denoising
  - nlmeans
  - scilpy

The name section should be already correctly populated by the nf-core tools. In the description section, please provide a complete description of what your module does in terms of processing steps. Then, fill out the keywords section with the most appropriate keywords for your module.

The tools section will contain the name, the description, the homepage, and the DOI of all tools you use within your module. If the specific tool you use does not have some section, such as the DOI, you can simply leave it blank or remove it. For the denoising/nlmeans module, since we only use scilpy, we will add only add a single tool to this section:

tools:
  - "scilpy":
      description: "The Sherbrooke Connectivity Imaging Lab (SCIL) Python dMRI processing toolbox."
      homepage: "https://github.com/scilus/scilpy.git" # This can also be a link to a documentation website.

The next section will document the inputs of your module, starting by the metadata linking the files to a specific subject (if this is the case for your module). For each inputs, you will need to specify their name, their type, a description, and a pattern. For example, in the denoising/nlmeans module, we previously defined three inputs: the metadata for the subject, the image we want to denoise, and an optional mask.

input:
  - meta:
      type: map
      description: |
        Groovy Map containing sample information
        e.g. `[ id:'test', single_end:false ]`

  - image:
      type: file
      description: Nifti image file to denoise
      pattern: "*.{nii,nii.gz}"

  - mask:
      type: file
      description: Nifti image file used to mask the input image
      pattern: "*.{nii,nii.gz}"

Before documenting your outputs, you need to document which arguments can be supplied to your module to customize its behavior. This is done using the args section. For example, in the denoising/nlmeans module, we only have a single argument that can be passed to our modules (number_of_coils). Depending the type of your arguments, you will supply the type (typically string, float, int, or boolean), a description, a choices (if applicable), and the default value.

args:
  - number_of_coils:
      type: int
      description: The number of coils used during sequence acquisition.
      default: 1

Finally, it’s time to document the outputs of your module! This section is identical in its structure as the input section, but for your output.

output:
  - meta:
      type: map
      description: |
        Groovy Map containing sample information
        e.g. `[ id:'test', single_end:false ]`

  - image:
      type: file
      description: Denoised Nifti image file
      pattern: "*_denoised.{nii,nii.gz}"

  - versions:
      type: file
      description: File containing software versions
      pattern: "versions.yml"

There you go! Your module is now documented, and can be reuse by someone else in their work. Optionally, there is a last section authors you can fill out at the bottom of the meta.yml file. You can use your GitHub handle, or if you do not want to be identified the @scilus. Once you have completed everything, your meta.yml file should be similar to this:

---
name: "denoising_nlmeans"
description: denoise a dataset with the Non Local Means algorithm
keywords:
  - nifti
  - denoising
  - nlmeans
  - scilpy
tools:
  - "scilpy":
      description: "The Sherbrooke Connectivity Imaging Lab (SCIL) Python dMRI processing toolbox."
      homepage: "https://github.com/scilus/scilpy.git"

input:
  - meta:
      type: map
      description: |
        Groovy Map containing sample information
        e.g. `[ id:'test', single_end:false ]`

  - image:
      type: file
      description: Nifti image file to denoise
      pattern: "*.{nii,nii.gz}"

  - mask:
      type: file
      description: Nifti image file used to mask the input image
      pattern: "*.{nii,nii.gz}"

args:
  - number_of_coils:
      type: int
      description: The number of coils used during sequence acquisition.
      default: 1

output:
  - meta:
      type: map
      description: |
        Groovy Map containing sample information
        e.g. `[ id:'test', single_end:false ]`

  - image:
      type: file
      description: Denoised Nifti image file
      pattern: "*_denoised.{nii,nii.gz}"

  - versions:
      type: file
      description: File containing software versions
      pattern: "versions.yml"

authors:
  - "@scilus"

Then, to look at the documentation it creates for your module, run :

nf-core modules info <category/name>

You are now done! You can now create test case for your module!