How to start ExploreASL

While the content of the text below is correct and ExploreASL is still using a similar structure and step, the specific details of ExploreASL calls changes in new ExploreASL version. Please refer to the Installation and Execution Tutorials.

NB: At the end of this tutorial it is possible to find an explanation of how to run a TestDataSet in ExploreASL.

1. Download ExploreASL in https://github.com/ExploreASL/ExploreASL. It is possible to download it using the terminal by typing 'git clone' followed by the https link (see figure). It is also possible to download ExploreASL by clicking 'Download ZIP'.

2. Initialize ExploreASL on matlab. Inside the folder that contains ExploreASL, just type ExploreASL() to initialize.







3. What is needed to run ExploreASL:

ExploreASL('root folder',1,1) is the the main command, to run everything in ExploreASL.

Before running it, it is needed to prepare this 'root folder' in a specific way.

4. How to prepare your data for ExploreASL import and processing?

a) First, your root folder must have a sourcedata folder with you subjects' folders, just like it is shown in the figures.



Inside each 'sub-xxxx' folder, you should have folders (ASL, FLAIR, M0, T1) containing the dicoms files of each scan time.


b) Second, the sourcestructure.json and studyPar.json that you see in the first printscreen, must have this format (see figures).

-> The studyPar.json must contain some important parameters for the processing. Note: The times must be in seconds. The ASLContext vector will have "control, label" as many times as you control-label pairs you have (in this case we have 30 control-label pairs).

-> For the sourceStructure.json, regular expressions are used to describe the layer hierarchy of the folders.
E.g., in this folderHierarchy field (see figure), there are two layers separated by a coma: the first one is the regular expression of how your subjects' names are written in the sourcedata - see above: sub-4numbers - and the second layer of folders in this case is ASL,M0,T1,FLAIR. More information on how to create the sourceStructure.json file (how to write the 'folderHierarchy', 'tokenOrdering', etc) is shown here.





4.1. After all this, you are ready to start running ExploreASL.

ExploreASL('root folder', 1, 0) will perform the import module. Here, 'root folder' is the directory which contains your sourcedata folder. The import module is divided in 4 submodules:

  • ExploreASL('root folder', [1 0 0 0], 0): Runs the DICOM to NIFTI conversion (DCM2NII), and creates a temporary folder ('temp') containing the niftis created from the dicoms.

  • ExploreASL('root folder', [0 1 0 0],0): Runs the NIFTI to BIDS conversion (NII2BIDS), and creates a 'rawdata' folder.

  • ExploreASL('root folder', [0 0 1 0],0): Runs the defacing of structural scans (DEFACE).

  • ExploreASL('root folder', [0 0 0 1],0): Runs the BIDS to LEGACY conversion (BIDS2LEGACY), creating a 'derivatives' folder, which has the data formatted for the ExploreASL analysis pipeline.

At the end of the import module, your root folder will look like this (see figure).


When you instal ExploreASL, there is a folder that has a TestDataSet (ExploreASL/External/TestDataSet) that you can use to explore and check the hierarchy of the folders. It doesn't have dicoms, so it already starts with the rawdata folder (niftis sorted in BIDS format). A README file can be used to support the user with more information.

After the import, ExploreASL('root folder', 0, 1) will perform the processing modules. There are 3 processing modules:

  • ExploreASL('root folder', 0, [1 0 0]: Runs the Structural Module (STRUCTURAL).

  • ExploreASL('root folder', 0, [0 1 0]: Runs the ASL Module (ASL).

  • ExploreASL('root folder', 0, [0 0 1]: Runs the Population Module (POPULATION).

7. At the end of the processing



After the processing, inside the derivatives/ExploreASL/Population directory, it will be possible to find most of the results.



Inside 'derivatives/ExploreASL/Population/Stats' you will find the results of the statistics, containing the CBF values of GM, WM, specific ROIs from atlases that you can add to the studyPar.json (e.g. Hammers atlas, Harvard-Oxford atlas, etc. More information about the atlases can be found here in the 'Atlas Options' subchapter).