DPABISurf: A Surface-Based Resting-State fMRI Data Analysis Toolbox

DPABISurf is a surface-based resting-state fMRI data analysis toolbox evolved from DPABI/DPARSF, as easy-to-use as DPABI/DPARSF. DPABISurf is based on fMRIPrep 20.0.5 (Esteban et al., 2018)(RRID:SCR_016216), and based on FreeSurfer 6.0.1 (Dale et al., 1999)(RRID:SCR_001847), ANTs 2.2.0 (Avants et al., 2008)(RRID:SCR_004757), FSL 5.0.9 (Jenkinson et al., 2002)(RRID:SCR_002823), AFNI 20160207 (Cox, 1996)(RRID:SCR_005927), SPM12 (Ashburner, 2012)(RRID:SCR_007037), PALM alpha112 (Winkler et al., 2016), GNU Parallel (Tange, 2011), MATLAB (The MathWorks Inc., Natick, MA, US) (RRID:SCR_001622), Docker (https://docker.com) (RRID:SCR_016445), and DPABI V4.2 (Yan et al., 2016)(RRID:SCR_010501). DPABISurf provides user-friendly graphical user interface (GUI) for pipeline surface-based preprocessing, statistical analyses and results viewing, while requires no programming/scripting skills from the users.

The DPABISurf pipeline first converts the user specified data into BIDS format (Gorgolewski et al., 2016), and then calls fMRIPprep docker to preprocess the structural and functional MRI data, which integrates FreeSurfer, ANTs, FSL and AFNI. With fMRIPprep, the data is processed into FreeSurfer fsaverage5 surface space and MNI volume space. DPABISurf further performs nuisance covariates regression (including ICA-AROMA) on the surface-based data (volume-based data is processed as well), and then calculate the commonly used R-fMRI metrics: amplitude of low frequency fluctuation (ALFF) (Zang et al., 2007), fractional ALFF (Zou et al., 2008), regional homogeneity (Zang et al., 2004), degree centrality (Zuo and Xing, 2014), and seed-based functional connectivity. DPABISurf also performs surface-based smoothing by calling FreeSurfer’s mri_surf2surf command. These processed metrics then enters surfaced-based statistical analyses within DPABISurf, which could perform surfaced-based permutation test with TFCE by integrating PALM. Finally, the corrected results could be viewed by the convenient surface viewer DPABISurf_VIEW, which is derived from spm_mesh_render.m.

DPABISurf is designed to make surface-based data analysis require minimum manual operations and almost no programming/scripting experience. We anticipate this open-source toolbox will assist novices and expert users alike and continue to support advancing R-fMRI methodology and its application to clinical translational studies.

DPABISurf is open-source and distributed under GNU/GPL, available with DPABI at http://www.rfmri.org/dpabi. It supports Windows 10 Pro, MacOS and Linux operating systems. You can run it with or without MATLAB.

1. With MATLAB.
1.1. Please go to http://www.rfmri.org/dpabi to download DPABI. 
1.2. Add with subfolders for DPABI in MATLAB's path setting.
1.3. Input 'dpabi' and then follow the instructions of the "Install" Button on DPABISurf.
2. Without MATLAB.
2.1. Install Docker.
2.2. Terminal: docker pull cgyan/dpabi

2.3. Terminal: docker run -d --rm -v /My/FreeSurferLicense/Path/license.txt:/opt/freesurfer/license.txt -v /My/Data/Path:/data -p 5925:5925 cgyan/dpabi x11vnc -forever -shared -usepw -create -rfbport 5925
/My/FreeSurferLicense/Path/license.txt: Where you stored the FreeSurferLicense got from https://surfer.nmr.mgh.harvard.edu/registration.html.
/My/Data/Path: This is where you stored your data. In Docker, the path is /data.
2.4. Open VNC Viewer, connect to localhost:5925, the password is 'dpabi'.
2.5. In the terminal within the VNC Viewer, input "bash", and then input:
/opt/DPABI/DPABI_StandAlone/run_DPABI_StandAlone.sh ${MCRPath}

Now please enjoy the StandAlone version of DPABISurf with GUI!

If you don't want to run with GUI, you can also call the compiled version of DPABISurf_run. E.g.,
docker run -it --rm -v /My/FreeSurferLicense/Path/license.txt:/opt/freesurfer/license.txt -v /My/Data/Path:/data cgyan/dpabi /bin/bash
/opt/DPABI/DPABI_StandAlone/run_DPABISurf_run_StandAlone.sh ${MCRPath} /data/DPABISurf_Cfg.mat

New features of DPABISurf_V1.3_200401 within DPABI_V4.3_200401 (download at http://rfmri.org/dpabi, please also update the docker file by: docker pull cgyan/dpabi):
Fixed the errors of "--ignore-aroma-denoising-errors" and "--template-resampling-grid". These were caused by the input format changing in fmriprep V20.
1) For Linux or Mac OS, please start matlab from terminal in order to reach docker in DPABI (e.g., Linux: matlab; Mac: open /Applications/MATLAB_R2018a.app/).
2) Before running DPABISurf_Pipeline, you can test the docker environment by running DPABI->DPABISurf->Utilities->Volume-Surface Projector. If the file can be successfully projected to surface, then the software is all set. 
New features of DPABISurf_V1.3_200301 within DPABI_V4.3_200301 (download at http://rfmri.org/dpabi, please also update the docker file by: docker pull cgyan/dpabi):
1. Stability Analysis module was added. You can calculate volume-based and surface-based stability from DPABI->Dynamic & Stability Analyses. You can read our recent work for the details of stability measure: Li, L., Lu, B., Yan, C.G. (2019). Stability of dynamic functional architecture differs between brain networks and states. Neuroimage, 116230, doi:10.1016/j.neuroimage.2019.116230.
2. Field map correction was added, both for DPARSF and DPABISurf. If you want to perform field map Correction, you need to arrange each subject's field map DICOM files in one directory, and then put them in "FieldMap" directory under the working directory. i.e.:';...
    '{Working Directory}\FieldMap\PhaseDiffRaw\Subject001\xxxxx001.dcm';...
    '{Working Directory}\FieldMap\PhaseDiffRaw\Subject001\xxxxx002.dcm';...
    '{Working Directory}\FieldMap\PhaseDiffRaw\Subject002\xxxxx001.dcm';...
    '{Working Directory}\FieldMap\PhaseDiffRaw\Subject002\xxxxx002.dcm';...
    '{Working Directory}\FieldMap\Magnitude1Raw\Subject001\xxxxx001.dcm';...
    '{Working Directory}\FieldMap\Magnitude1Raw\Subject001\xxxxx002.dcm';...
    '{Working Directory}\FieldMap\Magnitude1Raw\Subject002\xxxxx001.dcm';...
    '{Working Directory}\FieldMap\Magnitude1Raw\Subject002\xxxxx002.dcm';...
Then you can click the button of “FieldMap” button to set field map correction parameters. In most cases, you can use the default  “0” value to let the program read the parameters (e.g., echo times) from the DICOM files.
3. Check data organization function added. For the new users of DPARSF and DPABISurf, most of the errors were caused by data organization! Please use DPABI->Utilities->Check Data Organization to check your data organization before running DPARSF or DPABISurf. This program will lead you to organize your data correctly with prompting messages!
4. Slice timing information read from DICOM files. If you are starting with DICOM files, you no longer need to set the slice timing correction parameters. Just leave it as default (slice number: 0), then DPARSF or DPABISurf will read the parameters from DICOM files. This new feature thanks to Dr. Chris Rorden's new dcm2niiX program (version v1.0.20190902).
5. DPARSF V5.0 now is compatible with BIDS format. You can start with BIDS format data by checking checkbox “BIDS to DPARSF” and setting  “Starting Directory Name” to “BIDS”.
6. DPABISurf V1.3. Check and re-run fmriprep failed subjects. If for any reason, the program failed fmriprep running in DPABISurf, you just need to re-run starting with the step “Preprocessing with fmriprep” and set the “Starting Directory Name” to “BIDS” in DPABISurf_Pipeline. Alternatively, you can run a single checking step from DPABI->DPABISurf->Utilities->Re-Run fmriprep Failed Subjects.
7. DPABI->Utilities->DICOM Sorter. Now DICOM Sorter will remove illegal characters for file names in DICOM sorter. E.g., a subject id of “Wang’#$#’s” will no longer cause a problem in sorting DICOM files.
8. y_Call_DPABISurf_VIEW_FromVolume.m and y_Call_DPABISurf_VIEW.m were added. Now you can use script to call DPABISurf_VIEW to generate surface maps (with higher quality now) in batch. Remember to add “close all” in the for loop to prevent too many windows.
New features of DPABISurf_V1.2_190919 within DPABI_V4.2_190919 (download at http://rfmri.org/dpabi, please also update the docker file by: docker pull cgyan/dpabi):
1. DPABISurf_V1.2_190919 updated.
1.1. A quality control module was added to DPABISurf. Now users can quality control surface reconstruction, EPI to T1 registration and T1 to MNI registration for all the subjects in one HTML file, respectively (based on fmriprep 1.5.0). For volume-based analysis, users can also generate group mask for DPABISurf, and exclude subjects by thresholding coverage and head motion.
1.2. DPABISurf now also output sulcus depth and volume in fsaverage and fsaverage5 spaces for statistical analysis.
1.3. In results organizer of DPABISurf, the redundant files would not be organized now. In addition, the fmriprep and freesurfer files were backed up, while excluding T1 image that may have privacy information such as face.
2. DPABI_VIEW has a new function "Surface View with DPABISurf_VIEW" now. This function will convert the files to fsaverage surface using freesurfer's mri_vol2surf command. Then the results were displayed by calling DPABISurf_VIEW to generate surface-based picture. 
New features of DPABISurf_V1.1_190725  (download at http://rfmri.org/dpabi):
1. New module for Surface-Based Temporal Dynamic Analysis (DPABI_TDA_Surf) was added. Dynamic regional indices (ALFF, fALFF, ReHo, Degree Centrality and Global Signal Correlation) and dynamic functional connectivity could be automatically calculated by one click through DPABI_TDA_Surf (with DPABISurf preprocessed data). The statistics maps (CV, Mean and SD) of the dynamic regional indices would also be generated by DPABI_TDA_Surf. A neuroimaging index which measures the concordance of the dynamic regional indices is incorporated into DPABI_TDA_Surf. Please see more details at: Yan, C.-G., Yang, Z., Colcombe, S.J., Zuo, X.-N., Milham, M.P., 2017. Concordance among indices of intrinsic brain function: insights from inter-individual variation and temporal dynamics. Sci Bull 62, 1572-1584.
2. The calculation of degree centrality now considers a vertex's correlation to both left and right hemispheres.
3. Standardization considers bilateral hemispheres. 
4. Smooth function after Standardization was added.
5. If ICA-AROMA was chosen, no head motion realign parameters would be regressed out.
6. Fixed compatibility issues with old matlab versions.
7. The default surface-based smoothing kernel changed to 6mm instead of 10mm.
8. The DPABISurf results organizing function was added to the R-fMRI Maps Project.
9. Output an excel table for the volume of subcortical structures (calculated by freesurfer): {WorkingDir}/Results/AnatVolu/Anat_Segment_Volume.tsv.
10. DPABISurf_VIEW, the surface-based viewer now has a function to yoke between different viewers.
11. Docker updated basing on fMRIPrep 1.4.1. Besides pull from docker hub, the docker file can be also downloaded form baidu (extract code: enmn).
12. Besides the stand alone version of DPABI (with GUI), the compiled version of DPABISurf_run was also added to docker. Users can run DPABISurf_run with scripting. E.g.,
docker run -it --rm -v /My/FreeSurferLicense/Path/license.txt:/opt/freesurfer/license.txt -v /My/Data/Path:/data cgyan/dpabi /bin/bash
/opt/DPABI/DPABI_StandAlone/run_DPABISurf_run_StandAlone.sh ${MCRPath} /data/DPABISurf_Cfg.mat
Tips for Linux or Mac OS: please start matlab from terminal in order to reach docker in DPABI (e.g., Linux: matlab; Mac: open /Applications/MATLAB_R2018a.app/).



  • Ashburner, J. (2012). SPM: a history. Neuroimage, 62(2), 791-800, doi:10.1016/j.neuroimage.2011.10.025.
  • Avants, B.B., Epstein, C.L., Grossman, M., Gee, J.C. (2008). Symmetric diffeomorphic image registration with cross-correlation: evaluating automated labeling of elderly and neurodegenerative brain. Med Image Anal, 12(1), 26-41, doi:10.1016/j.media.2007.06.004.
  • Cox, R.W. (1996). AFNI: software for analysis and visualization of functional magnetic resonance neuroimages. Comput Biomed Res, 29(3), 162-173.
  • Dale, A.M., Fischl, B., Sereno, M.I. (1999). Cortical surface-based analysis. I. Segmentation and surface reconstruction. Neuroimage, 9(2), 179-194, doi:10.1006/nimg.1998.0395.
  • Esteban, O., Markiewicz, C.J., Blair, R.W., Moodie, C.A., Isik, A.I., Erramuzpe, A., Kent, J.D., Goncalves, M., DuPre, E., Snyder, M., Oya, H., Ghosh, S.S., Wright, J., Durnez, J., Poldrack, R.A., Gorgolewski, K.J. (2018). fMRIPrep: a robust preprocessing pipeline for functional MRI. Nat Methods, doi:10.1038/s41592-018-0235-4.
  • Gorgolewski, K.J., Auer, T., Calhoun, V.D., Craddock, R.C., Das, S., Duff, E.P., Flandin, G., Ghosh, S.S., Glatard, T., Halchenko, Y.O., Handwerker, D.A., Hanke, M., Keator, D., Li, X., Michael, Z., Maumet, C., Nichols, B.N., Nichols, T.E., Pellman, J., Poline, J.B., Rokem, A., Schaefer, G., Sochat, V., Triplett, W., Turner, J.A., Varoquaux, G., Poldrack, R.A. (2016). The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments. Sci Data, 3, 160044, doi:10.1038/sdata.2016.44.
  • Jenkinson, M., Bannister, P., Brady, M., Smith, S. (2002). Improved optimization for the robust and accurate linear registration and motion correction of brain images. Neuroimage, 17(2), 825-841.
  • Tange, O. (2011). Gnu parallel-the command-line power tool. The USENIX Magazine, 36(1), 42-47.
  • Winkler, A.M., Ridgway, G.R., Douaud, G., Nichols, T.E., Smith, S.M. (2016). Faster permutation inference in brain imaging. Neuroimage, 141, 502-516, doi:10.1016/j.neuroimage.2016.05.068.
  • Yan, C.G., Wang, X.D., Zuo, X.N., Zang, Y.F. (2016). DPABI: Data Processing & Analysis for (Resting-State) Brain Imaging. Neuroinformatics, 14(3), 339-351, doi:10.1007/s12021-016-9299-4.
  • Zang, Y., Jiang, T., Lu, Y., He, Y., Tian, L. (2004). Regional homogeneity approach to fMRI data analysis. Neuroimage, 22(1), 394-400, doi:http://dx.doi.org/10.1016/j.neuroimage.2003.12.030.
  • Zang, Y.F., He, Y., Zhu, C.Z., Cao, Q.J., Sui, M.Q., Liang, M., Tian, L.X., Jiang, T.Z., Wang, Y.F. (2007). Altered baseline brain activity in children with ADHD revealed by resting-state functional MRI. Brain Dev, 29(2), 83-91, doi:10.1016/j.braindev.2006.07.002.
  • Zou, Q.-H., Zhu, C.-Z., Yang, Y., Zuo, X.-N., Long, X.-Y., Cao, Q.-J., Wang, Y.-F., Zang, Y.-F. (2008). An improved approach to detection of amplitude of low-frequency fluctuation (ALFF) for resting-state fMRI: Fractional ALFF. Journal of Neuroscience Methods, 172(1), 137-141, doi:http://dx.doi.org/10.1016/j.jneumeth.2008.04.012.
  • Zuo, X.-N., Xing, X.-X. (2014). Test-retest reliabilities of resting-state FMRI measurements in human brain functional connectomics: A systems neuroscience perspective. Neuroscience & Biobehavioral Reviews, 45, 100-118, doi:http://dx.doi.org/10.1016/j.neubiorev.2014.05.009.





I am using DPABISurf  4.3 200301 and the Demo data with 3 subjects.
I got this error below-
fmriprep: error: unrecognized arguments: --ignore-aroma-denoising-errors --template-resampling-grid 2
After re-run fmriprep, these subjects have not run fmriprep yet:
I tried re-running, starting with preprocessing with fmriprep and giving BIDS as my starting directory. It still fails witht he error/s below.
Appreciate any suggestions. Thank you.
fmriprep: error: unrecognized arguments: --ignore-aroma-denoising-errors --template-resampling-grid 2
You are using fMRIPrep-20.0.1, and a newer version of fMRIPrep is available: 20.0.5.
Please check out our documentation about how and when to upgrade:
WARNING: Version 20.0.1 of fMRIPrep (current) has been FLAGGED
(reason: fsLR resampling error (problematic only when using the --cifti-output flag)).
That means some severe flaw was found in it and we strongly discourage its usage.
Error using DPABISurf_run (line 518)
Error detected during running fmriprep, please check!
Error in DPABISurf_Pipeline>pushbuttonDPABISurfRun_Callback (line 1693)
[Error, Cfg]=DPABISurf_run(handles.Cfg);
Error in gui_mainfcn (line 95)
Error in DPABISurf_Pipeline (line 42)
    gui_mainfcn(gui_State, varargin{:});
Error in
Error while evaluating UIControl Callback.


There is a minor bug when using ICA-AROMA since fMRIPrep-20.0.1 changed the input format.

For "Version 20.0.1 of fMRIPrep (current) has been FLAGGED", you don't need to worry because DPABISurf doesn't use cifti-output.

As for now, please download our development version from https://github.com/Chaogan-Yan/DPABI

Please let me know if it works.

Thank you, with the GitHub version fMRIprep started running. 

After few hours, the pipeline has stopped with subject 002. Though I don’t think it finished 001 successfully either.

Matlab window has following error. Please let me know how to fix this. Thank you.


[Node] Running "lta2itk_fwd" ("niworkflows.interfaces.freesurfer.PatchedLTAConvert"), a CommandLine Interface with command:

lta_convert --inlta /data/fmriprepwork/sub-Sub002/fmriprep_wf/single_subject_Sub002_wf/anat_preproc_wf/surface_recon_wf/t1w2fsnative_xfm/out.lta --outitk /data/fmriprepwork/sub-Sub002/fmriprep_wf/single_subject_Sub002_wf/anat_preproc_wf/anat_derivatives_wf/lta2itk_fwd/out.txt

200327-06:36:15,538 nipype.workflow INFO:

                 [Node] Finished "fmriprep_wf.single_subject_Sub002_wf.anat_preproc_wf.anat_derivatives_wf.lta2itk_fwd".

200327-06:36:19,0 nipype.workflow ERROR:

                 could not run node: fmriprep_wf.single_subject_Sub002_wf.anat_preproc_wf.brain_extraction_wf.norm

You are using fMRIPrep-20.0.1, and a newer version of fMRIPrep is available: 20.0.5. Please check out our documentation about how and when to upgrade:


WARNING: Version 20.0.1 of fMRIPrep (current) has been FLAGGED

(reason: fsLR resampling error (problematic only when using the --cifti-output flag)).

That means some severe flaw was found in it and we strongly

discourage its usage.

fMRIPrep failed: Workflow did not execute cleanly. Check log for details

Preprocessing did not finish successfully. Errors occurred while processing data from participants: Sub002 (1). Check the HTML reports for details.


/usr/local/miniconda/lib/python3.7/site-packages/scipy/fftpack/basic.py:160: FutureWarning: Using a non-tuple sequence for multidimensional indexing is deprecated; use `arr[tuple(seq)]` instead of `arr[seq]`. In the future this will be interpreted as an array index, `arr[np.array(seq)]`, which will result either in an error or a different result.


  z[index] = x


Are you using demo data from: http://rfmri.org/demodata?

This is wierd, what's your OS?

Yes demo data from  http://rfmri.org/demodata

OS is MacOS Catalina 10.15.3


Thank you.

I don't have a Catalina to test. But is should be OK.

Do you have a linux machine? Could you have a test on ubuntu or centos? Those platforms were tested.



Running DARTEL: Normalize to MNI space for VBM. Modulated version With smooth kernel [8 8 8].
Running job #1
Running 'Normalise to MNI Space'
Failed  'Normalise to MNI Space'
Error using read_hdr (line 32)
Error reading header file "D:\MRIAnalysissoftware\spm12\tpm\TPM.nii".
In file "D:\MRIAnalysissoftware\spm12\@nifti\private\read_hdr.m" (v4967), function "read_hdr" at line 32.
In file "D:\MRIAnalysissoftware\spm12\@nifti\nifti.m" (v4986), function "nifti" at line 26.
In file "D:\MRIAnalysissoftware\spm12\spm_get_space.m" (v6379), function "spm_get_space" at line 18.
In file "D:\MRIAnalysissoftware\spm12\toolbox\DARTEL\spm_dartel_norm_fun.m" (v5668), function "spm_dartel_norm_fun" at line 43.
The following modules did not run:
Failed: Normalise to MNI Space
Error using MATLABbatch system
Job execution failed. The full log of this run can be found in MATLAB command
window, starting with the lines (look for the line showing the exact #job as
displayed in this error message)
Running job #1
Error while evaluating UIControl Callback

Seems you need to re-install SPM.


        我在用DPABISurf进行到preprocessing with fmriprep过程中matlab突然被killed

-VM:~/sharefolder/BOLD/T2DM$ matlab
MATLAB is selecting SOFTWARE OPENGL rendering.

        严老师好!我用台式机windows10-pro系统(Intel i3-4160U 3.6GHz  双核4线程,16G内存,硬盘2T),Matlab2013b  运行DPABI_V4.3_200401中DPABISurf 1.3 【最新版docker2.3.0.3(45519),docker分了2个核,10G memory,load from local file <dpabi43_200401docker.tar.gz,licence.txt均顺利安装】,从DPABISurf_DemoData已做好fmriprep的步骤,照着视频设置往下跑(parallel:1#):

Regressing Out Covariates...
Regressing Out Covariates finished.
Warning: Several fields match intent type. Using first.
> In @gifti\private\isintent at 56
  In gifti.subsref at 19
  In y_RegressOutCovariates_OnSurf at 31
  In DPABISurf_run>(parfor body) at 920
  In parallel_function>make_general_channel/channel_general at 922
  In remoteParallelFunction at 28 
Load mask "".
Error using y_RegressOutCovariates_OnSurf (line 63)
Dimensions of matrices being concatenated are not consistent.
Error in DPABISurf_run>(parfor body) (line 920)
Error in DPABISurf_run (line 780)
        parfor i=1:Cfg.SubjectNum
Error in DPABISurf_Pipeline>pushbuttonDPABISurfRun_Callback (line 1693)
[Error, Cfg]=DPABISurf_run(handles.Cfg);
Error in gui_mainfcn (line 96)
Error in DPABISurf_Pipeline (line 42)
    gui_mainfcn(gui_State, varargin{:});
Error in @(hObject,eventdata)DPABISurf_Pipeline('pushbuttonDPABISurfRun_Callback',hObject,eventdata,guidata(hObject))
Caused by:
    Error using horzcat
    Dimensions of matrices being concatenated are not consistent.
Error while evaluating uicontrol Callback
尝试用VNC viewer 运行DPABISurf_StandAlone GUI version,parallel 1#刚开始run时,滚动一串error,速度比matlab慢但还是能跑下去,到了smoothing the results...                                   ______________________________
parallel:warning:input is read from the terminal...             \              DPABISurf   Pipeline                        /
parallel:warning: are donging(in which case: YOU ARE... \    working DIR  /data/...                               /
parallel:Warning: consider going through the tutorial...    \         sub_Sub_001                                         /
parallel:Warning:Press CTRL-D to exit.                                 \                                                                           /
在这停住了,也没有报错提示 ,CTRL-D也无反应,只能docker stop o(╯□╰)o

老师,您好,在处理静息态数据的时候,我想用自己的mask,但是我的mask是91x109x91,然后就没办法开展了,所以我想问一下如何将维度为91x109x91 的脑图转成61x73x61?

请使用dpabi>Utilities>Image Reslicer功能。