Skip to content

Tutorials (Basics)

How to run ExploreASL using Matlab

The first thing you have to do, to use ExploreASL, is to clone the ExploreASL repository. If you want to run ExploreASL from Matlab, we recommend to clone the main repository directly from the official GitHub website. You also have the option to download the zipped version or to download an older release.

If you are new to Matlab, we recommend checking out a Matlab tutorial. It can be helpful to add the ExploreASL directory to your Matlab paths. Open Matlab, select the Home tab, and add the ExploreASL directory including its subfolders using the Set Path option. Now change your working directory, using the Current Folder tab or the cd command, to the ExploreASL directory.

To run ExploreASL you have to type in the following command in the Command Window: ExploreASL. If you already created an ASL-BIDS dataset in sourcedata format, you can run the full default ExploreASL pipeline like this:

DataParPath = 'C:\...\MY-BIDS-DATASET\DataParFile.json';
ImportModules = true;
ProcessModules = true;
bPause = false;
[x] = ExploreASL_Master(DataParPath, ImportModules, ProcessModules, bPause);

How to run a compiled ExploreASL Version

To compile ExploreASL you have to run the xASL_adm_MakeStandalone.m script. If necessary, you can also ask the developer team for a specific compiled version. Providing a compiled version for every operating system and corresponding Matlab version is currently not feasible for us. Please feel free to ask us for help though! A compiled version of ExploreASL always requires the corresponding Matlab Runtime. Please checkout the official Matlab Documentation. Download the Matlab Runtime of the Matlab Version which was used for the compilation. Make sure to install the Matlab Runtime correctly. If you're using Windows, it is important that the path to the Matlab Runtime is added to Windows PATH during the installation.

Windows

Let's assume you want to run the compiled version of ExploreASL latest. Check the contents of the folder created by xASL_adm_MakeStandalone.m, which contains the compiled version. There should be a file called xASL_latest.exe. We recommend using the command line interface now. For this you can go to the address bar of your file explorer. Type in cmd to open the command prompt in the current folder. The following command will start ExploreASL, import the ASL-BIDS dataset in sourcedata format, and process the dataset of your sourceStructure.json file:

xASL_latest.exe "c:\MY-BIDS-DATASET\sourceStructure.json" "1" "1"

The executable will extract all necessary data from the CTF archive within the folder. This is totally normal. Within the command window you should see that ExploreASL is starting to process the given dataset:

xASL_latest.exe "c:\MY-BIDS-DATASET\sourceStructure.json" "1" "1"
(insert example here)

To test if it is possible to initialize ExploreASL without the processing of a dataset, you could run the following command:

xASL_latest.exe "" "0" "0"

The usual ExploreASL parameters (DataParPath, ImportModules, ProcessModules, bPause, iWorker, nWorkers) have to be given to the compiled ExploreASL version as strings. The resulting output could look like this:

xASL_latest.exe "" "0" "0"
(insert example here)

Linux

On Linux you can basically do the same as above. We can run the ExploreASL shell script with a specified Matlab MCR (here we use version 96 e.g.) using the following command:

./run_xASL_latest.sh /usr/local/MATLAB/MATLAB_Runtime/v96/ "" "0" "0"

Using the options "" "0" "0" we initialize ExploreASL, but do not process a dataset. To run a dataset, we have to switch the ImportModules and/or the ProcessModules parameter from 0 to 1 and pass a path for the DataParPath. This could look something like this:

./run_xASL_latest.sh /usr/local/MATLAB/MATLAB_Runtime/v96/ "/home/TestDataSet/analysis/DataParFile.json" "1" "1"
(insert example here)

How to run ExploreASL using the docker image

First you have to pull an official docker image from the ExploreASL repository:

docker pull exploreasl/xasl:latest

Check out your local images using docker images. If you want to rename the docker image, tag your image using the docker tag command:

docker tag exploreasl/xasl:latest xasl:my-version

To start a docker container of ExploreASL v1.6.0 e.g., you can use the following command:

docker run -e DATAPARFILE=TestDataSet/sourceStructure.json
       -e IMPORTMODULES=1 -e PROCESSMODULES=1
       -v /home/.../incoming:/data/incoming 
       -v /home/.../outgoing:/data/outgoing xasl:1.6.0
  • Here DATAPARFILE is an environment variable which is a relative path to the data parameter file of your dataset.
  • The IMPORTMODULES and PROCESSMODULES are the parameters of ExploreASL_Master
  • /home/.../incoming:/data/incoming is used to mount your dataset folder (/home/.../incoming) to its corresponding docker dataset folder (/data/incoming).
  • The same notation is used to mount the docker dataset output folder (/data/outgoing) to its corresponding real output folder on your drive (/home/.../outgoing).