DPABI/DPABISurf/DPARSF Error Handling

DPABI/DPABISurf/DPARSF Error Handling

（中文版在后半部分）

    We have noticed that the biggest problem that troubles beginners of functional magnetic resonance imaging is error reporting (Figure 1). Among all the errors, the computer environment setting (software installation) accounted for 40%, and the data sorting problem accounted for 50%. So please be sure to read this guide carefully, it will help you avoid 90% of possible errors, and save your precious time to focus on the analysis of results!

Figure 1. You definitely never want to see this error (“the red”) again

1. Installation of DPABI/DPABISurf

The prerequisites for DPABI/DPABISurf to run smoothly:

(0) A windows/mac/linux computer with relatively decent performance

The equivalent or higher performance of processors than the 7th Gen Intel-i5. More than 16G of the memory. Better to reserve more than 300G disk space.

(1) MATLAB

Many users would like to put SPM or DPABI into the toolbox of MATLAB, then there shouldn’t be any spaces, Chinese characters or special characters in the installation path! Such as

The installation path like "C:\Program files\MATLAB" is absolutely not allowed, as there is a space between Program and files! In addition, if your account name of the operating system ("Administrator" by default) contains Chinese characters, it is recommended to create a new English account (without spaces), and install MATLAB under this account.

(2) SPM

SPM is a free and open source software, please go to http://www.fil.ion.ucl.ac.uk/spm/software/download/ and fill in a table with some simple personal information to download. It is recommended to download SPM12. Remember that the software path should not include any spaces, Chinese characters or special characters!

(3) FSL (please ignore this if you are windows users)

If you are using a computer with a mac or linux system, you need to additionally install another MRI data processing software, FSL, please go to https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation, and follow the steps on the web page to download and install it. Alternatively, you can install the docker version of DPABISurf to skip this step.

(4) DPABI/DPARSF

Please go to http://rfmri.org/DPABI to download the latest version of DPABI (including DPARSF).

Installation of SPM and DPABI/DPARSF. Remember that the software path should not include any spaces, Chinese characters or special characters!

After downloading, open MATLAB and click "Set Path" (Figure 2).

Figure 2. Set path

First, click "default" to restore the path. Next click “Add Folder”to add SPM path (don't "Add with subfolders" for SPM). And then click "Add with subfolders" (Figure 3), find the location where DPABI is stored in the pop-up window and click "open" to add it. Finally, click "save" and close this window.

Figure 3. Add with subfolders

After that, you can input "dpabi" in the "command window" and press Enter. When you see the interface as shown below, you successfully completed the installation of DPABI/DPARSF.

Figure 4. DPABI

2. Data collation

DPABI/DPABISurf is a scientific and efficient R-fMRI pre-processing pipeline. But if you want DPABI/DPARSF to run smoothly, you need to organize your data in strict accordance with the requirements of DPABI/DPARSF. Tips: You can use DPABI->Utilities->DPABI Input Preparer to organize your data! When you are organizing data, please use DPABI->Utilities->Check Data Organization repeatedly to check whether your data organization is qualified! Almost all the errors as "index exceeds dimensions" can be solved by the Check Data Organization!

(1) Create a "working directory"

Create a folder of any name (but it cannot contain any spaces, Chinese characters or special characters!) anywhere you want, which is the "working directory" of preprocessing. Most of the preprocessing operations are under "working directory". This is a very important concept, so please keep it in mind. For demonstration, we created a folder named "dpabi" as the working directory (Figure 5).

Figure 5. Working directory

(2) Copy the MRI data of subjects

Next, we need to the MRI data of subjects under the working directory according to the requirements of DPABI/DPARSF. The following is an example of three subjects:

Figure 6. An example of 3 subjects

This figure shows the form of the created folder. The working directory should include folders named "FunRaw" and "T1Raw". Each of them contains three folders: "Sub001", "Sub002", " "Sub003". This example is of the situation of three subjects, please follow this pattern for more subjects.

The “FunRaw” folder contains the functional image data, while the “T1Raw” folder contains the structural images. You need to select the folder containing functional images or structural images from the raw data, and then copy the image data into the corresponding folder.

Note 1: DPABI/DPARSF has very strict requirements on sorting the data format under the working directory. The names of the two folders "FunRaw" and "T1Raw" must be in full compliance with this form, and should not be changed, otherwise the “error” will be reported. Although the name of subject folders such as "Sub001", "Sub002", and "Sub003" are more arbitrary and you can change them according to your needs, you should still keep the names of corresponding subject folders in "FunRaw" and "T1Raw" are exactly the same. Any difference will cause an error. An example is when a student accidentally entered an extra space at the end when naming a folder, which resulted in an error.

Note 2: The example here fits when the raw data you had is in dicom format. If your data is in NIFTI format, please rename the two folders "FunRaw" and "T1Raw" as "FunImg" and "T1Img". The way to judge the dicom/NIFTI format: the number of data files in the dicom format is very large (hundreds to thousands); while the number of data files in the NIFTI format is one for each subject and each sequence is only one (4D .nii file) or hundreds (3D .img/.hdr files).

Note 3: Generally speaking, the raw data is organized according to the sequence and the data of each scan sequence has its corresponding folder. But sometimes the data is completely messy, then you need to use the "Dicom Sorter" function of DPABI to organize the messy raw data into a form that we can understand.

To open Dicom Sorter, please call DPABI and click Utilities->DICOM Sorter

Figure 7. Dicom Sorter

Fill in the suffix of the original file in the "Suffix" box. If there is no suffix, clear this box. Next click "Add All" to find the folder that contains all the original files. Finally enter the output directory you want in "Output Dir" box and click the "Sort" button. It should be noted that if there is no suffix, the original folders should not contain any other types of files except DICOM ones, otherwise you will get an error.

(3) What should I do if “errors” show up?

It's frustrating to see "the red", but you can always log in at http://rfmri.org/DPABIDiscussion, and quickly search by the keyword of the error to see how the previous people solved it. If you do not find the relevant answer, you can also post for help. However, you may need to wait for a while to get the solution. So, before you asking for help, we have a few simple tips for you to take home and worth trying when "the red" shows up.

(1) Run with our Demo Data

Please go to http://rfmri.org/DemoData to download the demo data for processing.

(2) Run with data of one/several subject(s)

You can randomly select one or several subject(s) to run as a test. If your data of these subjects can pass the test, then there is a high probability that the error is caused by the data of some other subjects. At this time, you need to carefully take a look at whether the name of some folder does not correspond strictly, or whether the data of some subject is not copied completely. You can easily infer it from the number of dicom files. Normally, the number of dicom files for each sequence of a same batch of subjects is also the same. You can easily find the problem where the number of dicom files of a subject is inconsistent with others.

(3) Reinstall the software/use another computer

If errors were always reported even though you had tried with data of many subjects, the issue may get a bit tricky. It may be caused by the unfitness of the operating environment. At this time, you can try to uninstall the software, then reinstall it and reboot your computer. Or simply using another computer may resolve this issue. This operating sequence of solutions can be considered: 1) rerun; 2) shutdown and restart matlab; 3) reboot the computer; 4) reinstall DPABI/SPM; 5) reinstall matlab; 6) reinstall windows; 7) try another computer.