Skip to content

Latest commit

 

History

History
213 lines (157 loc) · 10 KB

output.md

File metadata and controls

213 lines (157 loc) · 10 KB

nf-pediatric: Output

Introduction

This document describes the output produced by the pipeline. Most of the plots are taken from the MultiQC report, which summarises results at the end of the pipeline.

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 (still WIP, don't hesitate to open an issue if needed). As such, your root output folder will contain one folder per subject.

<outdir>
  |-- multiqc
  |-- sub-0001
  |     |-- anat
  |     |-- dwi
  |     |-- figures
  |     └-- multiqc
  |-- sub-0002
  |     |-- anat
  |     |-- dwi
  |     |-- figures
  |     └-- multiqc
  <...>

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 files. It is particularly useful when running the pipeline on clusters where file quota are often rapidly met. To opt-out from the lean output version, set the --lean_output parameter to false when launching the pipeline (--lean_output false).

If you decided to run FreeSurfer or FastSurfer 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:

<your-nf-pediatric-outdir>
  |-- multiqc
  |-- sub-0001
  |-- sub-0002
  <...>
fastsurfer-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.

  • 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/
    • *_space-orig_desc-preproc_T1w.nii.gz: Final preprocessed T1w image in original space.
    • *_space-orig_desc-T1w_mask.nii.gz: Final brain mask in original space.
    • *_space-orig_desc-preproc_T2w.nii.gz: Final preprocessed T2w image in original space.

DWI Preprocessing

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

Local Modelling

Output files
  • dwi/
    • *_space-orig_ad.nii.gz: Axial Diffusivity map.
    • *_space-orig_rd.nii.gz: Radial Diffusivity map.
    • *_space-orig_md.nii.gz: Mean Diffusivity map.
    • *_space-orig_fa.nii.gz: Fractional Anisotropy map.
    • *_space-orig_mode.nii.gz: Mode map.
    • *_space-orig_ga.nii.gz: Geodesic Anisometry map.
    • *_space-orig_tensor.nii.gz: Tensor map.
    • *_space-orig_rgb.nii.gz: RGB map.
    • *_space-orig_fodf.nii.gz: Fiber oriented distribution functions (fODF).
    • *_space-orig_afd_max.nii.gz: Maximum apparent fiber density (AFD) map.
    • *_space-orig_afd_sum.nii.gz: Sum of the AFD map.
    • *_space-orig_afd_total.nii.gz: AFD total map.
    • *_space-orig_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-diff_desc-preproc_{T2w,T1w}.nii.gz: Preprocessed T1w/T2w image in diffusion space.

Segmentation

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

Tractography

Output files
  • dwi/
    • *_space-diff_desc-local_tracking.nii.gz: Whole-brain tractogram using local tractography.
    • *_space-orig_desc-pft_tracking.nii.gz: Whole-brain tractogram using PFT tractography.
    • *_space-diff_label-exclude_desc-pft_probseg.nii.gz: Exclude probability map for PFT tracking.
    • *_space-diff_label-include_desc-pft_probseg.nii.gz: Include probability map for PFT tracking.
    • *_space-diff_label-seeding_desc-local_mask.nii.gz: Seeding mask for local tracking.
    • *_space-diff_label-tracking_desc-local_mask.nii.gz: Tracking mask for local tracking.
    • *_space-diff_label-seeding_desc-pft_mask.nii.gz: Seeding mask for PFT tracking.

Connectomics

Output files

  • dwi/

    • *_space-diff_desc-filtered_tracking.{trk,h5}: Filtered whole-brain tractogram.
    • *_space-orig_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-diff_seg-BrainnetomeChild_dseg.nii.gz: Atlas labels in diffusion space. Name of the atlas might changed depending on which one is used.

FreeSurfer

Output files
  • anat/
    • *_{reconall,fastsurfer}: FreeSurfer style output folder for either reconall or fastsurfer.
    • *_space-orig_seg-BrainnetomeChild_desc-labels.json: JSON file containing the labels information.
    • *_space-orig_seg-BrainnetomeChild_desc-labels.txt: Text file containing the labels information.
    • *_space-orig_seg-BrainnetomeChild_dseg.nii.gz: Atlas label file in subject original space.
    • *_space-orig_seg-BrainnetomeChild_dseg_dilated: Dilated atlas label file in subject original space.
    • *_space-orig_seg-BrainnetomeChild_stat-subcortical.stats: Subcortical statistics file.
    • *_space-orig_seg-BrainnetomeChild_stat-lh.stats: Left hemisphere statistics file.
    • *_space-orig_seg-BrainnetomeChild_stat-rh.stats: 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.

Still under construction, report is experimental for now.

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 Brainnetome Child Atlas.

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.
    • Reformatted samplesheet files used as input to the pipeline: samplesheet.valid.csv.
    • 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.