Metadata documentation

Documentation for nf-neuro is autogenerated from the content of the main.nf file and a special metadata file named meta.yml. This file is located in the root of your module, and documents the inputs, outputs, arguments and dependencies of your module, as well as other useful fields used to construct an API and CLI outputs. Here, we’ll go through the different fields that are required to be filled out.

The `description` field

Each module requires a thourough description of it main purpose, its configuration and its behaviors. Here is a good example for the denoising/nlmeans module:

name: "denoising_nlmeans"
description: |
  Denoise a dataset with the Non Local Means algorithm. The Non Local Means algorithm is a denoising algorithm that uses
  the similarity between patches of the image to denoise it. It is based on the assumption that similar patches in the
  image should have similar intensities. The algorithm supports various noise estimation methods and is sensitive to the
  number of coils used during the acquisition.

The `keywords` field

The keywords field is a list of keywords that describe the module and will help users find him through search tools such as the ones included on this website. The keywords should be relevant to the module and its purpose. For example, for the denoising/nlmeans module, the following keywords cover the purpose well :

---
name: "denoising_nlmeans"
description: |
  Denoise a dataset with the Non Local Means algorithm. The Non Local Means algorithm is a denoising algorithm that uses
  ...
keywords:
  - nifti
  - denoising
  - non-local
  - means
  - patch
  - intensity

The `tools` field

In the tools section, you describe each and every dependency included in the script and the versions.yml file. This section is a simple list of named entries, one for each tool, with a short description and a homepage link. Additionnally, if the tool is published with a DOI, you can add it to the DOI field. For the nlmeans module, the section describe scilpy :

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

The `args` field

The args section documents which arguments can be supplied to your module via task.ext to customize its behavior. Depending the kind of argument, you will need to supply a type (typically string, float, int, or boolean), a description, a choices (a list of possible values), and a default value. For the denoising/nlmeans module, the arguments are number_of_coils, sigma, sigma_from_all_voxels, gaussian and method. Refer to the example below to define them :

---
name: "denoising_nlmeans"
description: |
  ...
keywords:
  ...
tools:
  ...
args:
  - number_of_coils:
      type: int
      description: The number of coils used during sequence acquisition.
      default: 1
  - sigma:
      type: float
      description: The noise standard deviation. Overrides automatic estimation.
      default: null
  - sigma_from_all_voxels:
      type: boolean
      description: Use all voxels to estimate the noise standard deviation.
      default: false
  - gaussian:
      type: boolean
      description: Use a Gaussian kernel for the denoising.
      default: false
  - method:
      type: string
      description: The method used to estimate the noise standard deviation.
      choices:
        - basic_sigma
        - piesno
      default: basic_sigma

The `input` field

The next section documents the inputs of your module. It contains an entry for every input channel, specifying the name, type, description, pattern and if it is optional. If the channel’s elements are defined as tuple, its metadata description will be a list of entries as well. For the denoising/nlmeans module, we defined 3 inputs :

---
name: "denoising_nlmeans"
description: |
  ...
keywords:
  ...
tools:
  ...
args:
  ...
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}"
        optional: true
    - noise_mask:
        type: file
        description: Nifti image file used to estimate the noise standard deviation
        pattern: "*.{nii,nii.gz}"
        optional: true

The `output` field

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. In the case of the Non-Local Means module, we have 3 outputs :

---
name: "denoising_nlmeans"
description: |
  ...
keywords:
  ...
tools:
  ...
args:
  ...
input:
  ...
output:
  - image:
    - meta:
        type: map
        description: |
          Groovy Map containing sample information
          e.g. `[ id:'test', single_end:false ]`
    - "*__denoised.{nii,nii.gz}":
        type: file
        description: Denoised Nifti image file
        pattern: "*__denoised.{nii,nii.gz}"
  - noise_mask:
    - meta:
        type: map
        description: |
          Groovy Map containing sample information
          e.g. `[ id:'test', single_end:false ]`
    - "*__piesno_noise_mask.{nii,nii.gz}":
        type: file
        description: Nifti image file used to estimate the noise standard deviation
        pattern: "*__piesno_noise_mask.{nii,nii.gz}"
        optional: true
  - 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. The Non Local Means algorithm is a denoising algorithm that uses
  the similarity between patches of the image to denoise it. It is based on the assumption that similar patches in the
  image should have similar intensities. The algorithm supports various noise estimation methods and is sensitive to the
  number of coils used during the acquisition.
keywords:
  - nifti
  - denoising
  - non-local
  - means
  - patch
  - intensity
tools:
  - "scilpy":
      description: "The Sherbrooke Connectivity Imaging Lab (SCIL) Python dMRI processing toolbox."
      homepage: "https://github.com/scilus/scilpy"
args:
  - number_of_coils:
      type: int
      description: The number of coils used during sequence acquisition.
      default: 1
  - sigma:
      type: float
      description: The noise standard deviation. Overrides automatic estimation.
      default: null
  - sigma_from_all_voxels:
      type: boolean
      description: Use all voxels to estimate the noise standard deviation.
      default: false
  - gaussian:
      type: boolean
      description: Use a Gaussian kernel for the denoising.
      default: false
  - method:
      type: string
      description: The method used to estimate the noise standard deviation.
      choices:
        - basic_sigma
        - piesno
      default: basic_sigma
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}"
        optional: true
    - noise_mask:
        type: file
        description: Nifti image file used to estimate the noise standard deviation
        pattern: "*.{nii,nii.gz}"
        optional: true
output:
  - image:
    - meta:
        type: map
        description: |
          Groovy Map containing sample information
          e.g. `[ id:'test', single_end:false ]`
    - "*__denoised.{nii,nii.gz}":
        type: file
        description: Denoised Nifti image file
        pattern: "*__denoised.{nii,nii.gz}"
  - noise_mask:
    - meta:
        type: map
        description: |
          Groovy Map containing sample information
          e.g. `[ id:'test', single_end:false ]`
    - "*__piesno_noise_mask.{nii,nii.gz}":
        type: file
        description: Nifti image file used to estimate the noise standard deviation
        pattern: "*__piesno_noise_mask.{nii,nii.gz}"
        optional: true
  - 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!

Metadata documentation

The description field

The keywords field

The tools field

The args field

The input field

The output field