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

Submitted by YAN Chao-Gan on Wed, 03/06/2019 - 10:10

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.
 
Tips: 
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/).

 

References:

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

 

 

Forums:

Tsuki

Tue, 02/18/2020 - 08:19

Dear all, 

How can I get those flatten surface brain images? My data is in NIFTI format. I did not manage to visualize them as flatten surface.

Thanks and congratulations on your toolbox!

Tsuki

YAN Chao-Gan

Tue, 03/03/2020 - 10:03

DPABI->Viewer: then set up to view your 3D nifti files.

Then Click the "More" dropout menu -> Surface view with DPABISurf_VIEW

You'd better go over the free courses: http://rfmri.org/course

Tsuki

Mon, 03/16/2020 - 15:10

Dear Yan Chao-Gan, thanks for your response. I can't however find the "More" dropout menu. Do you mean the "More Options" cell below the "Surface Option"? Another question: where do I add my NIFTI files? Is it under "Overlay Files" > Add Overlay? Thank you again.

Tsuki

Mon, 03/16/2020 - 15:10

Dear Yan Chao-Gan, thanks for your response. I can't however find the "More" dropout menu. Do you mean the "More Options" cell below the "Surface Option"? Another question: where do I add my NIFTI files? Is it under "Overlay Files" > Add Overlay? Thank you again.

YAN Chao-Gan

Thu, 03/19/2020 - 12:08

You need to use DPABI_VIEW to open your 3D NIfTI files first.

胜楠

Tue, 03/03/2020 - 07:34

严老师您好，我想研究一下海马尾部和全脑的功能连接，但是不知道如何设置海马尾部的ROI，也找不到相关的mask，希望得到老师的帮助！

YAN Chao-Gan

Tue, 03/03/2020 - 10:04

查查文献看freesurfer有这样的mask吗？

veeus18

Thu, 03/26/2020 - 21:21

Hello,
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:
    'sub-Sub001'
    'sub-Sub002'
    'sub-Sub003'
 
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:
https://fmriprep.readthedocs.io/en/latest/faq.html#upgrading
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)
        feval(varargin{:});
 
Error in DPABISurf_Pipeline (line 42)
    gui_mainfcn(gui_State, varargin{:});
 
Error in
matlab.graphics.internal.figfile.FigFile/read>@(hObject,eventdata)DPABISurf_Pipeline('pushbuttonDPABISurfRun_Callback',hObject,eventdata,guidata(hObject)) 
Error while evaluating UIControl Callback.
 

 

YAN Chao-Gan

Fri, 03/27/2020 - 03:14

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.

veeus18

Fri, 03/27/2020 - 13:22

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:

https://fmriprep.readthedocs.io/en/latest/faq.html#upgrading

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

 

YAN Chao-Gan

Sat, 03/28/2020 - 00:58

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

This is wierd, what's your OS?

veeus18

Sat, 03/28/2020 - 02:14

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

OS is MacOS Catalina 10.15.3

 

Thank you.

YAN Chao-Gan

Sat, 03/28/2020 - 02:30

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.

Tsuki

Sun, 04/12/2020 - 19:43

Hi, 

Since I had problems preprocessing my 26 subjects, I did the DPARSFA pipeline using subgroups of subjects (first run 9 subjects; second run 9 subjects, third run 8 subjects). I noticed that results from a previous session using different number of subjects yielded was not identical. 

Question: does the number of subjects included in a run affect the individual subject results? Or is it normal that I get different results when running DPARSFA every time (due to some stochastic processes)?

The only way for me to preprocess large data sets is by preprocessing subsets one at a time.

Thank you, 

T