First download a small fMRI dataset, with a structural scan. Be aware that all raw and derivatives data will be generated in the current folder. Note that you will need to manually remove the data_test_niak_mnc1
and fmri_preprocess
folders to restart this tutorial from scratch.
clear
niak_wget('data_test_niak_nii');
Now, set up the names of the structural and functional files.
path_data = [pwd filesep];
% Structural scan subject 1
files_in.subject1.anat = ...
[path_data 'data_test_niak_nii/anat_subject1.nii.gz'];
% fMRI run 1 subject 1
files_in.subject1.fmri.session1.motor = ...
[path_data 'data_test_niak_nii/func_motor_subject1.nii.gz'];
% Structural scan subject 2
files_in.subject2.anat = ...
[path_data 'data_test_niak_nii/anat_subject2.nii.gz'];
% fMRI run 1 subject 2
files_in.subject2.fmri.session1.motor = ...
[path_data 'data_test_niak_nii/func_motor_subject2.nii.gz'];
We also specify where to write the results.
% Where to store the results
opt.folder_out = [path_data 'fmri_preprocess/'];
Next we specify how many threads to use. A value of N
means that up to N
jobs can be executed in parallel.
% Use up to 2 threads
opt.psom.max_queued = 2;
We now set the options of the slice timing correction. Note that we specify the type of the scanner (in practice, only 'Siemens' has an impact), because the definition of the scanner impacts the definition of the slice timing.
opt.slice_timing.type_acquisition = 'interleaved ascending';
opt.slice_timing.type_scanner = 'Bruker';
opt.slice_timing.delay_in_tr = 0;
other options are available as part of the slice timing step, which are not part of the slice timing per say. It is notably possible to center the functional images (if the header information is not accurate), or to suppress some volumes at the beginning of the time series:
% Center the functional volumes on the brain center-of-mass (true/false)
opt.slice_timing.flag_center = false;
% Suppress some volumes at the beginning of the run
opt.slice_timing.suppress_vol = 3;
The voxel size for resampling in stereotaxic space is specified by the user:
% The voxel size to use in the stereotaxic space
opt.resample_vol.voxel_size = 10;
The options for non-uniformity correction of the T1 image is often useful to tweak:
% Parameter for non-uniformity correction.
% 200 is a suggested value for 1.5T images,
% 75 for 3T images.
opt.t1_preprocess.nu_correct.arg = '-distance 75';
The options for temporal filtering, motion parameter regression, white matter and ventricle signal regression, COMPCOR, global signal correction and scrubbing.
% Cut-off frequency for high-pass filtering,
% or removal of low frequencies (in Hz).
opt.time_filter.hp = 0.01;
% Cut-off frequency for low-pass filtering,
% or removal of high frequencies (in Hz).
opt.time_filter.lp = 0.1;
% Remove slow time drifts (true/false)
opt.regress_confounds.flag_slow = true;
% Remove high frequencies (true/false)
opt.regress_confounds.flag_high = false;
% Apply regression of motion parameters (true/false)
opt.regress_confounds.flag_motion_params = true;
% Reduce the dimensionality of motion parameters with PCA (true/false)
opt.regress_confounds.flag_pca_motion = true;
% How much variance of motion parameters (with squares) to retain
opt.regress_confounds.pct_var_explained = 0.95;
% Apply average white matter signal regression (true/false)
opt.regress_confounds.flag_wm = true;
% Apply average ventricle signal regression (true/false)
opt.regress_confounds.flag_vent = true;
% Apply anat COMPCOR (white matter+ventricles, true/false)
% We recommend not using FLAG_WM and FLAG_VENT together with FLAG_COMPCOR
opt.regress_confounds.flag_compcor = false;
% Apply global signal regression (true/false)
opt.regress_confounds.flag_gsc = true;
% Apply scrubbing (true/false)
opt.regress_confounds.flag_scrubbing = true;
% The threshold on frame displacement for scrubbing
opt.regress_confounds.thre_fd = 0.5;
The size of the spatial Gaussian blurring kernel:
% Full-width at maximum (FWHM) of the Gaussian blurring kernel, in mm.
opt.smooth_vol.fwhm = 6;
This command can take up to 20-30 minutes to complete. It runs the full preprocessing pipeline on one subject/run.
niak_pipeline_fmri_preprocess(files_in,opt);
% Check the content of fmri_preprocess/logs/PIPE_history.txt to monitor the progress of the pipeline
Once the pipeline has completed, an interactive report is built as part of the output. Just open the file fmri_preprocess/report/index.html in your browser, located inside the output folder. Note that the images of the test data have very low resolution. You can check an example report with a more typical resolution here.