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.2.1 (Esteban et al., 2018) (RRID:SCR_016216), and based on FreeSurfer 6.0.1 (Dale et al., 1999) (RRID:SCR_001847), ANTs 2.3.3 (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), dcm2niix (Li et al., 2016) (RRID:SCR_014099), PALM alpha115 (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 (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.6_210501 within DPABI_V6.0_210501 (download at http://rfmri.org/dpabi).
1. Can use individual ROI definition files for each subject. The first line of the ROI definition file should be: 'Seed_ROI_List:'. An example SeedROI.txt:
2. Fixed a bug in dealing with multiple sessions of FieldMap.
3. Allow skipping subjects in TRInfo.tsv.
4. The surface for ReHo calculation were changed from pial to white.
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.5_201201 within DPABI_V5.1_201201 (download at http://rfmri.org/dpabi, please also update the docker file by: docker pull cgyan/dpabi):
1. fMRIPrep backend updated to version 20.2.1 (Long-Term Support).
2. Fixed a bug during processing data with multiple sessions.
3. DPABISurf_VIEW. Updated Cluster Report function. Please see here for usage.
4. DPABISurf_VIEW. Fixed a bug when setting p = 0.001, but still display 1. Fixed a bug to input index. Added save colorbar.
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.
New features of DPABISurf_V1.4_201001 within DPABI_V5.0_201001 (download at http://rfmri.org/dpabi, please also update the docker file by: docker pull cgyan/dpabi):
1. fMRIPrep backend updated to version 20.2.0 (Long-Term Support).
2. For surface based multiple comparison correction, the method of FDR correction was added to DPABISurf. See DPABISurf_VIEW->Cluster...->Apply FDR Correction.
3. For surface based multiple comparison correction, the method of Monte Carlo simulation was added to DPABISurf. See DPABISurf_VIEW->Cluster...->Apply FWE (Monte Carlo Simulation) Correction.
4. Pre-calculated Monte Carlo Simulation tables were added for most used situations. Please see {DPABI}/StatisticalAnalysis/DPABISurf_MonteCarlo/MonteCarloTable/. Users can index the minimum cluster area for an estimated smoothness and set at DPABISurf_VIEW->Cluster...->Set Cluster Size.
5. Docker File: MCR files extracted for easy use in Singularity.
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.
  • Li X, Morgan PS, Ashburner J, Smith J, Rorden C. (2016) The first step for neuroimaging data analysis: DICOM to NIfTI conversion. J Neurosci Methods. 264:47-56.
  • 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.



老师您好,我使用linux的ubuntu系统,matlab2018b安装DPABISurf,已经安装好docker,但是进行pull DPABISurf Docker这一步,使用代码docker pull cgyan/dpabi时,很多文件下着下着就下不动了。

最后提示:error pulling image configuration: Get "https://production.cloudflare.docker.com/registry-v2/docker/registry/v2/blobs/sha256/13/13d6174a60b18e990091efd5e64edc9e5795ce8d708ea90f81a4f45ac060/data?verify=1636427975-UAQ6S2tcIHUpEX1pA%2FsOg7qaEy4%3D": dial tcp i/o timeout

然后我看pull Docker可以load local file。所以我进到官网给的百度网盘上下载了dpabi60docker.tar.gz和gyancircosdocker.tar.gz,这两个文件,我直接load的话,会提示 [1BError processing tar file(exit status 1): setxattr("/usr/lib/node_modules/npm", trusted.overlay.opaque=y): operation not supported。

麻烦老师能解答一下,如何才能顺利在linux上安装好 DPABISurf。万分感谢。