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.

• Directoryresult_mouse/

  • Directorymultiqc/

    • …
  • Directorysub-01/

    • Directoryanat/

      • Directorysub-01_masks/

        • …
      • sub-01_atlas-Allen_2PE.nii.gz
      • sub-01_atlas-Allen_desc-ANO_dseg.nii.gz
      • sub-01_atlas-Allen_desc-ANOLR_dseg.nii.gz
      • sub-01_desc-seeding_mask.nii.gz
      • sub-01_desc-tracking_mask.nii.gz
      • sub-01_from-dwi_to-Allen_warp.nii.gz
      • sub-01_from-Allen_to-dwi_affine.mat
      • sub-01_from-Allen_to-dwi_warp.nii.gz
    • Directorydwi/

      • sub-01_model-csd_param-afd-max_dwimap.nii.gz
      • sub-01_model-csd_param-afd-sum_dwimap.nii.gz
      • sub-01_model-csd_param-afd-tot_dwimap.nii.gz
      • sub-01_model-csd_param-nufo_dwimap.nii.gz
      • sub-01_model-csd_param-peaks_dwimap.nii.gz
      • sub-01_model-csd_param-sh_dwimap.nii.gz
      • sub-01_desc-local_tracking.trk
      • sub-01_desc-preproc_dwi.nii.gz
      • sub-01_desc-preproc_dwi.bval
      • sub-01_desc-preproc_dwi.bvec
      • sub-01_model-qball_param-apower_dwimap.nii.gz
      • sub-01_model-qball_param-gfa_dwimap.nii.gz
      • sub-01_model-qball_param-qball_dwimap.nii.gz
      • sub-01_model-tensor_param-ad_dwimap.nii.gz
      • sub-01_model-tensor_param-fa_dwimap.nii.gz
      • sub-01_model-tensor_param-ga_dwimap.nii.gz
      • sub-01_model-tensor_param-md_dwimap.nii.gz
      • sub-01_model-tensor_param-mode_dwimap.nii.gz
      • sub-01_model-tensor_param-rd_dwimap.nii.gz
      • sub-01_model-tensor_param-rgb_dwimap.nii.gz
      • sub-01_model-tensor_param-tensor_dwimap.nii.gz
      • sub-01_mqc.png
    • Directorystats/

      • sub-01_stats.json
    • Directoryreport/

      • sub-01_multiqc_report.html
  • Directorysub-02/

    • Directoryanat/

      • …
    • Directorydwi/

      • …
    • Directorystats/

      • …
    • Directoryreport/

      • …
  • …
• 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. 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).

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.

• 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.
• MultiQC - Includes pre-QC. Gather run informations, provide methods boilerplate and software versions list.
• Pipeline information - Report metrics generated during the workflow execution

DWI Preprocessing

Output files

• dwi/
  • sub-01_desc-preproc_dwi.nii.gz: Final preprocessed DWI image in original space.
  • sub-01_desc-preproc_dwi.bval: Final b-values file.
  • sub-01_desc-preproc_dwi.bvec: Final corrected b-vectors file.
• anat/
  • sub-01_desc-preproc_mask.nii.gz: Final brain mask in original space.

Local Modelling

Output files

• dwi/
  • sub-01_model-csd_param-afd-max_dwimap.nii.gz: Maximum apparent fiber density (AFD) map.
  • sub-01_model-csd_param-afd-sum_dwimap.nii.gz: Sum of the AFD map.
  • sub-01_model-csd_param-afd-tot_dwimap.nii.gz: AFD total map.
  • sub-01_model-csd_param-nufo_dwimap.nii.gz: Number of fiber orientation map.
  • sub-01_model-csd_param-peaks_dwimap.nii.gz: fODF peaks.
  • sub-01_model-csd_param-sh_dwimap.nii.gz: fODF coefficients.
  • sub-01_model-qball_param-apower_dwimap.nii.gz: Anisotropic power map.
  • sub-01_model-qball_param-gfa_dwimap.nii.gz: Generalized fractional anisotropy map.
  • sub-01_model-qball_param-sh_dwimap.nii.gz: Spherical harmonics coefficients.
  • sub-01_model-tensor_param-ad_dwimap.nii.gz: Axial Diffusivity map.
  • sub-01_model-tensor_param-fa_dwimap.nii.gz: Fractional Anisotropy map.
  • sub-01_model-tensor_param-ga_dwimap.nii.gz: Geodesic Anisometry map.
  • sub-01_model-tensor_param-md_dwimap.nii.gz: Mean Diffusivity map.
  • sub-01_model-tensor_param-mode_dwimap.nii.gz: Mode map.
  • sub-01_model-tensor_param-rd_dwimap.nii.gz: Radial Diffusivity map.
  • sub-01_model-tensor_param-rgb_dwimap.nii.gz: RGB map.
  • sub-01_model-tensor_param-tensor_dwimap.nii.gz: Tensor map.

Registration

Output files

• anat/
  • sub-01_from-dwi_to-Allen_warp.nii.gz: Non-linear transform from diffusion space to Allen Mouse Brain Atlas space.
  • sub-01_from-Allen_to-dwi_affine.mat: Affine transform from Allen Mouse Brain Atlas space space to diffusion space.
  • sub-01_from-Allen_to-dwi_warp.nii.gz: Non-linear transform from Allen Mouse Brain Atlas space to diffusion space.

Segmentation

Output files

• anat/
  • mask/: Folder containing all the masks extracted from the Allen Mouse Brain Atlas determinated in the nextflow.config in diffusion space, along with a .csv file.
  • sub-01_atlas-Allen_2PE.nii.gz: Allen Mouse Brain Atlas in the native space.
  • sub-01_atlas-Allen_desc-ANO_dseg.nii.gz: Allen Mouse Brain Atlas segmented in the native space.
  • sub-01_atlas-Allen_desc-ANOLR_dseg.nii.gz: Allen Mouse Brain Atlas segmented splitted left/right in the native space.

Tractography

Output files

• anat/
  • sub-01_desc-seeding_mask.nii.gz: Seeding mask for local tracking.
  • sub-01_desc-tracking_mask.nii.gz: Tracking mask for local tracking.
• dwi/
  • sub-01_desc-local_tracking.trk: Whole-brain tractogram using local tractography.

MultiQC

Output files

• multiqc/
  • multiqc_report.html: 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.

Stats

Output files

• stats/
  • sub-01__stats.json: Mean and SD for AD, FA, MD and RD for each regions determinated in the nextflow.config

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.

Results

The pipeline creates 2 folders: results_mouse and work. The files in results are symlinks in works. To transfert or copy-paste the results folder, please use one of the following commands:

On local computer

Command

cp -rL results_mouse NEW_PATH/results_mouse

On HPC

Command

tar cvzfh /HPC_PATH/results_mouse.tar.gz /HPC_PATH/results_mouse
rsync -rL login@adress:/HPC_PATH/results_mouse.tar.gz NEW_PATH/results_mouse.tar.gz