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 subworkflow, and documents the inputs, outputs, parameters and dependencies of your subworkflow, as well as other useful fields.

All of this content is extemely valuable ! We use it among others to generate the nf-neuro API and usage outputs for command line interfaces (CLI). All this really helps users and developers understand the purpose of your subworkflow, its configuration and its behaviors.

The description field

Each subworkflow requires a thourough description of it main purpose, its configuration and its behaviors. In addition, the description should contain a consise explanation of the dataflow between the modules and other subworkflows used. Here is a good example for preproc_anat :

name: "preproc_anat"
description: |
  Complete preprocessing workflow for anatomical MRI images (e.g. T1w, T2w, FLAIR, quantitative). The following steps
  are performed :
    [ DENOISING_NLMEANS       ] (optional) Denoise the anatomical image with the Non-Local Means algorithm.
    [ BETCROP_SYNTHBET        ] (optional) Compute a synthetic brain mask to improve downstream processing.
    [ PREPROC_N4              ] (optional) Correct intensity biases on the anatomical image, inside the synthetic mask.
    [ BETCROP_ANTSBET         ] Compute a robust brain mask based on a population template.
    [ ANATOMICAL_SEGMENTATION ] Segment the anatomical image into different tissue types (GM, WM, CSF).

The keywords field

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

---
name: "preproc_anat"
description: |
  Complete preprocessing workflow for anatomical MRI images (e.g. T1w, T2w, FLAIR, quantitative). The following steps
  ...
keywords:
  - anatomical
  - preprocessing
  - denoising
  - normalization
  - intensity
  - mask
  - segmentation

The components field

The components field is a list of all the modules, then all subworkflows, included in the main.nf file :

---
name: "preproc_anat"
description: |
  Complete preprocessing workflow for anatomical MRI images (e.g. T1w, T2w, FLAIR, quantitative). The following steps
  ...
keywords:
  - anatomical
  ...
components:
  - betcrop/antsbet
  - betcrop/synthbet
  - denoising/nlmeans
  - preproc/n4
  - anatomical_segmentation

The args field

The args field is a list of all the parameters (params) defined for the subworkflow. Parameters defined in included components MUST also be described here, unless they SHOULD be hidden. For the preproc_anat subworkflow, use the following :

---
name: "preproc_anat"
description: |
  ...
keywords:
  ...
components:
  ...
args:
  - preproc_anat_denoise:
      type: boolean
      description: Denoise the anatomical image with the Non-Local Means algorithm.
      default: true
  - preproc_anat_bet_before_n4:
      type: boolean
      description: Perform brain extraction before intensity normalization.
      default: true
  - preproc_anat_n4:
      type: boolean
      description: Perform intensity normalization on the anatomical image.
      default: true
  - preproc_anat_nlmeans_number_of_coils:
      type: int
      description: Number of receive coils used to acquire the anatomical image.
      default: 1
  - preproc_anat_nlmeans_sigma:
      type: float
      description: Noise standard deviation. Overrides automatic estimation.
      default: null
  - preproc_anat_nlmeans_sigma_from_all_voxels:
      type: boolean
      description: Use all voxels to estimate the noise standard deviation.
      default: false
  - preproc_anat_nlmeans_gaussian:
      type: boolean
      description: Use a Gaussian kernel for the denoising.
      default: false
  - preproc_anat_nlmeans_method:
      type: string
      description: The method used to estimate the noise standard deviation.
      choices:
        - basic_sigma
        - piesno
      default: basic_sigma
  - preproc_anat_betcrop_synthbet_border:
      type: int
      description: The border width to use for the synthetic brain mask.
      default: 10
  - preproc_anat_betcrop_synthbet_nocsf:
      type: boolean
      description: Do not estimate the CSF to compute the synthetic brain mask.
      default: false
  - preproc_anat_n4_knots_per_voxel:
      type: float
      description: Number of bias field knots per voxel to use for intensity normalization.
      default: 1
  - preproc_anat_n4_shrink_factor:
      type: int
      description: Resolution downsampling factor to use for intensity normalization.
  - run_synthbet:
      type: boolean
      description: (ANATOMICAL_SEGMENTATION) Run the synthetic brain extraction step.
      default: false

The input field

The input field lists all input channels in order. Each entry defines the content structure of an input channel in a list of maps. For the preproc_anat subworkflow, there are 8 inputs to document :

---
name: "preproc_anat"
description: |
  ...
keywords:
  ...
components:
  ...
args:
  ...
input:
  - ch_anatomical:
      description: Input anatomical image to preprocess.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - image:
            type: file
            description: Nifti anatomical image.
  - ch_template:
      description: Input template image to use for the ANTs brain extraction.
      structure:
        - reference:
            type: file
            description: Nifti reference anatomical template.
        - probabilities:
            type: file
            description: Nifti brain probability map.
  - ch_brain_mask:
      description: (Optional) Input brain mask. If provided, all brain extraction steps are skipped.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - mask:
            type: file
            description: Nifti brain mask.
  - ch_synthbet_weights:
      description: (Optional) Input weights for the synthetic brain mask extraction.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - weights:
            type: file
            description: Nifti weights image.
  - ch_n4_reference:
      description: (Optional) Input reference image onto which estimate the bias field.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - reference:
            type: file
            description: Nifti reference image.
  - ch_freesurferseg:
      description: (Optional) Input segmentation maps from FreeSurfer.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - aparc_aseg:
            type: file
            description: Nifti FreeSurfer brain parcellation and segmentation.
        - wmparc:
            type: file
            description: Nifti FreeSurfer white matter parcellation.
  - ch_lesion:
      description: (Optional) Input lesion mask.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - lesion:
            type: file
            description: Nifti lesion mask.
  - ch_fs_license:
      description: (Optional) Input FreeSurfer license file.
      structure:
        - license:
            type: file
            description: FreeSurfer license file.

The output field

Finally, it’s time to document the output, the last metadata section ! They are mostly structured the same way as the input, with files having an aditional pattern field describing their naming convention and possible formats. The section MUST always include the following entry for the versions.yml file :

- versions:
    description: Channel containing software versions file.
    structure:
        - versions.yml:
            type: file
            description: File containing versions of the software used.
            pattern: "versions.yml"

Just like inputs, outputs MUST be given in the same order they are found in the subworkflow’s emit section. Here is the complete output section for the preproc_anat subworkflow :

---
name: "preproc_anat"
description: |
  ...
keywords:
  ...
components:
  ...
args:
  ...
input:
  ...
output:
  - ch_anatomical:
      description: Channel containing the preprocessed anatomical image.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - "*.{nii,nii.gz}":
            type: file
            description: Preprocessed Nifti anatomical image.
            pattern: "*.{nii,nii.gz}"
  - ch_brain_mask:
      description: Channel containing the brain mask.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - "*t1_bet_mask.{nii,nii.gz}":
            type: file
            description: Nifti brain mask.
            pattern: "*t1_bet_mask.{nii,nii.gz}"
  - ch_wm_mask:
      description: Channel containing the white matter mask.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - "*mask_wm.{nii,nii.gz}":
            type: file
            description: Nifti white matter mask.
            pattern: "*mask_wm.{nii,nii.gz}"
  - ch_gm_mask:
      description: Channel containing the gray matter mask.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - "*mask_gm.{nii,nii.gz}":
            type: file
            description: Nifti gray matter mask.
            pattern: "*mask_gm.{nii,nii.gz}"
  - ch_csf_mask:
      description: Channel containing the CSF mask.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - "*mask_csf.{nii,nii.gz}":
            type: file
            description: Nifti CSF mask.
            pattern: "*mask_csf.{nii,nii.gz}"
  - ch_wm_map:
      description: Channel containing the white matter map.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - "*wm_map.{nii,nii.gz}":
            type: file
            description: Nifti white matter map.
            pattern: "*wm_map.{nii,nii.gz}"
  - ch_gm_map:
      description: Channel containing the white matter map.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - "*gm_map.{nii,nii.gz}":
            type: file
            description: Nifti white matter map.
            pattern: "*gm_map.{nii,nii.gz}"
  - ch_csf_map:
      description: Channel containing the white matter map.
      structure:
        - meta:
            type: map
            description: Metadata map.
        - "*csf_map.{nii,nii.gz}":
            type: file
            description: Nifti white matter map.
            pattern: "*csf_map.{nii,nii.gz}"
  - versions:
      description: Channel containing software versions file.
      structure:
          - versions.yml:
              type: file
              description: File containing versions of the software used.
              pattern: "versions.yml"

And with that, you are done with the metadata file ! There are still two fields remaining, for authors and maintainers, but they are not mandatory. Edit them as you please, they are bound to change as other contributors modify the subworkflow in the future.