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 (below sf-tractomics-v0.1.0 used as example). 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.

• Directorysf-tractomics-v0.1.0/

  • Directorypipeline_info/ # Global informations on the run

    • …
  • Directorystats/ # Global statistics on the run

    • …
  • Directorymultiqc/ # Global MultiQC report

    • …
  • Directorysub-0001/

    • Directoryses-1/ # Session level is created when provided

      • Directoryanat/ # Clean T1w in diffusion space

        • …
      • Directorydwi/ # All clean DWI files, models, tractograms, …

        • Directorybundles/ # Extracted bundles when using bundling

          • …
      • Directoryxfm/ # Transforms between diffusion and anatomy

        • …
      • Directorymultiqc/ # Participant MultiQC report

        • …
    • …
  • …
• Directorywork/

  • …

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.

Results

The pipeline creates 2 folders: the result folder specified by the --outdir parameter and the work folder. The files in the result folder are symlinks into work. To transfert or copy-paste the results folder, please use one of the following commands. We use sf-tractomics-v0.1.0 as the result folder name, but you might have to change it to your own :

On local computer

Command

cp -rL sf-tractomics-v0.1.0 NEW_PATH/results

On HPC

Command

rsync -rL login@adress:/HPC_PATH/sf-tractomics-v0.1.0 NEW_PATH/results

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.

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.

• Anatomy Preprocessing - Preprocess T1w 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 Allen Mouse Brain Atlas in diffusion space.
• Segmentation - Perform anatomical segmentation of tissues.
• Tractography - Perform either local tracking in subject space.
• Bundling - Perform bundling of common white matter tracts.
• Advanced Modelling - Fit Noddi and Freewater elimination models.
• Tractometry - Compute statistics using metrics from modeling and bundles.
• MultiQC - Includ pre-QC. Gather run informations, provide methods boilerplate and software versions list.
• Pipeline information - Report metrics generated during the workflow execution

Anatomy Preprocessing

Output files

• anat/
  • *_desc-brain_mask.nii.gz : Final brain mask in diffusion space.
  • *_space-dwi_desc-preproc_T1w.nii.gz : Final preprocessed T1w image in diffusion space.
  • *_space-T1w_desc-brain_mask.nii.gz : Final brain mask in original space.
  • *_space-T1w_desc-preproc_T1w.nii.gz : Final preprocessed T1w image in original space.
  • *_T1w.nii.gz :

DWI Preprocessing

Output files

• dwi/
  • *_desc-brain_mask.nii.gz : Final brain mask in diffusion space.
  • *_desc-preproc_b0.nii.gz : Final preprocessed b0 image.
  • *_desc-preproc_dwi.bval : Final preprocessed b-value file.
  • *_desc-preproc_dwi.bvec : Final preprocessed b-vectors file.
  • *_desc-preproc_dwi.nii.gz : Final preprocessed DWI image.

Local Modelling

Output files

• dwi/
  • *_frf.txt : Fiber Response Funtion file.
  • *_model-csd_param-afdmax_dwimap.nii.gz: fODF Maximum Apparent Fiber Density (AFD) map.
  • *_model-csd_param-afdsum_dwimap.nii.gz: fODF Sum of the AFD map.
  • *_model-csd_param-afdtotal_dwimap.nii.gz: fODF AFD total map.
  • *_model-csd_param-nufo_dwimap.nii.gz: fODF NUmber of Fiber Orientation map.
  • *_model-csd_param-peaks_dwimap.nii.gz: fODF peaks.
  • *_model-csd_param-sh_dwimap.nii.gz : fODF Spherical Harmonics coefficients.
  • *_model-qball_param-gfa_dwimap.nii.gz : Q-Ball Generalized Fractional Anisotropy map.
  • *_model-qball_param-nufo_dwimap.nii.gz : Q-Ball NUmber of Fiber Orientation map.
  • *_model-qball_param-peaks_dwimap.nii.gz : Q-Ball peaks.
  • *_model-qball_param-sh_dwimap.nii.gz : Q-Ball Spherical Harmonics coefficients.
  • *_model-tensor_param-ad_dwimap.nii.gz: Axial Diffusivity map.
  • *_model-tensor_param-fa_dwimap.nii.gz: Fractional Anisotropy map.
  • *_model-tensor_param-ga_dwimap.nii.gz: Geodesic Anisometry map.
  • *_model-tensor_param-md_dwimap.nii.gz: Mean Diffusivity map.
  • *_model-tensor_param-mode_dwimap.nii.gz: Mode map.
  • *_model-tensor_param-rd_dwimap.nii.gz: Radial Diffusivity map.
  • *_model-tensor_param-rgb_dwimap.nii.gz: RGB map.
  • *_model-tensor_param-tensor_dwimap.nii.gz: Tensor map.

Registration

Output files

• xfm/
  • *_from-dwi_to-T1w_mode-image_desc-affine_xfm.mat : Affine transform from diffusion space to anatomical space.
  • *_from-dwi_to-T1w_mode-image_desc-warp_xfm.nii.gz : Non-linear transform from diffusion space to anatomical space.
  • *_from-T1w_to-dwi_mode-image_desc-affine_xfm.mat : Affine transform from anatomical space to diffusion space.
  • *_from-T1w_to-dwi_mode-image_desc-warp_xfm.nii.gz : Non-linear transform from anatomical space to diffusion space.

Segmentation

Output files

• anat/
  • *_label-CSF_desc-fastseg_mask.nii.gz : CSF mask computed by FastSeg in diffusion space.
  • *_label-CSF_desc-fastseg_probseg.nii.gz : CSF probability map computed by FastSeg in diffusion space.
  • *_label-GM_desc-fastseg_mask.nii.gz : GM mask computed by FastSeg in diffusion space.
  • *_label-GM_desc-fastseg_probseg.nii.gz : GM probability map computed by FastSeg in diffusion space.
  • *_label-WM_desc-fastseg_mask.nii.gz : WM mask computed by FastSeg in diffusion space.
  • *_label-WM_desc-fastseg_probseg.nii.gz : WM probability map computed by FastSeg in diffusion space.

Tractography

Output files

• dwi/
  • *_desc-local_tractogram.trk: Whole-brain tractogram using Local Tractography.
  • *_desc-pft_tractogram.trk: Whole-brain tractogram using Particle Filtering Tractography.
  • *_desc-ensemble_tractogram.trk: Concatenation of local and PFT whole-brain tractograms.
  • *_space-DWI_label-seeding_desc-local_mask.nii.gz: Seeding mask for Local Tractography.
  • *_space-DWI_label-tracking_desc-local_mask.nii.gz: Tracking mask for Local Tractography.
  • *_space-DWI_label-seeding_desc-pft_mask.nii.gz: Seeding mask for Particle Filtering Tractography.
  • *_space-DWI_label-tracking_desc-pft_mask.nii.gz: Tracking mask for Particle Filtering Tractography.

Bundling

Output files

• dwi/
  • bundles/
    • *_CG_L_Po.trk : Left posterior cingulum extracted from whole-brain tractogram.
    • *_CG_R_Po.trk : Right posterior cingulum extracted from whole-brain tractogram.
    • *_IFOF_R.trk : Right inferior fronto-occipital fasciculus extracted from whole-brain tractogram.
    • ...

Advanced Modelling

Output files

• dwi/
  • *_model-noddi_param-dir_dwimap.nii.gz : Noddi principal directions.
  • *_model-noddi_param-fwf_dwimap.nii.gz : Noddi Free Water Fraction map.
  • *_model-noddi_param-icvf_dwimap.nii.gz : Noddi IntraCellular Volume Fraction map.
  • *_model-noddi_param-isovf_dwimap.nii.gz : Noddi Isotropic Volume Fraction map.
  • *_model-noddi_param-od_dwimap.nii.gz : Noddi Orientation Dispersion map.
  • *_model-tensor_param-ad_desc-fwc_dwimap.nii.gz: Freewater corrected Axial Diffusivity map.
  • *_model-tensor_param-fa_desc-fwc_dwimap.nii.gz: Freewater corrected Fractional Anisotropy map.
  • *_model-tensor_param-ga_desc-fwc_dwimap.nii.gz: Freewater corrected Geodesic Anisometry map.
  • *_model-tensor_param-md_desc-fwc_dwimap.nii.gz: Freewater corrected Mean Diffusivity map.
  • *_model-tensor_param-mode_desc-fwc_dwimap.nii.gz: Freewater corrected Mode map.
  • *_model-tensor_param-rd_desc-fwc_dwimap.nii.gz: Freewater corrected Radial Diffusivity map.
  • *_model-tensor_param-rgb_desc-fwc_dwimap.nii.gz: Freewater corrected RGB map.
  • *_model-tensor_param-tensor_desc-fwc_dwimap.nii.gz: Freewater corrected tensor map.

Tractometry

Output files

• dwi/
  • *_label-mean_desc-tractometry_stats.tsv : Tractometry average statistics for each bundles and metrics.
  • *_label-point_desc-tractometry_stats.tsv : Tractometry statistics for each bundles and metrics on points along centroid.
  • *_atlas-iit_desc-roi_stats.tsv : Tractometry statistics inside of IIT Atlas bundles ROIs.

MultiQC

Output files

• multiqc/
  • multiqc_report.html: Global MultiQC report as a standalone HTML file that can be viewed in your web browser.
• sub-*
  • ses-*
    • multiqc/
      • multiqc_report.html: Participant MultiQC report as a standalone HTML file that can be viewed in your web browser.

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.