Outputs

The directories listed below will be created in the results directory after the pipeline has finished. All paths are relative to the top-level results directory. The pipeline outputs results in a BIDS-like structure (BIDS derivatives are not officially described and accepted in the BIDS specification, so don’t hesitate to open an issue if something should be changed). As such, your root output folder will contain one folder per subject.

• Directorynf-pediatric-v0.1.0/

  • dataset_description.json
  • Directorymultiqc/

    • …
  • Directorysub-0001/

    • Directoryses-session/

      • Directoryanat/

        • …
      • Directorydwi/

        • …
      • Directoryfigures/

        • …
      • Directorymultiqc/

        • …
    • Directoryses-session2/

      • …
  • Directorysub-0002/

    • Directoryses-session/

      • Directoryanat/

        • …
      • Directorydwi/

        • …
      • Directoryfigures/

        • …
      • Directorymultiqc/

        • …
    • Directoryses-session2/

      • …
  • …

The pipeline will output only the final preprocessed files by default. This behavior is used to limit the number of files generated by the pipeline by omitting the publishing of intermediate results. It is particularly useful when running the pipeline on clusters where file quotas are often rapidly met. To opt-out from the lean output version (not recommended), set the --lean_output parameter to false when launching the pipeline (e.g., --lean_output false).

If you decided to run FreeSurfer (both recon-all or recon-all-clinical), FastSurfer, or M-CRIB-S as part of nf-pediatric, your output will be located (by default) alongside the nf-pediatric output folder. You can select the destination folder by using the --fs_output_dir parameter. If you do not specify and output folder destination, it will look like this:

• Directorynf-pediatric-v0.1.0/

  • multiqc
  • sub-0001
  • sub-0002
  • …
• Directoryfastsurfer-v2.3.3/

  • sub-0001
  • sub-0002
  • …

Pipeline overview

The pipeline is built using Nextflow and data processing steps can be grouped. The final output files are listed below for each of those steps. If you used --lean_output false, you will find additional files than the ones described here (not recommended, this will highly increase the number of output files).

Sidecar JSON files

In addition to the output files described below, you will also find sidecar JSON file for nifti volumes. Those will contain informations regarding their source (either raw or processed), the applied transforms, and/or processing steps.

• T1w/T2w Preprocessing - Preprocess anatomical images (denoising, normalization, etc.)
• DWI Preprocessing - Preprocess DWI images (denoising, susceptibility correction, normalization, etc.)
• Local Modelling - Fit DTI and fODF models based on the diffusion signal.
• Registration - Register the T1w/T2w images in diffusion space.
• Segmentation - Perform anatomical segmentation of tissues.
• Tractography - Perform either local or PFT tracking.
• Connectomics - Perform tractogram segmentation, filtering, and metrics computation.
• FreeSurfer - Perform T1w reconstruction using FreeSurfer and map the Brainnetome Child atlas in subject space.
• MultiQC - Gather run informations, provide methods boilerplate and software versions list.
• Pipeline information - Report metrics generated during the workflow execution

T1w/T2w Preprocessing

Output files

• anat/
  • *_desc-preproc_T1w.nii.gz: Final preprocessed T1w image in original space.
  • *_desc-preproc_T2w.nii.gz: Final preprocessed T2w image in original space.
  • *_space-T2w_desc-preproc_T1w.nii.gz: Final preprocessed T1w image in T2w space (if infant data).
  • *_space-T1w_desc-preproc_T2w.nii.gz: Final preprocessed T2w image in T1w space (if pediatric data).
  • *_from-{T1w,T2w}_to-{T1w,T2w}_affine.mat: Affine transform from T1w/T2w to T1w/T2w space.
  • *_space-{template}_desc-preproc_T1w.nii.gz: Final preprocessed T1w image in template space (if a destination template has been selected).
  • *_space-{template}_desc-preproc_T2w.nii.gz: Final preprocessed T2w image in template space (if a destination template has been selected).
  • *_from-dwi_to-{template}_affine.mat: Affine transform from T1w/T2w to template space.
  • *_from-dwi_to-{template}_warp.nii.gz: Non-linear transform from T1w/T2w to template space.

DWI Preprocessing

Output files

• dwi/
  • *_desc-preproc_dwi.nii.gz: Final preprocessed DWI image in original space.
  • *_desc-preproc_dwi.bval: Final b-values file.
  • *_desc-preproc_dwi.bvec: Final corrected b-vectors file.
  • *_desc-preproc_b0.nii.gz: Final preprocessed B0 image.
  • *_desc-brain_mask.nii.gz: Final brain mask in original space.

Local Modelling

Output files

• dwi/
  • *_{space-template}_desc-ad.nii.gz: Axial Diffusivity map.
  • *_{space-template}_desc-rd.nii.gz: Radial Diffusivity map.
  • *_{space-template}_desc-md.nii.gz: Mean Diffusivity map.
  • *_{space-template}_desc-fa.nii.gz: Fractional Anisotropy map.
  • *_{space-template}_desc-mode.nii.gz: Mode map.
  • *_{space-template}_desc-ga.nii.gz: Geodesic Anisometry map.
  • *_desc-tensor.nii.gz: Tensor map.
  • *_{space-template}_desc-rgb.nii.gz: RGB map.
  • *_desc-fodf.nii.gz: Fiber oriented distribution functions (fODF).
  • *_{space-template}_desc-afd_max.nii.gz: Maximum apparent fiber density (AFD) map.
  • *_{space-template}_desc-afd_sum.nii.gz: Sum of the AFD map.
  • *_{space-template}_desc-afd_total.nii.gz: AFD total map.
  • *_{space-template}_desc-nufo.nii.gz: Number of fiber orientation map.
  • *_desc-peaks.nii.gz: fODF peaks.

Registration

Output files

• anat/
  • *_from-{T2w,T1w}_to-dwi_affine.mat: Affine transform from T1w/T2w space to diffusion space.
  • *_from-{T2w,T1w}_to-dwi_warp.nii.gz: Non-linear transform from T1w/T2w space to diffusion space.
  • *_from-dwi_to-{T2w,T1w}_warp.nii.gz: Non-linear transform from diffusion space to T1w/T2w space.
  • *_space-DWI_desc-preproc_{T2w,T1w}.nii.gz: Preprocessed T1w/T2w image in diffusion space.

Segmentation

Output files

• anat/
  • *_space-DWI_label-WM_mask.nii.gz: WM mask in diffusion space.
  • *_space-DWI_label-GM_mask.nii.gz: GM mask in diffusion space.
  • *_space-DWI_label-CSF_mask.nii.gz: CSF mask in diffusion space.
  • *_space-DWI_label-WM_probseg.nii.gz: WM probability map in diffusion space.
  • *_space-DWI_label-GM_probseg.nii.gz: GM probability map in diffusion space.
  • *_space-DWI_label-CSF_probseg.nii.gz: CSF probability map in diffusion space.

Tractography

Output files

• dwi/
  • *_{space-template}_desc-local_tractogram.trk: Whole-brain tractogram using local tractography.
  • *_{space-template}_desc-pft_tractogram.trk: Whole-brain tractogram using PFT tractography.
  • *_{space-template}_desc-concatenated_tractogram.trk: Whole-brain tractogram combining both PFT/local tracking.
  • *_space-DWI_label-exclude_desc-pft_probseg.nii.gz: Exclude probability map for PFT tracking.
  • *_space-DWI_label-include_desc-pft_probseg.nii.gz: Include probability map for PFT tracking.
  • *_space-DWI_label-seeding_desc-local_mask.nii.gz: Seeding mask for local tracking.
  • *_space-DWI_label-tracking_desc-local_mask.nii.gz: Tracking mask for local tracking.
  • *_space-DWI_label-seeding_desc-pft_mask.nii.gz: Seeding mask for PFT tracking.

Bundling

Output files

• dwi/bundles/

  • *_desc-{bundleName}.trk: Single .trk file for each of the recognized bundle. Those are cleaned, uniformized, and colored (only affect visualization).

• dwi/

  • *_desc-{statsName}.json: Various .json file for each metric type containing values for each bundles for the current subject. Will be subject to change in the near future for .tsv files, which are easier to work with in subsequent statistical analysis.

Connectomics

Output files

• dwi/

  • *_{space-template}_seg-{BrainnetomeChild,DKT}_desc-filtered_tracking.{trk,h5}: Filtered whole-brain tractogram.
  • *_{space-template}_seg-{BrainnetomeChild,DKT}_desc-preproc_tracking.h5: Final preprocessed decomposed whole-brain tractogram.
  • *.npy: Connectivity matrices for all supplied metrics.
  • *.png: Connectivity matrices visualized as pngs.

• anat/

  • *_space-DWI_seg-{BrainnetomeChild,DKT}_dseg.nii.gz: Atlas labels in diffusion space. Name of the atlas might changed depending on which one is used.

FreeSurfer/FastSurfer/M-CRIB-S

Output files

• anat/
  • *_seg-BrainnetomeChild_desc-labels.json: JSON file containing the labels information.
  • *_seg-BrainnetomeChild_desc-labels.txt: Text file containing the labels information.
  • *_{space-template}_seg-BrainnetomeChild_dseg.nii.gz: Atlas label file in subject original space.
  • *_seg-BrainnetomeChild_dseg_dilated: Dilated atlas label file in subject original space.
  • *_seg-BrainnetomeChild_stat-subcortical.tsv: Subcortical statistics file.
  • *_seg-BrainnetomeChild_stat-{lh,rh}_{area,thickness,volume}.tsv: Left hemisphere statistics file.
  • *_seg-BrainnetomeChild_stat-{lh,rh}_{area,thickness,volume}.tsv: Right hemisphere statistics file.

MultiQC

Output files

• multiqc/
  • multiqc_report.html: a standalone HTML file that can be viewed in your web browser.
  • multiqc_data/: directory containing parsed statistics from the different tools used in the pipeline.
  • multiqc_plots/: directory containing static images from the report in various formats.

MultiQC is a visualization tool that generates HTML reports on the subject-level and reports on population-level statistics. In your output folder, you will find a global MultiQC report (located next to your sub-XXXX folders). This is the population level report, containing statistics allowing the evaluation of outliers in terms of white matter coverage, number of streamlines, and volume, thickness, and surface area for each regions of the GM parcellation.

Within each subject folder, you will find subject-specific HTML reports. Those will display visual QC of some of the key processing steps performed during the pipeline execution. Those figures (for now) comprise: sphere sampling, tissue segmentation, white matter coverage, labels overlay on anatomical image, and metrics maps visualization. You can refer to those subject-specific reports to obtain a quick overview of the quality of the processing.

Pipeline information

Output files

• pipeline_info/
  • Reports generated by Nextflow: execution_report.html, execution_timeline.html, execution_trace.txt and pipeline_dag.dot/pipeline_dag.svg.
  • Reports generated by the pipeline: pipeline_report.html, pipeline_report.txt and software_versions.yml. The pipeline_report* files will only be present if the --email / --email_on_fail parameter’s are used when running the pipeline.
  • Parameters used by the pipeline run: params.json.

Nextflow provides excellent functionality for generating various reports relevant to the running and execution of the pipeline. This will allow you to troubleshoot errors with the running of the pipeline, and also provide you with other information such as launch commands, run times and resource usage.