Output files

Every processing stage writes its important outputs into datasink/ folders, created inside the output directory given at execution. This page describes every file produced.

Note

The output directory also contains the Nipype working directory and the serialised workflow state (.pkl). Those are internal, but they are what the next stage reads to locate the previous stage’s files — do not move or delete them between stages.

Preprocessing outputs

Preprocessing writes five datasinks: anat_datasink/, bold_datasink/, unbiased_template_datasink/, transforms_datasink/ and motion_datasink/. The quality control images are written separately to preprocess_QC_report/, described in Preprocessing QC outputs.

anat_datasink/

Inhomogeneity-corrected anatomical scans.

  • anat_preproc/: anatomical scans after inhomogeneity correction

bold_datasink/

All outputs related to the functional scans. Files are resampled either onto the native space or the commonspace of the EPI. Native space outputs are resampled over the anatomical scan from the corresponding MRI session; commonspace outputs are resampled over the reference atlas. The original EPI voxel resolution is unchanged during resampling unless specified otherwise in the RABIES command.

Native space

  • native_bold/: preprocessed EPI timeseries resampled to native space

  • native_brain_mask/: brain mask in native space

  • native_WM_mask/: WM mask in native space

  • native_CSF_mask/: CSF mask in native space

  • native_labels/: atlas labels in native space

  • native_bold_ref/: a volumetric 3D EPI average generated from the 4D native_bold/

Commonspace

  • commonspace_bold/: preprocessed EPI timeseries resampled to commonspace

  • commonspace_mask/: brain mask in commonspace

  • commonspace_WM_mask/: WM mask in commonspace

  • commonspace_CSF_mask/: CSF mask in commonspace

  • commonspace_vascular_mask/: vascular mask in commonspace

  • commonspace_labels/: atlas labels in commonspace

  • commonspace_resampled_template/: the commonspace anatomical template, resampled to the EPI’s dimensions

Inputs and intermediates

  • input_bold/: the raw EPI scans provided as inputs in the BIDS data folder

  • initial_bold_ref/: the initial volumetric 3D EPI average generated from the 4D input_bold/

  • raw_brain_mask/: brain mask resampled onto the 4D input_bold/

  • inho_cor_bold/: the volumetric 3D EPI (initial_bold_ref/) after inhomogeneity correction, later used for registration of the EPI

  • inho_cor_bold_warped2anat/: inho_cor_bold after co-registration to the associated anatomical image (anat_preproc/)

  • std_map_preprocess/: the temporal standard deviation at each voxel of commonspace_bold/

  • tSNR_map_preprocess/: the temporal signal-to-noise ratio (tSNR) of commonspace_bold/

unbiased_template_datasink/

Outputs from the generation of the unbiased template using optimized_antsMultivariateTemplateConstruction. The unbiased template is the average of all anatomical scans (or functional scans with --bold_only) after their alignment.

  • unbiased_template/: the unbiased template generated from the input dataset scans

  • warped_unbiased_template/: the unbiased template, registered to the reference atlas in commonspace

transforms_datasink/

All transform files for resampling between spaces.

The bold_to_anat registration transforms the raw EPI to overlap with the anatomical image, correcting susceptibility distortions, which defines native space. The native_to_unbiased registration overlaps every scan onto the generated unbiased template. The unbiased_to_atlas registration aligns the unbiased template with the reference atlas, which defines commonspace.

  • bold_to_anat_affine/: affine transforms from the EPI co-registration to the anatomical image

  • bold_to_anat_warp/: non-linear transforms from the EPI co-registration to the anatomical image

  • bold_to_anat_inverse_warp/: inverse of bold_to_anat_warp/

  • native_to_unbiased_affine/: affine transforms for the alignment between native space and the unbiased template

  • native_to_unbiased_warp/: non-linear transforms for the same alignment

  • native_to_unbiased_inverse_warp/: inverse of native_to_unbiased_warp/

  • unbiased_to_atlas_affine/: affine transforms for the alignment between the unbiased template and the atlas in commonspace

  • unbiased_to_atlas_warp/: non-linear transforms for the same alignment

  • unbiased_to_atlas_inverse_warp/: inverse of unbiased_to_atlas_warp/

motion_datasink/

Files derived from motion estimation.

  • motion_params_csv/: the 24 motion parameters, usable as nuisance regressors at the confound correction stage

  • FD_csv/: a CSV with timecourses for either the mean or maximal framewise displacement estimations

  • FD_voxelwise/: a NIfTI image containing framewise displacement evaluated at each voxel

  • pos_voxelwise/: a NIfTI image tracking the displacement of each voxel across time, derived from the head motion realignment parameters

Confound correction outputs

confound_correction_datasink/

  • cleaned_timeseries/: cleaned timeseries after the application of confound correction

  • frame_censoring_mask/: CSV files recording, as a boolean vector, which timepoints were censored, if frame censoring was applied

  • aroma_out/: outputs from running ICA-AROMA if --ica_aroma is applied, including the MELODIC ICA outputs and the component classification results

  • plot_CR_overfit/: figures illustrating the variance explained by random regressors during confound correction, and the variance explained by the real regressors after subtracting the variance from random regressors

Analysis outputs

commonspace_analysis_datasink/ and nativespace_analysis_datasink/

Which of these appears depends on the space the cleaned timeseries were produced in:

Datasink

Present when

commonspace_analysis_datasink/

confound correction produced commonspace timeseries, or --resample_to_commonspace was passed, or --group_ica apply=true was used

nativespace_analysis_datasink/

confound correction produced nativespace timeseries

Both contain the same set of files, listed below. group_ICA_dir/ is always written to commonspace_analysis_datasink/, since group ICA requires commonspace alignment.

  • group_ICA_dir/: complete output from MELODIC ICA, including the melodic_IC.nii.gz NIfTI giving all spatial components and a report/ folder with an HTML visualisation

  • matrix_data_file/: a .pkl file containing a 2D NumPy array representing the whole-brain correlation matrix. With --ROI_type parcellated, the row and column indices are matched in increasing order of the atlas ROI label number

  • matrix_fig/: a .png displaying the correlation matrix

  • seed_correlation_maps/: NIfTI files for seed-based connectivity, one voxelwise correlation map per seed provided in --seed_list

  • dual_regression_nii/: the spatial maps from dual regression, corresponding to the linear coefficients from the second regression. The 3D spatial maps are concatenated into a 4D NIfTI, with component order consistent with the priors provided in --prior_maps

  • dual_regression_timecourse_csv/: a CSV storing the outputs from the first linear regression during dual regression — one timecourse per prior component from --prior_maps

  • NPR_prior_filename/: spatial components fitted during NPR

  • NPR_prior_timecourse_csv/: timecourses associated with each component in NPR_prior_filename/

  • NPR_extra_filename/: the extra spatial components fitted during NPR which were not part of the priors

  • NPR_extra_timecourse_csv/: timecourses associated with each component in NPR_extra_filename/

data_diagnosis_datasink/

Produced when --data_diagnosis is selected. See How to assess data quality for how to use these.

  • figure_temporal_diagnosis/: scan-level temporal features from the spatiotemporal diagnosis

  • figure_spatial_diagnosis/: scan-level spatial features from the spatiotemporal diagnosis

  • temporal_info_csv/: CSV containing the data plotted in figure_temporal_diagnosis/

  • spatial_VE_nii/: NIfTI with the confound regression percentage variance explained (\(R^2\)) at each voxel

  • CR_prediction_std_nii/: NIfTI with the confound regression variance explained at each voxel

  • random_CR_std_nii/: NIfTI with the variance explained from random regressors at each voxel

  • corrected_CR_std_nii/: NIfTI with the confound regression variance explained at each voxel after removing the variance explained by random regressors

  • temporal_std_nii/: the standard deviation at each voxel after confound correction

  • GS_cov_nii/: the covariance of each voxel with the global signal

analysis_QC/ holds the group-level features of data quality:

  • sample_distributions/: the distribution plots

    • {analysis}_sample_distribution.png: the distribution plot for a given network analysis

    • {analysis}_outlier_detection.csv: a CSV associating the measures displayed in the distribution plot with the corresponding scan IDs

  • parametric_stats/: the group statistical report for analysis quality control, using parametric measures

    • DR{component #}_QC_maps.png: statistical maps relevant to analysis quality control. DR refers to dual regression analysis, and {component #} relates the file to one of the BOLD components specified in --prior_bold_idx

    • DR{component #}_QC_stats.csv: a follow-up to _QC_maps.png allowing quantitative categorisation of data quality outcomes as in [DGregoireDGC24]

    • seed_FC{seed #}_QC_maps.png: the same statistical maps, for seed-based connectivity analysis

    • seed_FC{seed #}_QC_stats.csv: the same measures, for seed-based connectivity analysis

  • non_parametric_stats/: as parametric_stats/, but using non-parametric measures

See also

Metric definitions gives the precise computation behind every quantity named on this page.