Before running xASL

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 Processing Tutorial.

First, it is advisable to check the import_summary.csv: are all scans imported correctly, and are the parameters that should be equal for multiple scans (e.g. nt) really equal? Then, it is advisable to quickly view a few samples of the imported NIFTIs, e.g. T1, 3D ASL, 3D M0, 2D ASL, and to quickly check whether all directories are created.

The ExploreASL_master_script.m can be called in Matlab, or opened in the Matlab script editor to run part-by-part:

All covariates saved in *.mat files in the root directory (e.g. analysis//Sex.mat are included if they fit the requirements (cell structure with first column SubjectName in strings, second column SessionName if this covariate is different for multiple sessions, and a third (or second if no SessionNames) column for the data (e.g. 0 or 1 for male/female, or continuous numbers). Another requirement is that the name of the variable is the same as the name of the .mat file (e.g. Sex.mat containing the variable Sex).

Most covariates are used only by the statistical part of ExploreASL, but some covariates are reserved for the post-processing methods. E.g. hematocrit-corrections for blood T1 (beta), or age. If there are multiple time points defined as _1, _2 : _n suffix in SubjectNames (e.g. SubjectName_1, SubjectName_2 : SubjectName_n), Longitudinal Registration will be initialized in the T1 module. If age.m is included, the subjects age at each scan will be used to model atrophy by SPM12's Longitudinal Registration, otherwise a default age difference of 1 year between scans is assumed.

DATA_PAR.m

This file should be placed in the root analysis directory. Open this file to check and adapt some settings. DATA_PAR_TEMPLATE.m inside ExploreASL provides a template and further explanation.

symbols.name = 'StudyName'; This is the study ID.

symbols.subject_regexp = '^\d{3}$';

This is the regular expression that ExploreASL uses to search for its subjects. In this example, subjects are coded by three digits \d{3}, e.g. 101 and 102. In case of a longitudinal study, this would have been \d{3}_\d where the last \d codes for the time point.

symbols.exclusion = ''"; This lists subjects that should be excluded from the analysis. E.g. {'101' '102'} would exclude subjects 101 & 102 from the analysis. It is good practice to exclude bad data quality scans from the post-processing as well, as they can influence the quality of the non-linear registration and creation of a group template. If no subjects are excluded, this should remain '"';

load(fullfile(symbols.ROOT,'InclusionList.mat'));

symbols.ForceInclusionList = InclusionList;

% Use this field if you want to use a selection of subjects rather than taking all available subjects from directories

symbols.ROOT = the root directory of the data (analysis/).

if you don't want to include all subjects, but rather want to force to include only a specified list of subjects, you can use symbols.ForceInclusionList to specify a list of subjects you want to include. This should be in the same cell-string format as abovementioned.

symbols.SESSIONS = {'ASL_1','ASL_2'}; This contains the session names, this should be ASL_1 ASL_2 : ASL_n to designate the different ASL sessions. Don't specify more sessions than there are available. If some subjects have missing sessions, this will currently create an error to make sure that this does not go unnoticed in case of import errors. Therefore, if there are actual missing sessions, simply clone the other available session and delete this afterwards. If there is more than one session, sessions will be a covariate or set.

symbols.session.options = {'morning' 'evening'}; This defines the names of the sessions.

For any of the covariates/sets provided as //analysis/*.mat, make sure these are cells with first column SubjectNames, second column SessionNames (if sessions exist) & third (or second if no sessions) column contains the data values for this covariate/set. The name of the variable containing this should be identical to the mat-filename. Use NaNs for missing data, not e.g. 9999. 9999s will mock up a parametric analysis whereas NaNs will be treated as missing values.

symbols.M0 defines which M0 method is used. It can be either a numeric value (e.g. 3.7394*10^6), obtained from a previous population on the same scanner with the same ASL scan protocol. In this case, all scans will be divided by this single number. Alternatively, this can be 'no_background_suppression' if no background suppression has been applied in the ASL scans. In this case, the mean control image will be used as M0. Finally, 'separate_scan' tells ExploreASL to use a separate M0 scan (i.e. M0.nii and M0_parms.mat).

symbols.BackGrSupprPulses : This tells ExploreASL what kind of background suppression was employed. Examples include: 2 (Philips 2D EPI & Siemens 3D GRaSE) 5 (GE 3D spiral) or 4 (Philips 3D GRaSE). This will be used to adapt the quantification for the loss of labeling efficiency by the use of background suppression pulses, e.g. a factor of 0.83 for 2 pulses or a factor of 0.75 for 5 pulses ².

symbols.init_PLD = 1800;

symbols.labdur = 1800;

These are the initial post-labeling delay (PLD) and labeling duration used for the ASL scan. These are rarely found in the DICOM header fields, and they should thus be obtained from the ASL scan protocol from the scanner. We call the PLD the initial PLD, because for 2D multi-slice scans the PLD increases with ascending slices, as described below.

symbols.readout_dim : This tells ExploreASL whether it deals with '2D' or '3D' ASL data.

symbols.PLDslicereadout : For a 2D ASL scan, ExploreASL assumes that the readout was a sequential ascending multi-slice readout, in which each slice is being readout later in time. The time it takes for a single slice to be readout is defined here, and ExploreASL will adapt the PLD accordingly: as each slice is being readout later in time, it means the PLD increases for each slice with this slice readout time. This PLDslicereadout should be a numeric value between 10-50 ms. It can be approximated emperically by 2.25 TE, but this is not the best to use. For Philips and Siemens 2D scans, this value can be estimated by (minimalTR - initial PLD - labeling duration)/NumberOfSlices, since these vendors scan all slices as quickly as possible and then insert a waiting time until the end of the TR. Note that all here refers to a single TR, so e.g. NumberOfSlices should be the number of slices in a single volume (e.g. 15-20), not in the full time-series (e.g. 1000-3000)! GE spreads all slice readouts evenly in the left time, so for 2D ASL scans from this vendor it should be (TR-initialPLD-labeling duration)/NumberOfSlices. The minimalTR is sometimes mentioned in the exported MRI scan protocol, or can be found by setting the TR of the ASL scan on shortest. For 3D ASL scans, this parameter is ignored since the complete volume is readout at once.

symbols.QUALITY : When this parameter is set to 1, all post-processing will run on normal, optimal quality. When it is set to 0, all post-processing will run on low quality. In this case, post-processing steps are performed much faster. The results should still approximate the results that would be obtained with normal quality, so it should still function as it should, but in a few cases registration might be off because of less iteration steps. This is useful to quickly try out ExploreASL, and to become familiar with its steps before running the full data analysis.

symbols.SpikeRemovalThreshold : This pertains to the modified ENABLE method (described below in the ASL module) to find control-label pairs with motion spikes that should be excluded because they add more nuisance/variance than meaningful signal. This parameter states how much the mean temporal SNR needs to be improved by removing control-label pairs, which functions as a kind of regularization parameter for the ENABLE method.

symbols.motion_correction : This enables (1) or disables (0) motion correction.

symbols.DELETETEMP : This removes (1) or keeps (0) temporary files.

symbols.Vendor : This specifies vendor-specific processing. Some MRI vendors store the ASL data in rescaled format, so the quantification may be slightly different. Options include GE_product and GE_WIP (for the 3D spiral product sequence or the Work In Progress (WIP) sequence), Philips or Siemens.

symbols.LabelingType : This specifies the quantification according to the consensus paper for either (pseudo-)continuous ('CASL') or pulsed ASL ('PASL'). The latter assumes Q2-TIPS, since previous PASL methods cannot be quantified because they don't have a well-defined label bolus. The difference between both quantifications is essentially that with PASL the complete bolus has been labeled at a single time point, and we assume that the total label bolus has experienced the same T1 decay, whereas for CASL the label has been created during the labeling duration. Therefore, for CASL the latest labeled spin has only experienced T1 decay during the PLD, whereas the earliest labeled spin has experienced T1 decay during labeling duration + PLD. Therefore, it is important to note that the average spin has experienced T1 decay during 0.5*labeling duration + PLD. In other words, when we discuss the sensitivity of ASL to transit times, we should account for the fact that the majority of our CASL label has had more time to travel to the imaging voxel within the brain than the PLD. Note that PCASL has the same quantification as CASL. In addition, with PASL we assume a labeling efficiency of 0.98 ³ whereas for CASL we assume a labeling efficiency of 0.85 ⁴.

symbols.qnt.labda = 0.9; This is the brain-blood water coefficient, according to the consensus paper ¹. This should be tissue specific and is another parameter that we could measure, but this would introduce noise and registration errors. The pragmatic approach is to assume 0.9 everywhere.

symbols.qnt.T2art = 50; This is the T2* time at 3T, which is only used for T2* correction of 2D ASL data. If we divide by a reference scan (M0 or mean_control image), this T2* correction is taken care of since we assume that this reference scan has had the same T2* decay as the perfusion-weighted image (PWI).

symbols.qnt.T1a = 1650; This is the T1 of arterial blood at 3T, according to the consensus paper.

symbols.T1_DARTEL : This enables (1) or disables (0) further non-linear spatial normalization using the DARTEL method based on the high-resolution 3D T1-weighted images ⁵.

symbols.BILAT_FILTER : This disables (0) or enables a filter that deals with image acquisition artifacts that have a high temporal frequency but low spatial frequency. The reason to create this filter was a fat suppression (SPIR) artifact in the ASL sequence of the Ingenia scanner, which is discussed in more detail in the ASL module. Filter options are a whole-brain bilateral filter (1) or a filter based on regions outside the GM (2), as an attempt to preserve the temporal and spatial variation in the GM region while correcting the artifact.

If all parameters are defined correctly, all path definitions are correct and all required software is installed, the following overview screen should be shown, which contains information about the symbols table (containing sets of covariates if they were present) as well as an overview of subjects and sessions of the data that will be analyzed: This should be checked to ensure that the correct data selection will be processed. This is especially important for processing that concerns multiple 'subjects', such as DARTEL or longitudinal registration in case of multiple time points. The following overview screen contains an example with 6 sets, of which 2 (sessions and cohorts) were defined a priori, and the other ones were acquired upon quality control of the data after post-processing (i.e spatial CoV, segmentation and head motion measurements). So, upon starting of analysis of this dataset, only the first 2 sets of covariates would be present and in the end all sets.

When you want a SubjectSession specific quantification parameters, you should put them in a .mat file in the analysis root directory, where the variable inside this mat file should have the same name as the filename.

Log files

For each module, ExploreASL will print its screen output in separate *.log files for each subject/session and module:

/analysis/SubjectName/Struct_module.log

/analysis/SubjectName/ASL_1/ASL_module.log

/analysis/SubjectName/dartel/DARTEL_T1_module.log

/analysis/SubjectName/dartel/Population_module.log

These files can be useful to read back if something went wrong, or to check if there were any errors along the way.

Status lock files

For each module, ExploreASL employs *.status files within the analysis/lock directory to track its progress. When a module is running, a dummy directory locked is created (e.g. analysis/lock/Struct/SubjectName/Struct_module/locked for the sstructural module of the first subject), which prevents that the same files are processed twice at the same time, in case of parallel processing. When a part of a module is ready, a *.status file will be created (e.g. analysis/lock/Struct/SubjectName/Struct_module/001_coreg_T12MNI.status when the first part of the structural module (T1w->MNI rigid-body registration) is done.

Registration checks for left-right flips

In between modules, CSV-files are saved in the ROOT directory containing orientation matrix information. From the original matrix, and from the new matrix minus the original matrix, allowing to check both the original values (i.e. scanner information plus whether dicom2nii performed correctly) and the effect of registration. It is important to check that the determinant has the same sign (+ve or -ve) for all scans from same scanner, otherwise there could have been a flip. This left-right flip is important, as it is the only flip that we can easily miss visually, and also will be "falsely" or not corrected by registration algorithms.

The use of CreateFileReport.m

When you start running ExploreASL, just after the structural module, you want to first check whether processing is fully completed, and secondly do the visual QC. You can either do this by checking the lock files. E.g. for the structural module: //lock/Struct/SubjectName/Struct_module should for each SubjectName contain the following .status files, that show that the parts of the structural module that were completed successfully. In Windows this looks like:

Alternatively, you can check whether all QC visualizations are created, since this is the last part of each module. E.g. //dartel//T1w_CoregCheck/ should contain the same number of rT1_ORI_SubjectName.jpg files as there are subjects. The CreateFileReport.m function does this for you, for all original NIfTI files in native space, as well as the NIfTI files created in the common space (in the dartel folder), the lock files and all the QC visualizations. It counts all these files in //FileReportSummary.csv and shows the missing files in the //Missing*Files.csv.

Private fields DICOM headers Philips ASL data

For global CBF quantification of Philips ASL, we require DICOM scale slopes. Without them, we can still quantify the relative CBF, but the global CBF will contain large undesired variance through the uncorrected Philips scale slopes. The DICOM scale slopes are stored by Philips in manufacturer-specific (i.e. private) DICOM fields. Private fields have an odd group number, e.g. 2001,xxxx or 2005,xxxx for Philips private data.

Many standard DICOM anonymization algorithms remove all information in private DICOM fields, since it cannot be predicted by the algorithm whether personal data are or are not stored in them. Because we require the information in those fields for the quantification of global CBF, it is essential to keep all manufacturer-specific (private) fields, except for field 2005,1391 that contains a copy of the patient name.

Standard DICOM fields have an even group number. Those fields can be anonymized according to GCP guidelines.