Functions

General Functions

xASL_Iteration.m

Format:

[bAborted, xOut] = xASL_Iteration(x, moduleName[, dryRun, stopAfterErrors])

Description:

Parses the settings and runs the DatabaseLoop sub-function.

Administration

xASL_adm_CatchNumbersFromString.m

Format:

[OutputNumber] = xASL_adm_CatchNumbersFromString(InputString)

Description:

Extracts a number from a char array.

xASL_adm_CheckFileCount.m

Format:

[result, files] = xASL_adm_CheckFileCount(path, expr[, mincount, failifmissing])
[result]        = xASL_adm_CheckFileCount(...)

Description:

Checks the given PATH for files corresponding to the SPM_SELECT regular expression EXPR. Returns if the number of files is equal to or higher than MINCOUNT. If FAILIFMISSING is true and not enough files, then throw and error. If everything goes ok and second output argument is specified then return also the list of files.

xASL_adm_CheckPermissions.m

Format:

[FilesList, FilesExeList, FoldersList] = xASL_adm_CheckPermissions(InputPath[, FilesExecutable])

Description:

This function does a recursive search through the root folder & makes a list of the attributes of all files and folders. It tries to reset the attributes to what we desire, which is by default:

664 for files (meaning only reading & writing for users & group, & read-only for others)
775 for folders (meaning reading, writing & opening for current user & current group, & for others only reading & opening)

For executable files we also want 775. Note that the permission to 'execute a folder' means opening them.

DataOK checks data permissions.
ExeOK checks executable permissions.
DataOK also includes executable permissions for folders.
This runs recursively (but currently skips the contents of the root-folder) .

xASL_adm_CheckSPM.m

Format:

[spm_path, spm_version] = xASL_adm_CheckSPM([modality, proposed_spm_path, check_mode])
[spm_path]              = xASL_adm_CheckSPM(...)
xASL_adm_CheckSPM(...)

Description:

Checks if the spm function exists and if the reported version matches our development version (SPM8 or SPM12). If the spm toolbox is not available yet, it will try the PROPOSED_SPM_PATH (if specified) or the user selected directory and add it to PATH. The function will fail if SPM cannot be found or if detecting an unsupported version.

xASL_adm_CleanUpBeforeRerun.m

Format:

xASL_adm_CleanupBeforeCompleteRerun(AnalysisDir, iModule, bRemoveWMH, bAllSubjects, SubjectID)

Description:

This function (partly) reverts previous ExploreASL runs, deleting derivatives, while keeping raw data intact. if bAllSubjects==true, then all subjects and all module derivatives will be removed. This function performs the following steps:

If a Population folder doesn't exist yet but dartel does, rename it
Remove whole-study data files in AnalysisDir if bAllSubjects
Remove lock files/folders for reprocessing
Restore backupped _ORI (original) files
Delete native space CAT12 temporary folders (always, independent of iModule)
Remove native space files for iModule
Remove standard space files for iModule
Remove population module files
Remove or clean up stored x-struct & QC file -> THIS HAS NO SESSION SUPPORT YET

NB: still need to add xASL_module_func & xASL_module_dwi for EPAD

xASL_adm_CompareDataSets.m

Format:

[RMS] = xASL_adm_CompareDataSets(RefAnalysisRoot,SourceAnalysisRoot,x,type,mutexState)

Description:

Compare data sets is used to ...

type 0: Only save
type 1: Save and evaluate
type 2: Only evaluate

xASL_adm_CompareLists.m

Format:

[NewList] = xASL_adm_CompareLists(list1, list2)

Description:

This script compares two single dimension lists.

xASL_adm_ConvertDate2Nr.m

Format:

[Nr DayInYear] = xASL_adm_ConvertDate2Nr(TempDate)

Description:

Converts date to number input mmdd -> output mm (with days in fractions/floating point). Inverse from ConvertNrDate.

xASL_adm_ConvertNr2Time.m

Format:

Time = xASL_adm_ConvertNr2Time(Nr)

Description:

Converts number to time input hh (with minutes in fractions/floating point) -> output hhmm. Inverse from xASL_adm_ConvertTime2Nr.

xASL_adm_ConvertSubjSess2Subj_Sess.m

Format:

[iSubj iSess] = xASL_adm_ConvertSubjSess2Subj_Sess(nSessions, iSubjSess)

Description:

Converts combined SubjectSession index to subject & session indices. Useful for data lists in ExploreASL.

xASL_adm_ConvertTime2Nr.m

Format:

Nr = xASL_adm_ConvertTime2Nr(Time)

Description:

Converts time to number input hhmm -> output hh (with minutes in fractions/floating point). Inverse from xASL_adm_ConvertNr2Time.

xASL_adm_CopyMoveFileList.m

Format:

[List] = xASL_adm_CopyMoveFileList(OriDir, DstDir, StrRegExp, bMove[, bDir, bRecursive, bOverwrite, bVerbose])

Description:

Moves a file to a file, a file to a directory, or a directory to a directory. It keeps the initial extensions, no unzipping or zipping after the move. But it makes sure that only one of .nii and .nii.gz exists in the destination directory. Useful to split a large database.

xASL_adm_CorrectName.m

Format:

strOut = xASL_adm_CorrectName(strIn[, bOption, strExclude])

Description:

Finds and replaces all non-word characters either by empty space or by an underscore. Optionally leaves in few selected special characters. Note that if '_' is excluded from replacement, but option 2 is on, then underscores are replaced anyway.

xASL_adm_CreateFileReport.m

Format:

x = xASL_adm_CreateFileReport(x, bHasFLAIR, bHasMoCo, bHasM0, bHasLongitudinal)

Description:

Prints a summary of created files or the individual modules (i.e. Structural, Longiutudinal & ASL modules). Provides a quick check to see what has been skipped, an whether all files are present.

This script iterates across: Native space 1) subject and 2) session files, Resampled 3) subject and 4) session files, 5) Lock files and 6) QC Figure files.

For all we perform a:

A) Count of the files present, summarized in FileReportSummary.csv
B) List of the missing files in "Missing*.csv" files

PM: Simplify/optimize this code, to make filename variable changing, search within subject-directories, etc. Combine the parts searching for missing & summarizing count.

xASL_adm_DefineASLResolution.m

Format:

x = xASL_adm_DefineASLResolution(x)

Description:

If the parameters x.ResolutionEstimation == 1, it initializes the resolution with expected values per sequence type and then runs the procedure xASL_im_ResolutionEstim to estimate the resolution from the mismatch between ASL and structural data. For x.ResolutionEstimation == 0, xASL_init_DefaultEffectiveResolution the educated guess is used for the estimated resolution using previous data and analyzis.

xASL_adm_DefineASLSequence.m

Format:

[x] = xASL_adm_DefineASLSequence(x)

Description:

This ExploreASL function tries to check what ASL sequence is being processed, if this was not already defined in x.Sequence. It does so by checking known combinations of readout dimensionality (x.readout_dim) and vendor, knowing the product sequences of the vendors.

xASL_adm_DeleteFilePair.m

Format:

filepaths = xASL_adm_DeleteFilePair(path, ext1[, ext2 [, ext3 ...]])
xASL_adm_DeleteFilePair(path, ext1[, ext2 [, ext3 ...]])

Description:

Delete the file given in PATH, and also deletes files with the same name, but with extension given in EXT1, and potentially also EXT2, EXT3...

xASL_adm_Dicom2Parms.m

Format:

[parms pathDcmDictOut] = xASL_adm_Dicom2Parms(inp[, parmsfile, dcmExtFilter, bUseDCMTK, pathDcmDictIn])

Description:

The function goes through the INP files, reads the DICOM or PAR/REC files and parses their headers. It extracts the DICOM parameters important for ASL, makes sure they are in the correct format, if missing then replaces with default value, it also checks if the parameters are consistent across DICOM files for a single sequence.

xASL_adm_DocCrawler.m

Format:

xASL_adm_DocCrawler(inputPath)

Description:

This function checks each individual file header and extracts the information. The results is saved as a markdown file.

If you want to use star symbols (*testFile.m e.g.) we recommend not to use them in the same line with bold text (which is written like this: bold text).

xASL_adm_DocInitialize.m

Format:

xASL_adm_DocInitialize

Description:

This function generates all markdown files, which are necessary for the mkdocs documentation.

xASL_adm_FindByRegExp.m

Format:

xasl_adm_FindByRegExp(root, dirSpecs[, varargin])

Description:

Recursively find files in the root directory according to the dirSpecs.

xASL_adm_FindStrIndex.m

Format:

INDEX = xASL_adm_FindStrIndex(ARRAY, STRING)

Description:

Similar to find, but then for a cell array filled with strings. Only takes 4 dimensions.

xASL_adm_GetFsList.m

Format:

RES = xASL_adm_GetFsList([strDirectory, strRegEx, bGetDirNames, bExcludeHidden, bIgnoreCase, nRequired])

Description:

List files or directories from a given path. And optionally uses regular expressions to filter the result with options to exclude hidden files, ignore case, and set a minimal requirement on the number of results. Sorts the results at the end.

xASL_adm_GetNumFromStr.m

Format:

num = xASL_adm_GetNumFromStr(str)

Description:

Obtains single number from string. CAVE there should only be one number!

xASL_adm_GetPhilipsScaling.m

Format:

scaleFactor = xASL_adm_GetPhilipsScaling(pathParmsMat,pathNifti)

Description:

This script provides the correct scaling factors for a NIfTI file. It checks the header of the NIfTI that normally has the same scaling as RescaleSlope in DICOM, it checks if dcm2nii (by the info in JSON) has already converted the scale slopes to floating point. And if not, the derive the correct scaling factor to be applied.

xASL_adm_GetUserName.m

Format:

UserName = xASL_adm_GetUserName()

Description:

Get the name of the current user.

xASL_adm_Hex2Num.m

Format:

outNum = xASL_adm_hex2num(inStr)

Description:

Takes a hexadecimal string and converts it to number or string. Works also when the string contains escape characters, and for single-floats and for a little and big endian. If containing 8 and less characters than treat as float, if more than as double.

xASL_adm_LesionResliceList.m

Format:

[INname, OUTname] = xASL_wrp_LesionResliceList(x,bLesion_T1,bLesion_FLAIR,bROI_T1,bROI_FLAIR)

Description:

Creates list of structural image paths to reslice.

xASL_adm_LoadParms.m

Format:

[Parms, x] = xASL_adm_LoadParms(ParmsPath[, x, bVerbose])

Description:

This function loads the internal memory x struct, any legacy *_parms.mat sidecar, any *.json BIDS sidecar, to use scan-specific parameters for image processing/quantification. Also, per BIDS inheritance, any x.S.SetsID parameters (from participants.tsv) are loaded as well. This function performs the following steps:

Load .mat parameter file
Load JSON file
Deal with warnings
Find fields with scan-specific data in x.S.Sets, and use this if possible (per BIDS inheritance)
Sync Parms.* with x.(Q.)* (overwrite x/x.Q)
Fix M0 parameter if not set

xASL_adm_LoadX.m

Format:

[x[, IsLoaded]] = xASL_adm_LoadX(x[, Path_xASL, bOverwrite])

Description:

This function loads x.Output & x.Output_im struct fields from the x.mat on the hard drive & adds them to the current x struct located in memory. If it didnt exist in the x.mat, it will set IsLoaded to false, which can be catched externally & a warning issued if managed so in the calling function. If it didnt exist in the memory x struct, or bOverwrite was requested, the contents of x.mat will be loaded to the memory x struct

xASL_adm_MakeStandalone.m

Format:

xASL_adm_MakeStandalone(outputPath, bCompileSPM, importDCM, markAsLatest);

Description:

This function creates an output folder including a standalone version of ExploreASL, which can be used with the Matlab Runtime outside of Matlab itself.

A quick fix to solve path dependencies etc. is to first compile SPM (but this can be turned off for speed).

This function performs the following steps:

Manage ExploreASL and compiler code folders
Capture version/date/time
File management output folder & starting diary
Handle SPM Specific Options
Manage compilation paths
Run SPM compilation
Run ExploreASL compilation
Print done

xASL_adm_OrderFields.m

Format:

outStruct = xASL_adm_OrderFields(inStruct,orderStruct)

Description:

Order fields in the structure inStruct to match orderStruct, unmatching fields in inStruct are copied as they are at the end, unmatching fields in orderStruct are ignored. This is just a cosmetic change and no values are edited.

xASL_adm_OtherListSPM.m

Format:

[OtherListSPM, OtherListOut] = xASL_adm_OtherListSPM(OtherList, bList4D)

Description:

bPadComma1 is to add the ,1 to the end of the pathstring, which SPM uses to assign the first image of a 4D image array (OPTIONAL, DEFAULT = true) bList4D: boolean, true for listing multiple 4D volumes separately in the list (OPTIONAL, DEFAULT=true).

xASL_adm_ParReadHeader.m

Format:

info =xASL_adm_ParReadHeader(filename)

Description:

Function for reading the header of a Philips Par / Rec MR V4.* file.

xASL_adm_RemoveLogFilesForRerun.m

Format:

xASL_adm_RemoveLogFilesForRerun(rootDir);

Description:

Removes all log files from any directory containing .log files.

xASL_adm_Remove_1_SPM.m

Format:

[OtherList] = xASL_adm_Remove_1_SPM(OtherList)

Description:

Remove ,1 at end of OtherLists, if exists. These are appended in CoregInit, OldNormalizeWrapper etc, since this should allow 4rd dim (e.g. as in ASL4D).

xASL_adm_ReplaceSymbols.m

Format:

strOut = xASL_adm_ReplaceSymbols(strIn, symbolTable[, bracketLeft, bracketRight])

Description:

It takes the STRIN on input, then looks for symbols between BRACKETLEFT and BRACKETRIGHT and replaces these symbols in in the string by the values provided in the SYMBOLTABLE as SYMBOLTABLE.SYMBOL, SYMBOLTABLE.D.SYMBOL, or SYMBOLTABLE.P.SYMBOL

xASL_adm_ResetVisualizationSlices.m

Format:

[x] = xASL_adm_ResetVisualizationSlices(x)

Description:

Removes any predefined slices that should be visualized, allowing to show the default slices. Comes in handy when different pipeline visualization parts are repeated.

xASL_adm_SaveX.m

Format:

xASL_adm_SaveX(x[, Path_xASL, bOverwrite])

Description:

This function saves the x.mat either to the predefined path or the the subject x.mat

xASL_adm_UnzipOrCopy.m

Format:

unpackedFiles = xASL_adm_UnzipOrCopy(srcDir, wildCard, destDir [, bOverwrite])

Description:

This is a simple wrapper function to (g)unzip one or more files to the specified destination directory. Existing files or directories will not be overwritten, unless forced with bOverwrite. A regular file-copy will be used if the source files don't have gz or zip filename extensions.

xASL_adm_Voxel2RealWorldCoordinates.m

Format:

[X Y Z] = xASL_adm_Voxel2RealWorldCoordinates(X,Y,Z,VoxelSize)

Description:

Converts MNI coordinates from voxel coordinates/indices. Assumes X Y Z = LR LeftRight AP AnteriorPosterior IS InferiorSuperior. VoxelSize should be [1 3]-sized input.

xASL_adm_ZipFileList.m

Format:

filepaths = xASL_adm_ZipFileList(strDirectory, strRegExp[, bRecurse, bUseGzip, nRequired])
xASL_adm_ZipFileList(strDirectory, strRegExp[, bRecurse, bUseGzip, nRequired])

Description:

Zip the files that match regular expression STRREGEXP in the given directory STRDIRECTORY. Zips recursively if specified in BRECURSE. Zips all files unless the number is specified by NREQUIRED, if the number is not met, then does not zip anything and throws an error.

xASL_adm_uiGetInput.m

Format:

[Parms] = xASL_adm_uiGetInput(Parms)

Description:

Checks whether input fields are present, or requests them.

BIDS

xASL_bids_Add2ParticipantsTSV.m

Format:

xASL_bids_Add2ParticipantsTSV(DataIn, DataName, x, bOverwrite)

Description:

This function adds metadata/statistical variables to the participants.tsv in the root/analysis folder, by the following steps. This function will iterate over Data provided at DataIn and fill them in the participants.tsv, overwriting if allowed. Empty data is filled in as 'n/a', and the first column "participants_id" is sorted for participants.

This function runs the following steps:

Admin - Validate that there are not too many columns
Admin - Detect nSubjectsSessions
Admin - Load pre-existing participants.tsv or create one
Admin - Get column number of data
Add data to CellArray
Sort rows on subjects
Fill empty cells
Write data to participants.tsv

xASL_bids_BIDS2Legacy.m

Format:

xASL_bids_BIDS2Legacy(pathStudy[, bOverwrite, dataPar])

Description:

This function converts BIDS rawdata (in pathStudy/rawdata/) to xASL legacy derivative format (e.g. pathStudy/derivatives/ExploreASL/)

Can be updated step-by-step when ExploreASL's derivative structure moves to BIDS NB: ask how Visits/session layer is defined in bids-matlab (should be separate layer within subjects, but now isn't?)

This function performs the following steps:

Parse a folder using bids-matlab
Define Subject
Define SubjectVisit
Parse modality
Parse scantype
Compile paths for copying
Manage sidecars to copy
Copy files
Parse M0
Create DataPar.json
Clean up

xASL_bids_CompareStructures.m

Format:

[identical,results] = xASL_bids_CompareStructures(pathDatasetA,pathDatasetB,[bPrintReport,threshRmseNii]);

Description:

Function that compares two BIDS folders with several subfolders and studies and prints the differences. We recommend to set bPrintReport to true, because you otherwise can't see significant file content differences.

xASL_bids_Config.m

Format:

bidsPar = xASL_bids_Config()

Description:

Creates several structures necessary for configuring the DICOM to BIDS conversion and saving of BIDS JSON files and NII structure.

xASL_bids_CreateDatasetDescriptionTemplate.m

Format:

[json] = xASL_bids_CreateDatasetDescriptionTemplate(draft)

Description:

This script creates a JSON structure which can be saved using spm_jsonwrite to get a dataset_description.json template. Missing fields that are required are added. BIDSVersion checked against the current configured version. Remaining fields will be validated. Other fields not belonging to dataset_description.json are ignored.

xASL_bids_DRO2BIDS.m

Format:

xASL_bids_DRO2BIDS(droTestPatient,[droSubject])

Description:

Prepare DRO test patient for BIDS2RAW conversion. This script uses the output of the asldro python script and converts it into a bids structure that can be read by our xASL_bids_BIDS2Legacy script. An exemplary usage is shown in the unit test called xASL_ut_UnitTest_function_BIDS2Legacy.

xASL_bids_Dicom2JSON.m

Format:

[parms pathDcmDictOut] = xASL_bids_Dicom2Parms(imPar, pathIn[, pathJSON, dcmExtFilter, bUseDCMTK, pathDcmDictIn])

Description:

The function goes through the pathIn files, reads the DICOM or PAR/REC files and parses their headers. It extracts the DICOM parameters important for ASL, makes sure they are in the correct format, if missing then replaces with default value, it also checks if the parameters are consistent across DICOM files for a single sequence.

Admin
Set up the default values
Recreate the parameter file from raw data

xASL_bids_GetPhoenixProtocol.m

Format:

[xasl,parameters,parameterList,phoenixProtocol] = xASL_bids_GetPhoenixProtocol(pathData,bUseDCMTK)

Description:

Function that reads raw DICOM data (".dcm" or ".IMA") and extracts the phoenix protocol parameters. Only works for Siemens DICOM data with phoenix protocol (tag = [0x29,0x1020]).

xASL_bids_JsonCheck.m

Format:

jsonOut = xASL_bids_JsonCheck(jsonIn,fileType)

Description:

It checks the existence of all BIDS fields, removes superfluous fields, checks all the conditions and orderes the structure on the output. It works according to the normal BIDS, or ASL-BIDS definition

xASL_bids_MergeNifti.m

Format:

NiftiPaths = xASL_bids_MergeNifti(NiftiPaths, seqType)

Description:

This function takes a list of M0 or ASL4D files and concatenates them together in a longer 4D volume if possible following certain patterns: works only with 3D and 4D files; all files in the list must have the same size of the first three dimensions; files are generarily sorted according to the last number in the filename and outputted to M0.nii or ASL4D.nii; first JSON is taken and renamed, all other JSONs and NIIs are deleted after merging; M0*_parms.m or ASL*_parms.mat is renamed to M0_parms.m or ASL4D_parms.m; M0 files are checked if the field PhaseEncodingAxis is consistent through all the volumes, if not the nothing is merged; this is applied to a generic case and 3 other specific Siemens scenarios are implemented:

i) All NII files have two volumes, then simply concatenate according to the last number.
ii) Two files with a single volume each are merged according to the last number in the file name.
iii) Multiple files with each containing a single volume are sorted to tags ASL4D_x_x_Y and controls ASL4D_Y and merged in the order of the last number in the filename (Y) alternating the tags and controls

This function performs the following steps in subfunctions:

xASL_bids_MergeNifti_M0Files Generic merging of M0 files
xASL_bids_MergeNifti_GEASLFiles Merge GE ASL files and extract scan order from DICOM tags
xASL_bids_MergeNifti_SiemensASLFiles Merge Siemens ASL files with specific filename pattern
xASL_bids_MergeNifti_AllASLFiles Merge any ASL files
xASL_bids_MergeNifti_Merge Merge NiftiPaths & save to pathMerged
xASL_bids_MergeNifti_Delete Delete NiftiPaths and associated JSONs
xASL_bids_MergeNifti_RenameParms Find *_parms.m files in directory and shorten to provided name

xASL_bids_MergeNifti_Delete.m

Format:

xASL_bids_MergeNifti_Delete(NiftiPaths);

Description:

Delete NiftiPaths and associated JSONs.

xASL_bids_MergeNifti_Merge.m

Format:

pathOut = xASL_bids_MergeNifti_Merge(NiftiPaths,indexSortedFile,nameMerged,bAlternatingControlLabel)

Description:

Merge NiftiPaths & save to pathOut.

xASL_bids_MergeNifti_RenameParms.m

Format:

xASL_bids_MergeNifti_RenameParms(Fpath,Fname);

Description:

Find *_parms.m files in directory and shorten to provided name.

xASL_bids_MergeNifti_SiemensASLFiles.m

Format:

pathOut = xASL_bids_MergeNifti_SiemensASLFiles(NiftiPaths)

Description:

Take a list of NIfTI files and concatenates 3D/4D files into a 4D sequence if possible (Siemens).

xASL_bids_Par2JSON.m

Format:

parms = xASL_bids_Par2JSON(pathPar, pathJSON)

Description:

Opens the Philips PAR file. Reads the relevant DICOM headers and saves them to JSON sidecar in a BIDS format. The JSON file is created automatically by the dcm2nii readout, so it always looks for this JSON file and add the same time reads the PAR file and adds further parameters to the JSON that were not identified by the dcm2nii tool.

xASL_bids_PhoenixProtocolAnalyzer.m

Format:

[bidsPar,sourcePar] = xASL_bids_PhoenixProtocolAnalyzer(parameterList);

Description:

This function analyzes the parameter list of the phoenix protocol (tag = [0x29,0x1020]). This function is usually called from xASL_bids_GetPhoenixProtocol.

xASL_bids_PhoenixProtocolReader.m

Format:

[parameterList,phoenixProtocol] = xASL_bids_PhoenixProtocolReader(rawPhoenixProtocol)

Description:

Function to parse the raw phoenix protocol. This function is usually called from xASL_bids_GetPhoenixProtocol.

xASL_bids_VendorFieldCheck.m

Format:

jsonOut = xASL_bids_VendorFieldCheck(jsonIn,bIsASL)

Description:

It checks all the JSON fields, make sure that they are renamed from vendor specific names to common BIDS names

xASL_bids_determineImageTypeGE.m

Format:

imageType = xASL_bids_determineImageTypeGE(jsonPar)

Description:

Determine the image type of a GE DICOM.

xASL_bids_parms2BIDS.m

Format:

outBids = xASL_bids_parms2BIDS(inXasl[, inBids, bOutBids, priorityBids])

Description:

This functions takes two parameter structures and merges them. At the same time, renames all fields according to the output type (note that only some fields have two standardised names different between the two formats. In case of duplicities, takes the field value from the preferred format. Also takes into account that the units in BIDS are s, but in xASL ms. This function performs the following steps:

Define field names that need to be convert/renamed/merged
Convert XASL fields to the output format (BIDS or XASL)
Convert BIDS fields to the output format (BIDS or XASL)
Merge the BIDS and XASL fields, convert field values

xASL_bids_parseM0.m

Format:

xASL_bids_parseM0(pathASLNifti)

Description:

Check the .JSON and aslContext.tsv sidecards of an ASL file in BIDS format and find the specified M0 possibilities. Then it converts the ASL file to ExploreASL legacy format including splitting of ASL and M0 NIFTIes if needed. Note that the sidecars are in BIDS, but the file-structure is already expected to be in Legacy format

FSL

xASL_fsl_RunFSL.m

Format:

[x] = xASL_adm_RunFSL(FSLCommand, x[, OutputZipping])

Description:

This function runs an FSL command from ExploreASL:

Checking the FSL dir
Manage CUDA/CPU parallelization (currently disabled, WIP)
Setting up FSL environment
Running the command

Supports .nii & .nii.gz, Linux, MacOS & Windows (WSL)

xASL_fsl_SetFSLdir.m

Format:

[FSLdir[, x, RootWSLdir]] = xASL_adm_SetFSLdir(x, bUseLatestVersion)

Description:

This function finds the FSLdir & puts it out, also in x.FSLdir to allow repeating this function without having to repeat searching. If the FSLdir & RootFSLDir are already defined in x.FSLdir & x.RootFSLDir, this function is skipped. Supports Linux, MacOS & Windows (WSL), & several different default installation folders for different Linux distributions

xASL_fsl_TopUp.m

Format:

xASL_fsl_TopUp(InDir[, ScanType], x)

Description:

This function runs FSL TopUp. It assumes that there are 2 TopUp images, i.e. 1 blip up & 1 blip down.

Admin: manage ScanType, NIfTI paths, create TopUp parameter file for image to apply TopUp to & for the TopUp NIfTIs, delete files from previous run, define the image with the same acquisition parameters as TopUp (does the image we apply TopUp to, have the Blip up or down?)
Register images to image that we apply TopUp to (registration between blip up/down images is performed by TopUp)
Run TopUp estimate (i.e. estimate the geometric distortion field from B0 NIfTI & parameters file), this takes quite long. Also has a x.Quality=0 option that is very fast but inaccurate, to try out this pipeline part. Before TopUp, NaNs (e.g. from resampling) are removed from the images TopUp is run with default settings
Apply TopUp

Imaging

xASL_im_BilateralFilter.m

Format:

[ovol] = xASL_im_BilateralFilter(volIM, mask, VoxelSize, x)

Description:

This function runs a spatial lowpass temporally highpass filter, and removes outliers within this signal, and adapts the time-series accordingly.

xASL_im_CenterOfMass.m

Format:

xASL_im_CenterOfMass(PathNIfTI, OtherList, AllowedDistance)

Description:

This function estimates the center of mass of the image matrix, and if this is too far off the current orientation matrix center, the center will be reset. This fixes any incorrect orientation outputted by the scanner. The realignment is only applied when any of the X/Y/Z dimensions have a higher offset than AllowedDistance.

xASL_im_CleanupWMHnoise.m

Format:

xASL_im_CleanupWMHnoise(InputPath, OutputPath, MinLesionVolume, pThresh)

Description:

Threshold white matter lesions, acknowledging the fact that they may be confluent with subresolution connection through a dilation. This part is executed conservatively, as FLAIR hyperintensities inside the GM can be erroneously segmented as WMH, and should not be lesion-filled (otherwise these cannot be fixed later in the Structural module).

Note that LST lesion filling expects a probability map, doesnt work nicely with binary mask

xASL_im_ClipExtremes.m

Format:

[NewIM] = xASL_im_ClipExtremes(InputIm[, ThreshHigh, ThreshLow, bVerbose, bNormalize])

Description:

This function clips an image to a given percentile. The percentile is found using non-zeros sorted intensities, so both isfinite & non-zeros. This function performs the following steps:

Constrain clippable intensities
Clip high intensities
Clip low intensities
Normalize to 4096 (12 bit, 12^2)
Save as NIfTI if the input was a NIfTI

xASL_im_Column2IM.m

Format:

[ImageOut] = xASL_im_Column2IM(ColumnIn, BrainMask)

Description:

This function "decompresses" an image matrix (or multiple matrices) from a single-dimensional column, by reconstructing the image matrix from the voxel positions within the BrainMask. NB: Important to use the same BrainMask as used for converting the image matrix to the column! See also: xASL_im_IM2Column.m

The mask mostly used for xASL_im_IM2Column is x.WBmask, which completely engulfes pGM, pWM & pCSF.

xASL_im_CompareNIfTIResolutionXYZ.m

Format:

[IsEqualResolution] = xASL_im_CompareNIfTIResolutionXYZ(PathNIfTI1, PathNIfTI2)

Description:

This function checks whether the X, Y and Z resolution of a NIfTI with any number of dimensions is equal. It rounds for 2 floating points, for both NIfTIs, to ensure that the same precision is compared.

xASL_im_ComputeDice.m

Format:

[DiceCoeff] = xASL_im_ComputeDice(imA, imB)

Description:

This function calculates the Dice coefficient of image overlap.

xASL_im_CreateASLDeformationField.m

Format:

xASL_im_CreateASLDeformationField(x, bOverwrite, EstimatedResolution)

Description:

This function smooths a transformation flow field to a lower resolution. Usually, we use a high resolution anatomical image (e.g. 3D T1w) to obtain the flowfields from native space to standard space, and apply these to the lower resolution ASL images. Because of the resolution differences, the flowfields need to be downsampled/smoothed, to avoid deformation effects that are crispier than the functional image that is investigated. This function performs the following steps:

Obtain resolutions
Fill NaNs at edges y_T1.nii flowfield to prevent interpolation artifact
Smooth flowfield
Fill NaNs at edges y_ASL.nii

Note that if the resolution of ASL is not significantly (i.e. >0.5 mm in any dimension) lower than T1w, the y_T1.nii is copied to y_ASL.nii

xASL_im_CreatePseudoCBF.m

Format:

xASL_im_CreatePseudoCBF(x, spatialCoV[, bPVC])

Description:

This function creates a pseudo-CBF image from mean CBF template, arterial transit time (ATT) bias field & vascular artifacts, weighted through spatial CoV The first part of this code puts templates in the native space and creates a pseudoCBF image from a downsampled pGM & pWM tissue (PseudoTissue). The latter is used for registration but also as reference for the template registration, to speed this up. The second part of this code computes a pseudoCBF image based on the pseudoTissue & the CBF templates of CBF, ATT biasfield and vascular peaks, based on spatial CoV.

This submodule performs the following steps:

Create the pseudoTissue CBF reference image, if it doesnt exist already
Create the native space copies of ASL templates, if they dont exist already
Spatial CoV input argument check
Load native space copies of templates
Create pseudoTissue from segmentations, mix this with the mean CBF template depending on spatial CoV
Create pseudoCBF reference image used for CBF-based registration
Scale mean_PWI_Clipped source image to the same range as PseudoCBF

xASL_im_CreateSliceGradient.m

Format:

xASL_im_CreateSliceGradient(x)

Description:

Create slice gradient in same space as input file
Reslice slice gradient to MNI (using existing ASL matrix changes from e.g. registration to MNI, motion correction, registration to GM)
Creating average slice gradient

xASL_im_DecomposeAffineTransformation.m

Format:

[M, P] = xASL_im_DecomposeAffineTransformation(Mtransformation)

Description:

This function splits a transformation matrix into individual components, which can be useful to guide the SPM reslicing. The components are the same as in spm_(i)matrix.m, except for the shearing: these are included in the rotations, and the 90 degree rotations, these are separated.

Reason for the separation of the 90 degree rotations, is that these indicate if orientations (transversal, coronal & sagittal) have been switched in the NIfTI.

This can be useful to correct for any erroneous 90degree rotations from registration, or to put two images in the same orientation order or voxelsize without applying their subtle realignment (e.g. for manipulating registration references)

THEORY 90 degree rotations: Any rotation will always swap the other dims (X rotation swaps Y/Z, Y rotation swaps X/Z etc.) because they are perpendicular (haaks)

Dims X Y Z care for LR, AP and IS translation. - X-rotation will rotate the transverse slice (LR <-> AP) swapping Y (coronal) & Z (saggital) - Y-rotation will rotate the coronal slice (IS <-> LR) slice, swapping X (transversal) and Z (sagittal) - Z-rotation will rotate the sagittal slice (AP <-> IS) swapping X (transversal) and Y (sagittal)

E.g., MPRAGE is acquired in sagittal slices, and ASL/fMRI/BOLD in transversal slices. This is an Y rotation (you look into the coronal plane, rotate this, which will swap the sagittal slices into transversal)

This function performs the following steps:

Start with an output P and M struct
Obtain translations
Obtain zoom
Obtain 90degree rotations
Obtain subtle rotations & shearing
Check the rounding errors of the decomposition

xASL_im_DetermineFlip.m

Format:

[QCstruct] = xASL_im_DetermineFlip(x,iS,PathOrientationResults,QCstruct)

Description:

Check determinants, should be the same before & after registration, otherwise a left-right flip is applied This is not visible, but detrimental for image analysis/stats.

xASL_im_DilateErodeFull.m

Format:

imOut = xASL_im_DilateErodeFull(imIn, type, kernel)

Description:

Runs dilation or erosion on a binary imIn in full three dimensions. It uses its own dilate_erode function and crops the image so that it contains only the mask. The size of all three dimensions of the kernel needs to be an odd number.

xASL_im_DilateErodeSeparable.m

Format:

imOut = xASL_im_DilateErodeSeparable(imIn, type, kernel_x, kernel_y, kernel_z)

Description:

Runs dilation or erosion on a binary imIn separably in three dimensions. Dilation/erosion in each dimension is done by using the specified kernels. It uses its own dilate_erode function and crops the image so that it contains only the mask. Works only with odd sized kernels

xASL_im_DilateErodeSphere.m

Format:

el = xASL_im_DilateErodeSphere(R)

Description:

Creates a 3D structuring element (binary) sphere with the given diameter (R) and size 2*R+1

xASL_im_DummyOrientationNIfTI.m

Format:

xASL_im_DummyOrientationNIfTI(PathSrc, PathRef, PathDummyOut[, bApplyRotationMinor, bApplyRotation90, bApplyZoom, bApplyTranslation])

Description:

This function creates a dummy image as reference for xASL_spm_reslice, allowing to only apply specific parts of the transformation between the two images. E.g. only the rotation, or only the zooming. This can be useful to correct for any erroneous rotations from registration, or to put two images in the same space without applying their realignment. This function performs the following steps:

Load orientations & calculate transformation
Calculate the desired transformation
Calculate new orientation matrix
Calculate the new image size
Save the dummy NIfTI

xASL_im_EstimateResolution.m

Format:

[resFWHM, resSigma, resErr, imSmo, imMask] = xASL_im_EstimateResolution(imCBF, imGM, imWM[, imMaskOrig, PSFtype, maxIter])

Description:

Creates a high-resolution pseudo-CBF image based on segmented GM and WM maps and iteratively adjusts its resolution by smoothing until reaching a perfect fit with the CBF image thus obtaining the resolution difference between the GM and CBF image and uses this to calculate the estimated effective resolution of hte CBF. Note that all the calculations are done using voxels as measures and not mm, so the output resolution is also in voxels and has to be transfered to mm by using the knowledge about the voxel size. It is assumed that for imGM and imWM, the voxel size equals the resolution, and the imCBF is upsampled to the smaller voxels of imGM.

xASL_im_Flip.m

Format:

[MatrixOut] = xASL_im_Flip(MatrixIn, varargin)

Description:

Backwards compatibility for flipping left-right in standard space (NB: this can be different than in native space!).

xASL_im_HausdorffDist.m

Format:

xASL_im_HausdorffDist(imIn1,imIn2)

Description:

Calculate Hausdorff and modified Hausdorff distance between two ROIs in volumes imIn1, imIn2. Input images are binarized as 0 and non-0

xASL_im_IM2Column.m

Format:

[ColumnOut] = xASL_im_IM2Column(ImageIn, BrainMask[, ApplyShiftDim])

Description:

This function "compresses" an image matrix (or multiple matrices) for optimization of memory and CPU resources. The output column only includes voxels that lie within the BrainMask. This excludes extracranial zero-information voxels from computations and memory use. NB: Important to use the same BrainMask for converting the column back to an image matrix! See also: xASL_im_Column2IM.m

The mask mostly used for xASL_im_IM2Column is x.WBmask, which completely engulfes pGM, pWM & pCSF

xASL_im_JointHist.m

Format:

imHist = xASL_im_JointHist(imA,imB[,imMask,minA,maxA,minB,maxB,nBins])

Description:

It calculates a joint histogram of two images of any dimensions over a mask of the same size. The boundaries and number of bins can either be given or min and max values are used. Values outside of the bins are counted to the first/last bin.

xASL_im_Lesion2CAT.m

Format:

LesionPathOut = xASL_im_Lesion2CAT(PathIn)

Description:

For all lesion masks in the anatomical directory, load them, merge them and save them for the CAT segmentation. If there are no lesions found, the images are untouched.

xASL_im_Lesion2Mask.m

Format:

LesionIM = xASL_im_Lesion2Mask(LesionPath, x)

Description:

This function takes a mask and adds several ROIs, to be used as custom "atlas", e.g. when computing region-average CBF values. The mask % can be an ROI or lesion, if we assume it is a lesion, the following masks are created:

Intralesional
Perilesional (15 mm rim around the lesion)
Hemisphere (ipsilateral to lesion)
Contralateral version of 1
Contralateral version of 2
Contralateral version of 3

All these masks are masked by a brainmask (pGM+pWM)>0.5

This function performs the following steps:

If lesion is empty, skip this & delete the file
BrainMasking
Create hemispheres
Save mutually exclusive masks
Create tsv-sidecar containing the names of the ROIs
Visual QC

xASL_im_M0ErodeSmoothExtrapolate.m

Format:

[ImOut] = xASL_im_M0ErodeSmoothExtrapolate(ImIn, x)

Description:

This function erodes, smooths & extrapolates M0 in standard space. It assumes that the M0 image is in standard space & that the GM & WM probability maps are aligned. Here, we mask the M0, to remove high CSF signal and low extracranial signal, enabling us to smooth the image without inserting wrong signal. See also the ExploreASL manuscript for a more extensive explanation. This function performs the following steps:

Mask: Load segmentations, create structural mask
Mask: Create intensity-based mask to remove extracranial signal
Mask: Erode the combined masks
Mask: Determine any odd borders
Smoothing
Extrapolating only
Scale back to the GM M0
Print visual QC figure

A visual QC figure is created, showing the M0 image processing steps for a single transversal slice (slice 53 in 1.5 mm MNI standard space) OutputFile = fullfile(x.D.M0regASLdir,['M0_im_proc_' x.P.SubjectID '.jpg']); The original M0 image (a) is masked with a (pGM+pWM)>50% mask (b) eroded with a two-voxel sphere to limit the influence of the ventricular and extracranial signal (c) and thresholded to exclude significantly high (i.e. median + 3*mean absolute deviation (MAD)) border region values (d) This masked M0 image is smoothed with a 16x16x16 mm full- width-half-maximum Gaussian filter (Mutsaerts et al., 2018) (e) after which the signal at the border is smoothly extrapolated until the full image is filled (f). Whereas the masking avoids mixing with cerebrospinal fluid or extracranial signal, the extrapolation avoids M0 division artifacts

xASL_im_MaskNegativeVascularSignal.m

Format:

[NegativeMask, TreatedPWI] = xASL_quant_DetectNegativeVascularSignal(x)

Description:

This function segments clusters with significant negative ASL signal. This can be tricky as there is also the negative tail of Gaussian noise from the ASL subtraction. The image feature we use here, is that negative vascular signal will be a relatively large region with significant median negative value, whereas noise will be regions with relatively small negative signal. Negative signal from wrong background suppression timing (e.g. in the first slice with 2D EPI) can be masked out with this as well. The procedure works as follows:

Obtain mask of negative voxels within pGM>0.5 mask
Obtain distribution of subzero clusters
Define the negative threshold
Create mask by thresholding whole image

Note that the definition of the threshold is obtained within the GM only, but that this threshold is applied to the full image.

Note that instead of the PWI path input, a CBF image should work equally well, as we don't expect a smooth M0 biasfield to change the distribution of negative clusters

xASL_im_MaskPeakVascularSignal.m

Format:

[MaskIM, CBF] = xASL_quant_VascularContrast(PathPWI, Path_M0, CompressionRate, ClipThresholdValue, bClip)

Description:

This function searches for an acceptable high threshold as definition of high intra-vascular ASL signal. It also allows to compress the values here (when bClip==true). Compression retains some variability, but limits their outlying influence on statistics. The procedure works as follows:

Segment GM on ASL image at 80th percentile of CBF image distribution
For PWI & CBF images, select voxels higher than median + ClipThresholdValue MAD Vascular artifacts will have a high intensity in both images, whereas errors by division by M0 will only have a high intensity on the M0 image, and high values due to a biasfield will only be noticeable on the PWI image
Combine the two created masks
Obtain average clipping value from selected voxels from the combined masks
Apply compression if requested. If not, output image will have NaNs for intra-vascular voxels.

Note that the definition of the threshold is obtained within the GM only, but that this threshold is applied to the full image to also remove extracranial extreme values.

Note that the performance may change when using this script with or without M0, as this will change the distribution that determines where the threshold for extremes lies.

xASL_im_Modulation.m

Format:

xASL_im_Modulation(x)

Description:

Combines the transformations to create Jacobians, & multiplies the standard space segmentations with these to create volumetric images for volumetric analyses.

xASL_im_NormalizeLabelingTerritories.m

Format:

image_out = xASL_im_NormalizeLabelingTerritories( imageIN, GMmask, x)

Description:

Normalizes per perfusion territory mask should be GM mask.

xASL_im_PCA.m

Format:

[pc, score, eigenvalues, tsquare, loadings, Xmean] = xASL_im_PCA(dataIn)

Description:

Perform a Principal Component Analysis.

xASL_im_PVCbspline.m

Format:

[imPVEC,imCBFrec,imResidual,FWHM] = xASL_im_PVCbspline(imCBF,imPV[,bsplineNum])

Description:

PVC of ASL data using prior GM-,WM-partial volume maps. Follows the principles of the PVEc algorithm by I. Asllani (MRM, 2008). The PV-corrected CBF_GM and CBF_WM maps are approximated using an uniformly sampled cubic B-splines.

REFERENCES: -Asllani I, Borogovac A, Brown TR. Regression algorithm correcting for partial volume effects in arterial spin labeling MRI. Magnetic Resonance in Medicine. 2008 Dec 1;60(6):1362-71. -Petr J, Mutsaerts HJ, De Vita E, Steketee RM, Smits M, Nederveen AJ, Hofheinz F, van den Hoff J, Asllani I. Effects of systematic partial volume errors on the estimation of gray matter cerebral blood flow with arterial spin labeling MRI. MAGMA 2018. DOI:10.1007/s10334-018-0691-y

xASL_im_PVCkernel.m

Format:

[imPVC,imCBFrec,imResidual] = xASL_im_PVCkernel(imCBF, imPV [,kernel,mode])

Description:

Partial volume correction (PVC) of ASL data using prior GM-,WM-partial volume maps. Follows the principles of the PVC algorithm by I. Asllani (MRM, 2008).

xASL_im_PreSmooth.m

Format:

pathOut = xASL_im_PreSmooth(pathRef,pathSrc[,pathSmo,resRef,resSrc,srcAffinePath, bInvAffine])

Description:

It assumes that the FWHM is equal to voxel size, unless the real resolution is given. Then takes into account the voxel sizes and orientation difference between the volumes, but performs the smoothing according to the given real resolution (it is possible to supply the resolution for just one image) - this should be helpful primarily when the It creates a Gaussian covariance matrix for the reference, transforms it according to the difference between the two images a produces the Gaussian covariance matrix of the pre-smoothing in the source space. Then it performs the smoothing.

The following steps are performed:

Obtain the voxel size
Skip this function if reference resolution is equal to, or lower than source resolution
Deal with affine transformation
Obtain the transformation matrix from the Reference to the Source space
Apply the smoothing filter on the source image(s)
Save the smoothed image

xASL_im_ProcessM0Conventional.m

Format:

[Corr_M0] = xASL_im_ProcessM0Conventional(ImIn, x)

Description:

This function uses the conventional M0 masking, and only a little smoothing, following what Philips uses for its 3D {{GRASE}}. Advantages of the newer M0 processing in ExploreASL are the lack of use of M0 threshold-based masking, the removal of high CSF values and higher SNR for ASL division.

xASL_im_ProjectLabelsOverData.m

Format:

OutputIM = xASL_im_ProjectLabelsOverData(DataIM,LabelIM,x,ScaleFactorData,ScaleFactorLabel)

Description:

This script projects labels over an image, but works only in 2D. Make sure to make a 2D image from a 3D or 4D image using xASL_vis_TransformData2View.m can be used in combination with xASL_vis_Imwrite.m

xASL_im_ReplaceLabel.m

Format:

xASL_im_ReplaceLabel(pathNifti, LabelNumbersOld, LabelNumbersNew, pathNewNifti)

Description:

This function replaces label values/numbers inside a NIfTI image, by the following steps:

Load NIfTI
Replace numbers
Save NIfTI

xASL_im_ResampleLinearFair.m

Format:

[output_res]=xASL_im_ResampleLinearFair(im_input,newsize)

Description:

Downsample (or upsample, works similarly) old_res image to low_res image, trilinear. We recommend using "xASL_spm_Resample" instead, because of better performance.

NB: new_res should fit exactly integer fold in old_res

NB: all dimensions of new_res should have equal size

xASL_im_RestoreOrientation.m

Format:

xASL_im_RestoreOrientation(PathNIfTI)

Description:

This function reverts the NIfTI header orientation matrix to the original orientation from the scanner/dcm2nii conversion.

xASL_im_SkullStrip.m

Format:

xASL_im_SkullStrip(InPath, PathMNIMask, x, OutPath)

Description:

Creates skull-stripped T1w image based on MNI -> native space registration from segmentation.

xASL_im_Smooth3D.m

Format:

[imSmo, imGaussX, imGaussY, imGaussZ] = xASL_im_Smooth3D(imIn, sigma[, PSFtype])

Description:

It smooths the 3D image with a 3D kernels that has defined the shape and SD of the smoothing separably in three dimension.

xASL_im_SplitImageLabels.m

Format:

xASL_im_SplitImageLabels(ImagePaths, LabelTable[, OutputFolder, bOverwrite, ResampleDir, SubRegExp])

Description:

This function allows extracting of labels from a NIfTI file containing multiple labels, into single NIfTI files each containing a single label. Not all existing labels need to be extracted.

The following steps are performed:

Load TSV file
Process images

xASL_im_Upsample.m

Format:

xASL_im_Upsample(PathOrig, PathDest, NewVoxelSize, LeaveEmpty, PaddingDim, Kernel)

Description:

Upsamples an ASL image, without changing the orientation matrix, which can be used e.g. for PVEc in higher resolution but same space.

xASL_im_ZeroEdges.m

Format:

[IM] = xASL_im_ZeroEdges(IM[, EdgeThicknessPerc])

Description:

Resampling can sometimes give some strange errors near image edges. These should be NaNs, but sometimes can be zeros or ones, or even weird numbers. For resampling, NaNs should be set to 0 (this is done in another function) as they can influence the resampling (depending on the transformation matrix). To be sure that the edges are nicely fixed, this function sets a border at the image matrix edges to zero.

xASL_im_dilateROI.m

Format:

xASL_im_dilateROI(PathIn, [PathOut, minVolume])

Description:

The function loads a binary image from PathIn and if smaller than the defined volume (40 mL by default) it dilates it with a 3x3 sphere element until a minimal volume is reached. When it is small enough, it is saved to PathOut. 40 mm^3 is equal to 3 voxels in all directions in DARTEL space, or around the highest obtainable ASL effective resolution (3x3x4 mm).

xASL_im_rotate.m

Format:

rotated = xASL_im_rotate(im, angle)

Description:

Simple rotation of the first two dimension of a ND image by 0, 90, 180, 270 degrees.

Initialization

xASL_init_DefaultEffectiveResolution.m

Format:

[EffectiveResolution] = xASL_init_DefaultEffectiveResolution(PathASL, x)

Description:

This ExploreASL module provides an educated guess on the effective spatial resolution of ASL. This may depend on the combination of acquisition PSF, reconstruction filter, head motion. Note that the derived/processed images may have a lower effective resolution because of smoothing effects from interpolation. Note that this remains an educated-guess, the actual FWHM may still differ, especially for 3D GRASE sequences, where e.g. the choice of number of segments can affect the smoothness.

This function conducts the following steps:

Educated-guess FWHM
Attempt accounting for in-plane interpolation in reconstruction
Calculate and report effective spatial resolution

xASL_init_DefineStudyData.m

Format:

[x] = xASL_init_DefineStudyData(x)

Description:

This initialization wrapper initializes the parameters for this pipeline run, i.e. subjects, sessions (runs), timepoints (visits), exclusions, sites, cohorts etc.

Note that ASL sessions are defined here as what BIDS calls "runs".

The "longitudinal_Registration functions here manage different TimePoints, which is what BIDS calls "visits". With different structural scans, from the same participant. This is managed by subject name suffixes _1 _2 _n, and can be used for comparing visits in the population module, or running SPM's longitudinal within-subject registration.

Parallelization is allowed here by calling ExploreASL different times, where it divides the subjects/images for processing across the nWorkers, using iWorker as the reference for the part that the current ExploreASL call will process. This requires having a Matlab license that can be started multiple times on a server, or alternatively running the ExploreASL compilation, and doesn't require the Matlab parallel toolbox.

This function exists from the following parts:

Manage included & excluded subjects
Create dummy defaults (exclusion list, ASL sessions)
Create list of total baseline & follow-up subjects, before exclusions
Create TimePoint data-lists
Manage exclusions
Add sessions as statistical variable, if they exist
Parallelization: If running parallel, select cases for this worker
Add Longitudinal TimePoints (different T1 volumes) as covariate/set, after excluding
Load & add statistical variables
Make x.S.SetsOptions horizontal if vertical by transposing
Create single site dummy, if there were no sites specified
Check for time points sets
Create list of baseline & follow-up subjects (i.e. after exclusion)
Check what excluded from which TimePoints

xASL_init_FileSystem.m

Format:

[x] = xASL_init_FileSystem(x)

Description:

This function initializes the file system used throughout ExploreASL, for processing a single dataset/scan. It is repeated for each scan, and runs the following parts:

Create folders
Subject/session definitions
Add prefixes & suffixes
Add Subject-specific prefixes
Add sidecars
Add atlas paths

xASL_init_InitializeMutex.m

Format:

[x] = xASL_init_InitializeMutex(x, ModuleName)

Description:

This function initializes the mutex/lock system of ExploreASL for a module. Mutex (for mutual exclusion) is a synchronization mechanism for enforcing limits of access to data (here a module for a single scan) to allow parallelization. It also allows stopping and continuing of ExploreASL. This function runs the following steps:

Lock folder management
Initialize mutex object

xASL_init_LoadMetadata.m

Format:

[x] = xASL_init_LoadMetadata(x)

Description:

This function loads all metadata used in the study, either statistical covariates (age, MMSE) or groups to compare between (site, sequence, cohort), or parameters to be used in quantification/image processing

These parameters should be provided in .mat files in the root analysis folder. Each .mat file should contain a single type of metadata, and the filename should equal the variable name. Metadata content should be a cell array with subjects as first column and metadata as last column. Sessions (runs) can be included as second column.

Metadata can be in any string or numerical format.

participants.tsv is now added per BIDS. It looks for metadata in participants.tsv first, before going through the mat-files

This function iterates through the following steps for each variable:

Admin (what nOptions do we call ordinal, convert subject numeric to string, remove white spaces from data)
Get unique list of data options & check for missing data
Deal with data format (correct NaNs, deal with numeric vs strings)
Distinguish continous data (e.g. age) or ordinal data (groups to compare, e.g. cohort)
Check if data is complete for all subjects
Include complete data in x.S.SETS

xASL_init_LongitudinalRegistration.m

Format:

[SubjectNlist, TimePoint, IsSubject, SubjectID_FirstVolume] = xASL_init_LongitudinalRegistration(x)

Description:

This function initializes the longitudinal registration for ExploreASL, which implements the SPM longitudinal registration.

This function recognizes and defines visits (i.e. multiple scans per subject) in the initialization of ExploreASL, based on the suffixes _1 _2 _n in the subject names (identified as foldernames).

Specifically, this function is called in the registration modules LongReg and DARTEL, the first carrying out within-subject registration and the second between-subject registration, based on the first time point only. For the first function, we specify here a list of visits/timepoints that should be registered longitudinally, for the second function we specify a list of first visits only, as the between-subject registration in ExploreASL is based on the first scan (as opposed to the average subject's scan).

This function runs the following steps:

Get TimePoint-list (list of visits)
Find subject IDs

xASL_init_VisualizationSettings.m

Format:

[x] = xASL_init_VisualizationSettings(x)

Description:

This function defines several visualization settings are used throughout ExploreASL's pipeline and tools, assuming a [121 145 121] matrix with 1.5 mm isotropic resolution in MNI space.

Input and Output

xASL_io_CreateNifti.m

Format:

xASL_io_CreateNifti(pathNewNifti, imNew, resMat, nBits, bGZip)

Description:

This function creates a new NIfTI file, using the SPM "nifti" functionality, with the parameters specified as input arguments. This function performs the following steps:

Initialize NIfTI
Choose datatype (bit resolution)
Create scale slopes
Create orientation matrix
Write the new NIfTI, image matrix & scale slopes
Zip and deal with zipping (.nii vs. .nii.gz)

xASL_io_DcmtkRead.m

Format:

header = xASL_io_DcmtkRead(filepath, bPixel)

Description:

SHORT Reads DICOM headers using DCMTK

FORMAT: header = xASL_io_DcmtkRead(filepath, bPixel)

INPUT: filepath (string) - full path to the DICOM file bPixel (bool) - read pixel data, default 0 OUTPUT: header (structure) - structure containing parsed DICOM header

Calls the MEX function that uses DCMTK library to read the DICOM header. To change which parameters are read and their names - the MEX file needs to be edited. This function also corrects formating of certain parameters.

xASL_io_ExportVTK.m

Format:

xASL_io_ExportVTK(nifti, [mask, exportPath])

Description:

Export a VTK image file based on a 3D NIFTI or a 3D/4D image matrix. 4D images will be exported as a VTK time series (export-1.vtk, export-2.vtk, etc.). This script uses vtkwrite (MIT License, Copyright 2016, Joe Yeh).

xASL_io_MakeNifti4DICOM.m

Format:

xASL_io_MakeNifti4DICOM(PathIn, x)

Description:

This function converts a NIfTI file to one that is ready to convert to DICOM for PACS visualization purposes:

For scaling/visualization:

Remove peak signal
Remove valley signal
Remove NaNs
Rescale to 12 bit integers
Save NIfTI. We also zip the NIfTI as this NIfTI won't be opened by ExploreASL
Manage scale slope/datatype
Apply original orientation
Zip NIfTI

xASL_io_PairwiseSubtraction.m

Format:

xASL_io_PairwiseSubtraction(InputFile,outputPath,do_mask,switch_sign)

Description:

Subtracts controls from labels and takes mean. Creates new perfusion-weighted delta_M file, prefaced with 's'. Converts into single precision floating point values (32 bit), removes scale slope. Only runs if ['s' input_file_ASL] doesn't exist. Remember to consider motion correction/ SPM realign (isotropically). Alternative to this function is robust fit (Camille Maumet).

xASL_io_ReadDataPar.m

Format:

[x] = xASL_io_ReadDataPar(pathDataPar)

Description:

This function reads the data-parameter file, which is a file containing settings specific to processing a certain dataset or study (abbreviated as DataPar) and creates the x-structure out of it. The file can be in .json or .m format. The input file name pathDataPar is given as a string or character array. The output is the x structure. It only loads the data, removes the x-prefixes, but keeps all the field names and units. It doesn't do any conversions to or from BIDS. The only added value to normal json-read is that it detects invalid entries (numbers in strings, and weird arrays), converts them correctly and reports this incorrect entries so that they can be manually fixed. Also, if an .m file is provided, it converts and saves it to a JSON file (doesn't overwrite) and reports that you should stop using .m files.

xASL_io_ReadTheDicom.m

Format:

[Info] = xASL_io_ReadTheDicom(bUseDCMTK, DicomPath)

Description:

This function tries to read a DICOM and throws a warning if it fails to

xASL_io_SplitASL.m

Format:

xASL_io_SplitASL(inPath[, iM0, iDummy])

Description:

This function splits ASL4D & M0 & Dummy images if they were in the same sequence. If dcm2niiX has already splitted the ASL4D NIfTI, this is reconstructed first. If no M0 exists, or only ASL splitting is desired, leave iM0 empty ([]). The dummy scans can be excluded from the ASL sequence during the splitting. Both iM0 and iDummy are the absolute positions of both in the original time series

Vendor product sequence examples: GE 3D spiral sometimes puts the M0 at the last volume of the series -> iM0 = [2]; Philips 3D GRASE puts the M0 as control-label volume pair -> iM0 = [1 2]; Siemens 3D GRASE puts the M0 as the first volume -> iM0 = 1; Some Siemens 3D GRASE puts a second Dummy control image -> iDummy = 2;

Input parameter admin
Prepare paths
First concatenate NIfTIs
Save M0 NIfTI
Determine ASL indices
Save ASL4D NIfTI
Split relevant JSON parameters/arrays
Split ASL4D_aslContext.tsv
Modify JSON fields
Copy sidecars

xASL_io_dcm2nii.m

Format:

[niifiles, ScanNameOut, usedinput, msg] = xASL_io_dcm2nii(inpath, destdir, series_name, varargin)

Description:

Convert DICOM NIfTI/BIDS format using the dcm2nii command line utility.

Initial settings
Parse parameters
Locate dcm2nii executable
Set default arguments dcm2nii
Set dcm2niiX initialization loading
Check if we are reading a DICOM folder
Check for existing targets
Create temporary subfolder for converting
Run dcm2nii and move files to final destination using specified series name
Cleanup temp
Optionally return the used input file

xASL_num2str.m

Format:

[DataOut] = xASL_num2str(DataIn[, f, bConcatenate, strDelimiter])

Description:

When the provided data is numeric, this function will convert the number to string/characters, rewriting NaN into 'n/a' (BIDS convention) but otherwise preserving the Matlab builtin functionality, also for the second argument "f". If non-numeric data is provided, it is bypassed (avoiding any issues "num2str" will have with non-numeric data). It can concatenate an array/matrix of strings, taking first the columns in the first row, and then going across the rows. See builtin num2str for more details

QC

xASL_qc_AsymmetryIndex.m

Format:

[AI_perc] = xASL_qc_AsymmetryIndex(ImageIn)

Description:

Extract voxel-wise asymmetry index for QC purposes.

xASL_qc_CAT12_IQR.m

Format:

[QA_Output] = xASL_qc_CAT12_IQR(InputImage, InputC1, InputC2, InputC3, bFLAIR)

Description:

Prepare and run CAT12s QC parameters (also for other images).

xASL_qc_CollectParameters.m

Format:

x = xASL_qc_CollectParameters(x, iSubject, ScanType, CollectQCFunction)

Description:

This function collects QC parameters for a module.

xASL_qc_CollectQC_ASL.m

Format:

[x] = xASL_qc_CollectQC_ASL(x, iSubject)

Description:

This functions collects QC parameters for the ASL module

These are stored in x.Output.ASL:

ID - SubjectName ASL_LR_flip_YesNo - Checks whether any image processing changed the left-right orientation by checking whether the determinant differs between nii.mat & nii.mat0 SPM realign (too much motion is suspicious) MotionMean_mm - mean motion MotionExcl_Perc - percentage of excluded outliers MotionMax_mm - max motion MotionSD_mm - SD motion

ASL quantification (strange average CBF, or strange GM-WM contrast) ASL acquisition parameters (should be fairly consistent over subjects/scans): TE - echo time TR - repetition time RescaleSlope - Philips Scaleslope - Philips Matrix X Y Z - matrix size Matrix Z - number of slices VoxelSize X Y - in plane resolution VoxelSize Z - slice thickness RigidBody2Anat_mm - Net Displacement Vector (RMS) from ASL to T1w image (mm) from registration

xASL_qc_CollectQC_Structural.m

Format:

[x] = xASL_qc_CollectQC_Structural(x, iSubject)

Description:

This functions collects QC parameters for the structural module These are stored in x.Output.Structural: ID - SubjectName T1w_LR_flip_YesNo - Checks whether any image processing changed the left-right orientation by checking whether the determinant differs between nii.mat & nii.mat0 LST output: WMH_vol_mL - WMH volume WMH_n - WMH number of lesions CAT12 output: T1w_IQR_Perc - CAT12 IQR quality parameter for T1w volumetric: GM_vol_mL, WM_vol_mL, CSF_vol_mL, ICV_vol_mL, GM_ICV_Ratio

xASL_qc_CollectQC_func.m

Format:

[x] = xASL_qc_CollectQC_func(x, iSubject)

Description:

This functions collects QC parameters for the func module

These are stored in x.Output.func:

ID - SubjectName func_LR_flip_YesNo - Checks whether any image processing changed the left-right orientation by checking whether the determinant differs between nii.mat & nii.mat0 SPM realign (too much motion is suspicious) MotionMean_mm - mean motion MotionExcl_Perc - percentage of excluded outliers MotionMax_mm - max motion MotionSD_mm - SD motion func quantification (strange average CBF, or strange GM-WM contrast) CBF_GM_Median_mL100gmin - median GM CBF CBF_WM_Median_mL100gmin - median WM CBF SpatialCoV_GM_Perc - GM spatial CoV SpatialCoV_WM_Perc - WM spatial CoV CBF_GM_WM_Ratio - GM-WM CBF ratio

func acquisition parameters (should be fairly consistent over subjects/scans): TE - echo time TR - repetition time RescaleSlope - Philips Scaleslope - Philips Matrix X Y Z - matrix size Matrix Z - number of slices VoxelSize X Y - in plane resolution VoxelSize Z - slice thickness RigidBody2Anat_mm - Net Displacement Vector (RMS) from func to T1w image (mm) from registration

xASL_qc_CollectSoftwareVersions.m

Format:

[x] = xASL_qc_CollectSoftwareVersions(x)

Description:

This functions collects software versions for Matlab, SPM, CAT, LST & ExploreASL If FSL is installed, it will obtain its version as well. These are stored in x.Output.Software.

xASL_qc_CompareTemplate.m

Format:

[QC] = xASL_qc_CompareTemplate(x, ModPrefix, iSubjectSession)

Description:

This function computes several advanced template-based QC parameters: RMSE_Perc - Root Mean Square Error between image and template (%) nRMSE_Perc - Same but then normalized AI_Perc - Asymmetry Index between image and template (%) Mean_SSIM_Perc - mean structural similarity index -> xASL_stat_MeanSSIM.m PeakSNR_Ratio - peak signal-to-noise ratio -> xASL_stat_PSNR.m

xASL_qc_ComputeFoVCoverage.m

Format:

[CoveragePerc] = xASL_qc_ComputeFoVCoverage(InputPath, x)

Description:

This function computes the intersection/overlap between brainmask on field-of-view (FoV) of low resolution image (native space) & the same brainmask with expanded FoV. It uses the pGM+pWM+pCSF as brainmask This assumes that the structural reference image has full brain coverage, and was properly segmented into GM, WM and CSF Also, we assume that the InputPath contains a single 3D volume

xASL_qc_ComputeNiftiOrientation.m

Format:

[structOut] = xASL_qc_ComputeNiftiOrientation(PathNIfTI[, structIn])

Description:

It loads the input Nifti, finds its dimension, voxel size and a net vector distance from its original position before registration. Adds all these information into an output structure structOut while copying all from structIn and keeping it intact.

xASL_qc_CreatePDF.m

Format:

xASL_qc_CreatePDF(x[, DoSubject])

Description:

This function iterates over all values in x.Output and all images in x.Output_im, and prints them in a PDF file. x.Output & x.Output_im should contain the QC/result output of all ExploreASL pipeline steps.

Further code explanation: Below, using the Matlab & SPM Figure tools we create an image, which is then printed to a PDF file

fg = the main Figure handle
ax = "axes" handles, these are objects containing either 1) text or 2) images, with fg as "parent" (1) & (2) images have ax as "parent" Positions are calculated in such a way that 4 categories can be printed, which will be the first 4 fields found in x.Output then allowing 8 single slice images, and 15 text lines (name & value columns)

xASL_qc_FA_Outliers.m

Format:

[FA_Outliers_mL] = xASL_qc_FA_Outliers(InputFA)

Description:

Extract the number of FA outliers, i.e. values of FA above 1 or below 0, from a FA image.

xASL_qc_ObtainQCCategoriesFromJPG.m

Format:

xASL_qc_ObtainQCCategoriesFromJPG(x)

Description:

This function obtains QC categories as covariant/set, based on the JPGs in //Population/ASLCheck. These are initially sorted by spatial CoV, and should be visually checked & put in the correct folder.

xASL_qc_PCPStructural.m

Format:

[anatQA] = xASL_qc_PCPStructural(PathT1, Pathc1T1, Pathc2T1, x, PopPathT1)

Description:

This function computes several anatomical QC parameters as proposed in SPM Univariate Plus:

WM_ref_vol_mL - volume of the WM reference region (mL)
WMref_vol_Perc - same but as percentage of total WM volume
SNR_GM - GM signal-to-Noise Ratio (SNR), ie the mean intensity within GM divided by SD of WM reference region. Higher = better.
CNR_GM_WM - GM-WM Contrast-to-Noise Ratio (CNR), i.e. the mean of GM - mean of WM divided by the SD of the WM reference region. Higher = better.
FBER_WMref_Ratio - Foreground to Background Energy Ratio (FBER), i.e. the variance of voxels within the brain (in pGM+pWM mask) divided by the variance of voxels in the WM reference region. Higher = better.
EFC_bits - Shannon Entropy Focus Criterion (EFC), i.e. the entropy of voxel intensities proportional to the maximum possibly entropy for a similarly sized image. Indicates ghosting and head motion-induced blurring. Lower = better.
Mean_AI_Perc - mean relative voxel-wise absolute Asymmetry Index (AI) within the brain (pGM+pWM mask) (%)
SD - same but SD (%)

REFERENCES: Preprocessed Connectome Project Quality Assurance Protocol (QAP): http://preprocessed-connectomes-project.org/quality-assessment-protocol/ http://ieeexplore.ieee.org/document/650886/

xASL_qc_PrintOrientation.m

Format:

xASL_qc_PrintOrientation(DIR, reg_exp_INPUT,OUTPUT_DIR,Name);

Description:

Check orientation of niftis, useful to detect accidental left-right flips (all other flips will be visible). translations, rotations or shears are not to be worried about, only negative zooms. This can be detected by negative determinants. So orientation parameters and determinants should be similar across all scans from single scanner/coil, and registration should not give negative determinant.

xASL_qc_TanimotoCoeff.m

Format:

TC = xASL_qc_TanimotoCoeff(Image1, Image2[, imMask, type])

Description:

Compares images Image1 and Image2 within the mask imMask. TYPE specifies the input data type.

RATIONALE: Note that the Tanimoto Coefficient is a measure of image overlap/intersection, similar to the Dice coefficient. With the option type 3, this is a fuzzy coefficient, which doesn't require to convert the two images to a binary mask. The TC can be interpreted as a stringent Kappa, ranging from 0 (completely dissimilar) to 100% (identical images). Assuming that perfect registration should not lead to identical images but still retain physiological differences, TC>70% can be regarded as excellent image agreement. The TC will be overestimated when smoothing, but this may lead to more stable artifact detection.

xASL_qc_WADQCDC.m

Format:

xASL_qc_WADQCDC(x, iSubject[, ScanType])

Description:

This QC function runs WAD-QC specific Python script to zip QC information & incorporate this into a DICOM field for analysis on the WAD-QC server, by the following:

Define QCDC script: this is the Python script written by Gaspare, edited by Joost Kuijer & copied to the EPAD CustomScripts folder of ExploreASL
Python installation location is checked, with several known locations, for several servers. If we cannot find it, the QCDC is not ran
Previous QCDC results are cleaned. QCDC stores all its results in a separate folder (Something like 2 layers up from the current folder, here referred to as QCDCDir = [x.D.ROOT 'qcdc_output']) from these result files, only the filled DICOM file is interesting, all the rest are copies of the QC results that we embedded into the DICOM
Run QCDC (if Python installation detected) The following files need to be set as executable: ('QCDC', 'src', 'qc_data_collector.py') ('QCDC', 'src', 'bash', 'create_dcm_only_wadqc.sh') ('QCDC', 'src', 'bash', 'sendwadqc.sh')
Clean up new QCDC results (as above) & move the filled DICOM to ['qcdc_' DummyFile] within the current ScanType folder
Sending the DICOM to the WAD-QC server using storescu

xASL_qc_WADQC_GenerateDescriptor.m

Format:

xASL_qc_WADQC_GenerateDescriptor(x, iSubject)

Description:

This QC function generates a JSON descriptor for Gaspare' QCDC script, by the following steps:

a) include information about where to find the dummy DICOM (i.e. placeholder DICOM)
b) For ExploreASL' QC fields (as passed through in x.Output), here we note all these QC fields for each ScanType, as the x.Output should have been collected equally in the QC file 'QC_collection_SubjectName.json' by function xASL_qc_CollectParameters
c) Subfunction xASL_qc_WADQC_images - Includes visual standard space QC images, by searching them on prescribed paths within the Population folder (where currently all derivatives reside)
d) Insert the PDF report; this PDF report is subject-specific, not scan-specific. For completeness it is added to each QCDC descriptor
e) Add WAD-QC server details (i.e. IP address etc)
f) Save the Descriptor JSON file.

xASL_qc_temporalSNR.m

Format:

tSNR = xASL_qc_temporalSNR(pathIm4D,pathImTissueProb)

Description:

This function computes several temporal SNR QC parameters as proposed in SPM Univariate Plus: tSNR.tSNR_GM_Ratio : mean GM signal / std GM over time tSNR.tSNR.tSNR_WM_Ratio : mean WM signal / std WM over time tSNR.tSNR.tSNR_CSF_Ratio: mean CSF signal / std CSF over time tSNR.tSNR_WMref_Ratio : mean signal/std over time in eroded deep WM tSNR.tSNR_GMWM_Ratio : mean (GM+WM) signal / sqrt(std(GM+WM)^2+std(WMref)^2) tSNR.tSNR_GMWM_WMref_Ratio: mean (GM+WM) signal / std WMref over time tSNR.tSNR_Physio2Thermal_Ratio: sqrt((tSNR(GM+WM)/tSNR_GMWM_WMref_Ratio))^2-1) tSNR.tSNR_Slope_Corr:

Differences to the SPM U+ suggestion:

eroded WM is used for estimating background noise
Brainmask is determined in the same way as the structural anatQC,
CSF is determined from the pGM&pWM maps;

REFERENCES: 1. Thomas Liu (2016). Noise contributions to the fMRI signal: An overview NeuroImage, 343, 141-151 http://dx.doi.org/10.1016/j.neuroimage.2016.09.008 2. Cesar Caballero-Gaudes and Richard C. Reynolds (2016). Methods For Cleaning The BOLD fMRI Signal. NeuroImage, 154,128-149 3. Lawrence Wald and Jonathan R Polimeni (2016). Impacting the effect of fMRI noise through hardware and acquisition choices ??? Implications for controlling false positive rates. NeuroImage, 154,15-22 4. SPM Utility + toolbox. Cyril Pernet. https://osf.io/wn3h8/

Quantization

xASL_quant_AgeSex2Hct.m

Format:

[Hematocrit] = xASL_quant_AgeSex2Hct([age, sex])

Description:

This function estimates a participants hematocrit, based on literature-based values for age and sex. It performs the following steps:

Warning unknown age/sex
Imputing unknown age/sex
Define hematocrit per age for unknown sex
Define Hematocrit per age for males
Define Hematocrit per age for females

xASL_quant_BSupCalculation.m

Format:

signalPercentage = xASL_quant_BSupCalculation(BackgroundSuppressionPulseTime, ReadoutTime[, PresaturationTime, T1Time, SliceTime, PathGraph])

Description:

This function computes the tissue signal percentage that remains after background suppression pulses are played in the ASL acquisition. It assumes that the signal is, at first, optionally saturated by a 90 degree flip at PresaturationTime before readout. Then follows a series of BSup pulses (times before readout are given) that do a 180 degree flip. The observed tissue relaxes with time T1time and the signal attenuation is calculated for several slices acquired at times relative to the readout.

xASL_quant_Basil.m

Format:

[CBF_nocalib] = xASL_quant_Basil(PWI, x)

Description:

This script performs quantification of the PWI using the FSL Basil pipeline. Final calibration to physiological units is performed by dividing the quantified PWI by the M0 image/value. This function performs the following steps: 1. Define paths 2. Delete previous BASIL output 3. Write the PWI as Nifti file for Basil to read as input 4. Create option_file that contains options which are passed to Fabber 5. Run Basil and retrieve CBF output 6. Scaling to physiological units 7. Householding

xASL_quant_FEAST.m

Format:

xASL_quant_FEAST(x)

Description:

This function quantifies ATT using the FEAST equations, using crushed and non-crushed sessions, of which the ratio is proportional to ATT. Note that the order of sessions should be 1) crushed 2) non-crushed

This function runs the following steps:

Skip this function if no FEAST data available
Admin
Load data & correct for timing differences (PLD etc)
Smooth and clip CBF maps & FEAST ratio
Compute TT maps

xASL_quant_GetControlLabelOrder.m

Format:

[ControlIM, LabelIM, OrderContLabl] = xASL_quant_GetControlLabelOrder(FramesIn, x)

Description:

This function automatically checks (and corrects if required) the control and label order of ASL timeseries based on the larger signal in control volumes. It supposes that data is acquired in pairs.

xASL_quant_Hct2BloodT1.m

Format:

BloodT1 = xASL_quant_Hct2BloodT1(Hematocrit, Y, B0, bVerbose)

Description:

This function converts hematocrit to blood T1, according to calculations defined by Patrick Hales. With courtesy and thanks! Note that we assume a venous O2 saturation of 68% (Yv=0.68)

This function performs the following steps:

Check fraction vs percentage hematocrit & Y, should be between 0 and 1
Specify defaults (Hb, Fe)
Perform calculation
Convert s to ms
Print what we did

xASL_quant_M0.m

Format:

[M0IM] = xASL_quant_M0(inputM0, x)

Description:

This function quantifies the M0, except for the difference in voxel size between the M0 and ASL source data (which is scaled in xASL_wrp_ProcessM0.m). This function runs the following steps:

Correct scale slopes, if Philips
Convert control image with background suppression to pseudo-M0
Skip M0 quantification if ~x.ApplyQuantification(4)
Set TR specifically for GE
Check for correct TR values
Quantify the M0, either for single 3D volume or slice-wise
Apply custom scalefactor if requested (x.M0_GMScaleFactor)

xASL_quant_SinglePLD.m

Format:

[ScaleImage[, CBF]] = xASL_quant_SinglePLD(PWI, M0_im, imSliceNumber, x)

Description:

This script performs a multi-step quantification, by initializing a ScaleImage that travels through this script & gets changed by the following quantification factors:

PLD scalefactor (gradient if 2D multi-slice) (if x.ApplyQuantification(3))
Label decay scale factor for single (blood T1) - or dual-compartment (blood+tissue T1) model, CASL or PASL Single-compartment model: Alsop MRM 2014 Dual-compartment model: Wang MRM 2002: Gevers JMRI 2012 (if x.ApplyQuantification(3))
Scaling to physiological units [ml/gr/ms =>ml/100gr/min =>(60,000 ms=>min)(1 gr=>100gr)] (if x.ApplyQuantification(3))
Vendor-specific scalefactor (if x.ApplyQuantification(1) -> future move to dcm2niiX stage) Finally, we:
Divide PWI/M0 (if x.ApplyQuantification(5))
Print parameters used

Note that the output always goes to the CBF image (in the future this could go to different stages, e.g. dcm2niiX or PWI stage)

Note that BASIL is also implemented, but it doesn't allow a standard space quantification yet (it would need to use imSliceNumber)

xASL_quant_SliceTiming.m

Format:

SliceTiming = xASL_quant_SliceTiming(x, inputIm)

Description:

This function takes the x.Q.SliceReadoutTime and returns the SliceTiming parameter. The function creates a vector (of the relatives timings for each slices) out of it with the correct length corresponding to the number of slices in the inputIm corresponding to the BIDS definition. It also checks the x.readout_dim, and for 3D readouts it returns 0. It loads the image from inputIm and calculates the SliceTiming according to the number of slices in the third dimension If a path is given, it also checks if it can find a JSON sidecar, then it loads the JSON sidecar, and looks for SliceTiming inside it. If SliceTiming/SliceReadoutTime is found in the JSON sidecar, it prioritize it over the value in the x-struct For reference, we use these terms:

SliceTiming (the BIDS parameter) - it is a vector with the same length as the number of slices and contains the timing of the start of the readout of each slice relative to the first slice SliceReadoutTime - Legacy xASL parameter that will be phased out. It contains either a vector matching the BIDS definition of SliceTiming or a scalar with difference in readout times between the consecutives slices (i.e. the xASL legacy definition of SliceTiming) SliceTimingDiff - Internal parameter in this function for calculating the time difference between consecutive slices.

Admin
ShortestTR
Assign the vector value and check for vector consistency

xASL_quant_SliceTiming_ShortestTR.m

Format:

[x] = xASL_quant_SliceTiming_ShortestTR(x)

Description:

When the TR is set to "shortestTR" in the ASL acquisition, each ASL scan will have its unique TR. As this is shortest, there won't be a delay between the readout of the last slice and the end of the TR. Therefore, the time to read out all slices is TR - InitialPostLabelDelay - LabelingDuration, and dividing this by the number of slices gives the SliceReadoutTime

SPM

xASL_spm_BiasfieldCorrection.m

Format:

xASL_spm_BiasfieldCorrection(PathIn, SPMdir, Quality, MaskName, PathOut)

Description:

This function is a wrapper around the SPM "old segment" function, for biasfield removal. It is tested for M0 and mean control images. It conducts the following steps:

Create implicit mask
Define SPM 'old segmentation' settings
Run SPM 'old segmentation'
Delete temporary files
Rename temporary SPM file into output file

xASL_spm_affine.m

Format:

xASL_spm_affine(srcPath, refPath, fwhmSrc, fwhmRef[,otherList, bDCT, bQuality])

Description:

This SPM wrapper runs SPM's old normalize-estimate function, which calculates the affine transformation (i.e. linear + zooming and shearing) that is required to align the source image with the reference image. By default it does not estimate the low-degree Discrete Cosine Transform (DCT) to have a simple affine transformation but this can be enabled in this wrapper. Also note that this affine transformation uses a correlation cost function, hence it requires the source and reference images to have similar contrasts and resolution - or provide the resolution estimates so the smoothing can be done. This function does not change the orientation header by default, but it allows to change those of others through the otherList. If bDCT is used or no otherList given, it stores its estimated affine transformation as orientation difference matrix in a file with the same path but _sn.mat extension. For the provided smoothing FWHM, note that smoothnesses combine with Pythagoras' rule (i.e. square summing).

xASL_spm_coreg.m

Format:

xASL_spm_coreg(refPath, srcPath[, OtherList, x, sep, FastReg])

Description:

This SPM wrapper runs SPMs coregister-estimate function, which calculates the 6 parameter rigid-body transformation (a.k.a. linear) that is required to align the source image with the reference image. This 6 parameter transformation (i.e. 3 XYZ translations and 3 rotations) is applied to the orientation header of the source NIfTI image, and also to the images provided in OtherList (optional). Note that this SPM registration function uses a normalized mutual information (NMI) by default, enabling registration between two images with different contrast. Note that this algorithm will use the first volume of a multi-volume NIfTI

xASL_spm_deface.m

Format:

xASL_spm_deface(PathIn, bReplace)

Description:

This function removes the face from an anatomical NIfTI image, e.g. T1w or FLAIR, for disidentification/privacy purposes. When this script is run after the ExploreASL structural module, it does a pretty good job even for 2D images. However, note that this can always fail, strip part of the brain, or change the output of pipelines. So best not to compare results from defaced and non-defaced images. Also, note that defacing makes it difficult to ensure that the FLAIR and T1w are from the same subject.

xASL_spm_deformations.m

Format:

xASL_spm_deformations([x,] PathIn, PathOut[, Interpolation, InverseSpace, AffineTrans, DeformationPath])

Description:

This ExploreASL wrapper manages the SPM deformation tool. It takes multiple (ExploreASL pipeline) transformations and combines/concatenates them into a single transformation prior to applying it to the input images. This allows to apply multiple transformations with a single interpolation, avoiding propagation of undesired interpolation effects. Mainly used to get native space images into standard space, or vice versa. Best to combine as many files as possible within this function, since the deformation calculation (which is the most computation intensive part) needs to be performed once for multi-file resampling This function runs the following steps:

Statistics

xASL_stat_AtlasForStats.m

Format:

[x] = xASL_stat_AtlasForStats(x)

Description:

This function loads atlases, checks them, and their ROI names, for later use as ROI definition in xASL_stat_GetROIstatistics Note that the atlases should be integer values, or different 4rd dimensions (i.e. multiple images), that are mutually exclusive. This function takes the following steps:

Load atlas ROI names There should be a TSV sidecar to the atlas NIfTI file, as explained above.
deal with memory mapping
Resample atlas 50 1.5 mm^3 MNI
Converted atlas with integers to 4D binary image
Convert/compress masks into Columns
Print atlas overview image

xASL_stat_ComputeDifferCoV.m

Format:

diffCoV = xASL_stat_ComputeDifferCoV(imCBF)
diffCoV = xASL_stat_ComputeDifferCoV(imCBF,imMask)
diffCoV = xASL_stat_ComputeDifferCoV(imCBF,imMask,bPVC,imGM,imWM)
diffCoV = xASL_stat_ComputeDifferCoV(imCBF,imMask,bPVC,imGM,imWM,b3D)

Description:

It calculates the spatial DiffCoV value on finite part of imCBF. Optionally a mask IMMASK is provide, and PVC is done for bPVC==2 using imGM and imWM masks and constructing pseudoCoV from pseudoCBF image. For bPVC~=2, imGM and imWM are ignored. It is calculated in 2D or assuming also 3D edges based on B3D. Calculate derivate spatial CoV, by summing up differences in CBF between neighbors. The derivative uses Sobels filter.

xASL_stat_ComputeMean.m

Format:

[CBF_GM CBF_WM] = xASL_stat_ComputeMean(imCBF[, imMask, nMinSize, bPVC, bParametric, imGM, imWM])

Description:

It calculates mean or median of CBF over the mask imMask if the mask volume exceeds nMinSize. It calculates either a mean, a median, or a mean after PVC, depending on the settings of bPVC. For the PVC options, it needs also imGM and imWM and returns the separate PV-corrected values calculated over the entire ROI.

Admin
Mask calculations
Calculate the ROI statistics 3a. No PVC and simple mean 3b. No PVC and median 3c. Simple PVC 3d. Full PVC on a region

xASL_stat_ComputeSpatialCoV.m

Format:

sCov = xASL_stat_ComputeSpatialCoV(imCBF[, imMask, nMinSize, bPVC, bParametric, imGM, imWM])

Description:

It calculates the spatial CoV value on finite part of imCBF. Optionally a mask IMMASK is provide, ROIs of size < NMINSIZE are ignored, and PVC is done for bPVC==2 using imGM and imWM masks and constructing pseudoCoV from pseudoCBF image. For bPVC~=2, imGM and imWM are ignored

Admin
Create masks
sCoV computation

xASL_stat_EqualVariancesTest.m

Format:

[resTest, P] = xASL_stat_EqualVariancesTest(X[, alpha, type])

Description:

Brown-Forsythe or Levene's test for equality of variances. The response variable is transformed (yij = abs(xij - median(xj)) for Brown-Forsythe and yij = abs(xij - mean(xj)) for Levene's test). And then runs a one-way ANOVA F-test to check if the variances are equal.

xASL_stat_GetROIstatistics.m

Format:

[x] = xASL_stat_GetROIstatistics(x)

Description:

This function computes mean and spatial CoV for each ROI, in a [1.5 1.5 1.5] mm MNI space, with several ASL-specific adaptions:

Skip ROI masks that are smaller than 1 mL as this would be too noisy for ASL (ignored when x.S.IsASL==false)
Expand each ROI mask such that it has sufficient WM content (skipped when IsASL==false)
Create for each ROI mask a left, right and bilateral copy
Iterate over all subjects:
a) Load partial volume maps
b) Correct for WMH SEGM -> IS THIS STILL REQUIRED???
c) Load data
d) Show ROIs projected on ASL image
e) Actual data computations Partial Volume Correction (PVC) options: PVC==0 -> perform masking only, no regression PVC==1 -> single compartment regression, for pGM PVC==2 -> dual compartment regression for pGM & pWM (i.e. normal PVC) Here we mask out susceptibility artifacts (including outside FoV) for all ASL computations, and also mask out vascular artifacts for computing the mean.

While other artifacts/FoV can be masked out on population level (i.e. >0.95 subjects need to have a valid signal in a certain voxel), vascular artifacts differ too much in their location between subjects, so we mask this on subject-level.

Note that the words "mask" and "ROI" are used interchangeably throughout this function, where they can have a different or the same meaning

PM: WE COULD CHANGE THIS, INTO MASK BEING USED TO EXCLUDE VOXELS AND ROI FOR INCLUDING VOXELS

xASL_stat_MadNan.m

Format:

y = xASL_stat_MadNan(x[,flag, dim])

Description:

Calculates a Median/Mean Absolute deviation, but ignoring NaNs in the calculation. xASL_stat_MadNan(X) or xASL_stat_MadNan(X,0) computes xASL_stat_MeanNan(ABS(X-xASL_stat_MeanNan(X)) xASL_stat_MadNan(X,1) computes xASL_stat_MedianNan(ABS(X-xASL_st_MedianNan(X)).

xASL_stat_MeanSSIM.m

Format:

mssim=xASL_stat_MeanSSIM(imRef,imSrc[,dynRange])

Description:

Calculates the similarity index according to Want et al.

xASL_stat_MultipleLinReg.m

Format:

[b,CI,pval,stats] = xASL_stat_MultipleLinReg(X,Y[,bIntercept])

Description:

Performs a multiple linear regression Y=b*X+a and provides the intercept and regression coefficients beta including their significance and confidence intervals. It calculates additionally the goodness of the fit.

xASL_stat_PSNR.m

Format:

PSNR=xASL_stat_PSNR(imRef,imSrc)

Description:

Calculates the PSNR, needs two input arguments - 3D images of the same size. Uses 95% percentile instead of MAX.

xASL_stat_PairwiseDice.m

Format:

[DiceCoeff] = xASL_stat_PairwiseDice(GroupA, GroupB)

Description:

This function obtains for two lists of images Dice coefficients, for all possible permutations of both lists, by the following steps: 1. Admin (check cell, image exist etc) 2. Obtain matrix of pair-wise permutations 3. Obtain DICE scores

PM: Allow entering one group only PM: could extend with xASL_qc_TanimotoCoeff

xASL_stat_PrintStats.m

Format:

[x] = xASL_stat_PrintStats(x)

Description:

This function prints an overview of statistics from data that were acquired per ROI, in a TSV file. It starts by printing covariates (called "Sets"). Rows will be subjects/sessions, columns will be the sets and ROI-statistics. Any missing data will be skipped (setting them to NaN should have happened in a previous function).

This function performs the following steps:

First remove previous TSV-file, if already existed printing to a TSV file can be tricky if it is opened by Excel. Make sure to close previous versions first, otherwise this part will crash.
Print overview of sets to TSV as explained above. Uses subfunction xASL_stat_CreateLegend to put legends. Aim is to create a single TSV file that has a proper overview of the data, & is self-explanatory to those reading/using it.
Define number of ASL sessions, force to 1 in case of TT or volume metrics
Print the overview

xASL_stat_QuantileNan.m

Format:

y = xASL_stat_QuantileNan(x[,quant, dim])

Description:

Calculates a quantile, but ignoring NaNs in the calculation

xASL_stat_RobustMean.m

Format:

[NoOutliers, iOutliers, ThresholdDeviation] = xASL_stat_RobustMean(IM, ParameterFunction)

Description:

This function detects outlier images, that can be used to create a robust average, e.g. for template or biasfield creation. This is based either on the sum-of-squares with the mean image (SoS), or on the average relative asymmetry index (AI). Images that are median+/-3 mad off are defined as outliers. MAD = median/mean absolute difference

xASL_stat_ShapiroWilk.m

Format:

[H, P, W] = xASL_stat_ShapiroWilk(x[, alpha])

Description:

Performs the statistical test of normality - null hypothesis is that the sample is from normal distribution with unspecified mean and variance. Based on the sample kurtosis it performs either Shapiro-Wilk (for platykurtic) or Shapiro-Francia test (for leptokurtic).

xASL_stat_StdNan.m

Format:

y = xASL_stat_StdNan(x[,w,dim])

Description:

It behaves in a similar way as VAR - it directly passes all arguments to xASL_stat_VarNan.

xASL_stat_SumNan.m

Format:

y = xASL_stat_SumNan(x[,dim])

Description:

It uses the function SUM, but it sets all the NaNs to zero before calling it.

xASL_stat_UniquePairwisePermutations.m

Format:

[PermutationList] = xASL_stat_UniquePairwisePermutations(GroupA, GroupB)

Description:

This function lists for one or two samples of indices all possible permutations of indices, performing the following steps:

One sample permutations
Two sample permutations
Print conclusion

PM: Allow entering one group only PM: could extend with xASL_qc_TanimotoCoeff

xASL_stat_VarNan.m

Format:

y = xASL_stat_VarNan(x[,w,dim])

Description:

It behaves in a similar way as VAR.

xASL_stat_fcdf.m

Format:

F = xASL_stat_fcdf(F,M,N)

Description:

Calculates the cumulative distribution function of the F-distribution for degrees of freedom M,N at value F.

xASL_stat_tcdf.m

Format:

F = xASL_stat_tcdf(T,nu)

Description:

Calculates the cumulative distribution function of the Student's t-distribution for degrees of freedom nu at value T.

xASL_stat_ticdf.m

Format:

T = xASL_stat_ticdf(P,nu)

Description:

Calculates the inverse of cumulative distribution function of the Student's t-distribution for degrees of freedom nu at value P.

xASL_stat_ttest.m

Format:

[H,P,CI,stats] = xASL_stat_ttest(X[,M,alpha,tail,dim])

Description:

Performs a t-test that the distribution of the input data X has a mean different from 0 (or from a given mean M, or that the distributions X and Y have different means). A normal distribution of the data with an unknown variance is assumed.

xASL_stat_ttest2.m

Format:

[H,P,CI,stats] = xASL_stat_ttest2(X,Y[,alpha,tail,vartype,dim])

Description:

Performs a unpaired t-test that the distribution of the input data X has a mean different from that of Y. A normal distribution of the data with an unknown variance is assumed.

xASL_str2num.m

Format:

[DataOut] = xASL_str2num(DataIn[, bKeepCell, bReplaceNonNumerical])

Description:

str2num wrapper, which only converts strings to numbers, and allows inputting cells. Also, it replaces 'n/a' with NaN (BIDS convention). And it has some other functionality as described in bKeepCell & bReplaceNonNumerical above.

xASL_test_BIDSConversion.m

Format:

xASL_test_BIDSConversion(baseDirImport[, baseDirReference, bImport, bComparison])

Description:

Runs the DICOM to ASL-BIDS import for all data in the baseDirImport directory. Study directories are supposed to be in, containing a 'sourcedata' folder - this folder can contain subject directories and also sourceStructure.json and studyPar.json specifying the directory structure and the additional study parameters, respectively. The import creates first the 'analysis' subfolder with data after dcm2nii and with all tags read and saved to JSON. Then it assembles everything with the studyParameters and makes sure all is in BIDS format and saves it correctly in the 'rawdata' subdirectory.

This function runs the following sections: 1. Initialization 2. DICOM -> NII+JSON (i.e. dcm2niiX) 3. Manual curation for certain flavors 3a. Siemens_PCASL_3DGRASE_vascular 3b. Philips_PCASL_3DGRASE_R5.4_TopUp 3c. Siemens_PCASL_volunteer 3d. Siemens_PCASL_multiTI 4. Convert NII+JSON -> BIDS 5. Run the comparison with the reference directory

xASL_test_BIDSFlavorsFull.m

Format:

xASL_test_BIDSFlavorsFull(pathExploreASL,pathTest)

Description:

Runs the full testing on import and processing of the FlavorsDatabase. The testing directory path has to be provided with the FlavorsDatabase subdirectory containig the Flavors - this subdirectory is read, but not modified. New directories are created for that inside the test directory.

xASL_test_GetLogContent.m

Format:

[logContent] = xASL_test_GetLogContent(rootDir, [printContent], [storeRelativePath], [exportTable])

Description:

Get warnings and errors from log files.

Input check
Load all log files
Iterate over log files
Optional: Print log content
Optional: Export (0 = no export, 1 = TSV export, 2 = XLSX export)

Visualization

xASL_vis_AddIM2QC.m

Format:

[x] = xASL_vis_AddIM2QC(x,parms);

Description:

Checks which images already are loaded, and adds new image.

xASL_vis_CreateVisualFig.m

Format:

[ImOut, FileName] = xASL_vis_CreateVisualFig(x, ImIn, DirOut, IntScale, NamePrefix, ColorMap, bClip)

Description:

This function creates a visualization Figure by merging flexibly rearranging NIfTI slices, input matrix or path, managing colormaps for different merged image layers. Current use is for visual QC figures and overview in papers. Function is structured as:

Admin, deal with input arguments
Process image layers separately * xASL_im_TransformData2View: Reshapes image data into visualization figure * xASL_im_ClipExtremes: Clips image to given percentile also we scale for peak intensity, we make sure that there is no visible clipping/distortion * Convert to colors, using any input colormaps
combine image layers, using input argument IntScale
print figure

This function assumes that the first image is a grayscale background image (e.g. for transparancy reasons), if there are multiple images

xASL_vis_CropParmsAcquire.m

Format:

[xmin xmax ymin ymax] = xASL_vis_CropParmsAcquire(temp_image)

Description:

Goes from outside to inside to acquire crop settings. Works with grayscale images (2 dimensions per slice). Image position information (2D matrix) should be first 2 dimensions. Could include colordimension later on.

xASL_vis_CropParmsApply.m

Format:

ImageOut = xASL_vis_CropParmsApply(ImageIn,CropParameters)

Description:

This function crops 2D image matrices.

xASL_vis_Imwrite.m

Format:

[ImOut] = xASL_vis_Imwrite(ImIn, PathOut[, ColorMap, bRescale])

Description:

This functions takes an input image matrix, interpolates it to HD resolution (1920x1080) for visibility, and saves the image as jpg. This function avoids the graphic interface of Matlab, for running from CLI Careful: this function overwrites any existing PathOut.

xASL_vis_OverlapT1_ASL.m

Format:

xASL_vis_OverlapT1_ASL( x, ASL)

Description:

Part of ExploreASL. Shows spatial agreement ASL and probability maps.

xASL_vis_TileImages.m

Format:

[ImOut] = xASL_vis_TileImages(ImIn, nColumns)

Description:

Merges selected slices (3D) into one single 2D picture. Plots all slices in one figure with specified rows and columns, aiming for a square tile.

PM: can be extended to multiple slices

xASL_vis_TransformData2View.m

Format:

FigureOut = xASL_vis_TransformData2View(ImagesIn, x)

Description:

This function changes the dimensionality and reshapes the input images in such a way that they are nicely tiled in a mosaic for visualization purposes. Reshaping a series of images with this function can be useful for visualization of SPM/voxel-based analyses.

xASL_vis_VisualQC_TopUp.m

Format:

[MeanAI_PreTopUp_Perc, MeanAI_PostTopUp_Perc] = xASL_vis_VisualQC_TopUp(PathPopB0, PathPopUnwarped, x, iSubject, CheckDir)

Description:

This function creates a Figure that showes the effect of TopUp with 6 images with axial slices: the NormPE, RevPE and their difference image in colorscale, and this before (upper row) & after (lower row) TopUp.

xASL_vis_VisualizeROIs.m

Format:

xASL_vis_VisualizeROIs(x, ROI_list)

Description:

Creates for each subject a JPEG image containing the original T1w, WMH_SEGM and T1w after lesion-filling.

xASL_wrp_LinearReg_Others2T1w.m

Format:

xASL_wrp_LinearReg_Others2T1w(x[, bAutoACPC])

Description:

This submodule registers T1c and T2 linearly to the T1w