diff --git a/1.11.0/404.html b/1.11.0/404.html new file mode 100644 index 0000000..5aaf7b3 --- /dev/null +++ b/1.11.0/404.html @@ -0,0 +1,620 @@ + + + +
+ + + + + + + + + + + +Format:
+xASL_wrp_CreateAnalysisMask(x)
+
+Description:
+This function creates an analysis mask with the following steps: +0. Create FoV mask (native & MNI spaces) +1. Detect negative vascular signal (native & MNI spaces, within pGM>0.5) +2. Detect peak vascular signal (native & MNI spaces, within pGM==80% percentile on ASL image) +3A. Brainmasking & FoV-masking native space +3B. Brainmasking & FoV-masking standard space +3C. Save brain mask for image processing (e.g., BASIL) +4. Save vascular masks +- Add WM vascular parts back to the mask (defined as pWM>0.8) & remove extracranial signal +In the WM, negative or peak signal is more expected from +noise rather than from intra-vascular signal, not many +big vessels exist in the WM +5. Create susceptibility mask (standard space only) +Here, we combine manually segmented susceptibility artifact regions in which +a population-based susceptibility probability map is created +This map is combined (i.e. taking the product) with the mean control & PWI +intensity distribution in these regions. This product +is thresholded with the average of the 75th percentile & +15% of the intensity (for a bit more robustness against individual variability in sinus sizes).
+Format:
+xASL_wrp_PVC(x)
+
+Description:
+This submodule performs partial volume correction (PVC) in native ASL space. It runs the Asllani's method +for partial volume correction by linear regression. It has two main extensions - first it uses a 3D kernel. +Second, it can use a Gaussian weights instead of the default flat kernel.
+Format:
+xASL_wrp_PreparePV(x, bStandardSpace)
+
+Description:
+This submodule prepares partial volume correction (PVC) by creating correct PV maps in ASL resolution, in native space, +as well as in standard space if requested (to perform PVC in +standard space):
+If bStandardSpace:
+else: run step 3 only, which will use the effective spatial resolution +that is default for the respective sequence: +2D EPI: [1 1 1] * VoxelSize +3D GRASE: [1.1 1.1 1.38] * VoxelSize +3D spiral: [4.3 4.4 10.1] * VoxelSize (assuming GE uses the upsampled 2x2x4 mm +& run steps 1&2, but in native space these entail presmoothing & +downsampling.
+Format:
+xASL_wrp_ProcessM0(x)
+
+Description:
+This submodule performs the image processing and +quantification of M0 maps (if they exist), with the following steps:
+Any M0 will be processed here. Even if part of the subjects does not +have an M0, since this can be later imputed, or an average population +M0 image could be used. Also, without background suppression and +without an M0, the MeanControl image is before saved as M0, and will +be processed here as well.
+Note that any voxel-size differences between M0 and ASL are allowed +here: step 0B below rescales the PD inside an M0 voxel to the same as +the ASL resolution (assuming a voxel with half volume contains half +the amount of protons). The M0 is further processed in standard +space, and reduced to a biasfield. For the quantification in standard +space, the PWI and M0 are now by definition in the same space. +Also, the standard space M0 biasfield is resampled to the native PWI +space (at the end of step 3B), ensuring that both are also in the +same native space.
+Format:
+xASL_wrp_Quantify(x [, PWI_Path, pathOutputCBF, M0Path, SliceGradientPath])
+
+Description:
+This submodule converts PWIs to quantified CBF maps (or +related derivatives). Note that we don't delete x.P.Path_PWI4D here, as +this NIfTI file may be needed by xASL_wrp_VisualQC_ASL.m
+Format:
+xASL_wrp_RealignASL(x[, bASL])
+
+Description:
+This submodule estimates motion by spm_realign, which uses a +rigid-body registration (3 translations, 3 rotations). It runs ENABLE to +reject outliers and provides a visualization. ENABLE, QC and visualizations +are based on the Net Displacement Vector (NDV) (in mm): +according to Pythagorean/Euclydian RMS +https://www.jiscmail.ac.uk/cgi-bin/webadmin?A2=ind1211&L=fsl&P=R34458&1=fsl&9=A&J=on&d=No+Match%3BMatch%3BMatches&z=4 +view this link for image of rotation roll, pitch and yaw https://www.google.nl/search?q=rotation+pitch+yaw+roll&espv=2&tbm=isch&imgil=LW3Nn1K-L6Oc7M%253A%253B-aSyykkRityJoM%253Bhttp%25253A%25252F%25252Fwww.grc.nasa.gov%25252FWWW%25252Fk-12%25252Fairplane%25252Frotations.html&source=iu&usg=__MlLQ5VuyRbm6kZP0vBJlPxmfbkw%3D&sa=X&ei=TWfjU4WcK4bqyQPqu4Fo&ved=0CD8Q9QEwBQ&biw=1680&bih=946#facrc=_&imgdii=_&imgrc=LW3Nn1K-L6Oc7M%253A%3B-aSyykkRityJoM%3Bhttp%253A%252F%252Fwww.grc.nasa.gov%252FWWW%252Fk-12%252Fairplane%252FImages%252Frotations.gif%3Bhttp%253A%252F%252Fwww.grc.nasa.gov%252FWWW%252Fk-12%252Fairplane%252Frotations.html%3B709%3B533
+This submodule performs the following steps:
+Format:
+xASL_wrp_RegisterASL(x)
+
+Description:
+This submodule registers ASL images to T1w space, by using a +combination of the registration techniques below. Note that in the +absence of raw structural files (i.e. T1.nii[.gz] or T1_ORI.nii[.gz], +it will recreate dummy files from standard space to do this registration
+M0-T1w rigid-body -> this works well in 2D EPI sequences +PWI-pGM rigid-body -> this is robust across sequences with different +readouts and consequently different effective spatial resolutions. With +low spatial resolution (e.g. GE 3D spiral product sequence), M0-T1w +registration may not work, but PWI-pGM will work. +PWI-pGM registration fails with large (vascular) artifacts, therefore +this is performed only with relatively low spatial CoV. +PWI-pGM affine -> If the spatial CoV is sufficiently low, this can +improve the registration
+These images are registered to ASL templates that were inversely +transformed from MNI to the T1w space (& resampled to the ASL space) +As this would have an ever higher similarity with the M0 & PWI
+This submodule performs the following steps: +0. Administration: +- A. ASL4D is dealth with, if motion peaks were removed this is called +despiked_ASL4D +- B. a default "OtherList" is specified. This is used every +registration instance, except for removing the ref and src NIfTIs +used in the registration instance. Also, inside the registration +function the unexisting OtherList NIfTIs are skipped +- C. Define paths to the ASL templates +- D. Previous registration output files are removed +- E. Allow registration without structural data +- F. native->MNI transformation flow field y_T1.nii is smoothed to the +effective ASL resolution y_ASL.nii +- G. Registration contrasts are dealth with: +x.modules.asl.bRegistrationContrast - specifies the image contrast used for +registration (OPTIONAL, DEFAULT = 2): +- 0 = Control->T1w +- 1 = CBF->pseudoCBF from template/pGM+pWM +(skip if sCoV>0.667) +- 2 = automatic (mix of both) +- 3 = option 2 & force CBF->pseudoCBF irrespective of sCoV or Tanimoto coefficient +- H. Dummy src NIfTIs are created: +mean_control.nii to register with T1w +mean_PWI_Clipped.nii to register with pseudoCBF +- I. Create reference images, downsampled pseudoTissue
+x.modules.asl.bAffineRegistration - specifies the ASL-T1w rigid-body registration is followed up by an affine +registration (OPTIONAL, DEFAULT = 0) +- 0 = affine registration disabled +- 1 = affine registration enabled +- 2 = affine registration automatically chosen based on +spatial CoV of PWI +x.modules.asl.bDCTRegistration - Specifies if to include the DCT registration on top of Affine, all other requirements for +affine are thus also taken into account (OPTIONAL, DEFAULT = 0) +- 0 = DCT registration disabled +- 1 = DCT registration enabled if affine enabled and conditions for affine passed +- 2 = DCT enabled as above, but use PVC on top of it to get the local intensity scaling right
+Format:
+xASL_wrp_ResampleASL(x)
+
+Description:
+This submodule resamples native space NIfTIs to standard space, using the deformation fields computed in the structural module +after smoothing these transformation fields to the ASL resolution. +The applied interpolation is a combination of all transformations (e.g. motion correction, registration to +T1w, and transformation of T1w to standard space. This submodule performs the following steps:
+Format:
+xASL_wrp_VisualQC_ASL(x)
+
+Description:
+This submodule performs several visualizations for visual & quantitative QC.
+For any help please contact the lead authors/developers at h.j.mutsaerts@amsterdamumc.nl or j.petr@hzdr.de. To report new issues and follow-up the discussion on new developments, please visit the GitHub page of the project. Or visit our Google-forum.
+Versions included & used third-party tools (see /External/README_SPM.txt
):
Versions included & used third-party tools (see /External/README_SPM.txt
):
Versions included & used third-party tools (see /External/README_SPM.txt
):
Import
. BIDS2Legacy
conversion is now done as first step of the processing module.log
as subject.xASL_adm_GzipAllFiles
.xASL_csvWrite
.Development
folder.xASL_num2str
always outputs a row vector.studyPar.json
and dataPar.json
.x.modules.asl.ApplyQuantification
.ASLContext
not matching with NIfTI dimensions.Versions included & used third-party tools (see /External/README_SPM.txt
):
xASL_module_Population
now does not start when ExploreASL is called in parallelization mode.xASL_system
function for all command line calls.xASL_module_ASL
to restore a correct order of all steps.xASL_im_CreateAnalysisMask
.ExploreASL
.xASL_spm_admin
crashed with cell input.PAR/REC
.x.SUBJECT/S
and x.overview
for subjects with illegal characters.x
structure clean-up between import and processing.ExploreASL
/SPM
routines.xASL_im_ResampleLinearFair
code.ExploreASL
README file.Versions included & used third-party tools (see /External/README_SPM.txt
):
xASL_bids_BIDS2Legacy
(check for empty visits), ExploreASL_Master
(update unit testing), xASL_stat_StdNan
(update unit testing), xASL_qc_CreatePDF
(minor change related to new PDF filename), xASL_imp_DCM2NII_Subject_SortASLVolumes
(minor bugfix), xASL_imp_NII2BIDS
(print user feedback for existing subjects/sessions), xASL_imp_Initialize
(check scan tokens), xASL_wrp_Quantify
& xASL_quant_SinglePLD
& xASL_quant_Basil
(return error if FSL is missing), xASL_adm_GetDeprecatedFields
(add BASIL field), xASL_im_M0ErodeSmoothExtrapolate
(use correct defaults for robustness, add warning)bUseBasilQuantification
in both a 2D and 3D ASL datasetparticipants.tsv
to BIDS formatxASL_im_Lesion2Mask
: Separate masks in 4D NIfTI if they are not mutually exclusivex
struct and with that some of the ExploreASL settings were moved to dedicated fields, for backwards compatibility a table was created and automated workflows were implementedxASL_wrp_CreateBiasfield
xASL_adm_DeleteFileList
, which now understands if the same file is tried to delete twice (e.g., in the case of symbolic links)xASL_fsl_TopUp
ASL_1
is missingn/a
for now, and use '_'
for placeholder elementscat_wmh_miccai2017.nii
Versions included & used third-party tools (see /External/README_SPM.txt
):
x
: x.opts
(input arguments and their derivatives), x.dir
(directories), x.settings
(mostly booleans for pipeline settings), x.dataset
(dataset related fields), x.external
, ...ExploreASL
reads folders and automatically searches for sourceStructure, studyPar and dataPar JSON filesbids.layout
: avoid printing the same warning repetitively in case multiple scans in a data set have the same issuex.SUBJECT
to avoid crashes for error reporting in the population modulexASL_adm_GetPopulationSessions
if no sessions are foundxASL_adm_GzipAllFiles
: Allow spaces in an input path for macOS/LinuxxASL_vis_CreateVisualFig
: allow empty overlaysxASL_stat_PrintStats
: Fix visits bug (legacy format)xASL_adm_GetPopulationSessions
gave incorrect warningsdataPar*.json
or studyPar*.json
or sourcestructure*.json
are presentExploreASL_Initialize
Versions included & used third-party tools (see /External/README_SPM.txt
):
spm_jsonread
and spm_jsonwrite
for all operationsx.MakeNIfTI4DICOM
to create CBF optimized for DICOM creation/PACS exportImageType
DICOM field to detect scan order in GE in DICOM->BIDS importstring
and contains
functions to ensure Matlab compatibility for R2016xASL_adm_ReplaceSymbols
crash when trying to replace sub-strings in PhoenixProtocol fieldMNI_Structural.*
filesVersions included & used third-party tools (see /External/README_SPM.txt
):
xASL_stat_GetROIstatistics
provide more feedback on missing imagesCustomScripts
with study-specific scripts to a separate repositoryx.DummyScanPositionInASL4D
that removes marked dummy scans when splitting ASL to ASL+M0+dummyxASL_qc_SortBySpatialCoV
now use all subjects without skippingxASL_adm_UnixPath
: bug with Windows+WSLxASL_stat_GetROIstatistics
fix skipping of actual ROI extractionxASL_adm_CleanUpBeforeRerun
delete files correctlyxASL_stat_MedianNan
for all-NaN inputxASL_test_getLogContent
Versions included & used third-party tools (see /External/README_SPM.txt):
+SliceReadoutTime
for pCASL)Versions included & used third-party tools (see /External/README_SPM.txt):
+(Lesion\_(FLAIR|T1)\_\\d\\.nii)
from WMH_SEGM.nii
.nii(.gz)
management in xASL_spm_deformations
: allow either .nii or .nii.gz as input, treat them equally, and when .nii.gz
is provided as output path, zip the resulting deformed imagexASL_im_SplitImageLabels
: Allow splitting labels, and warping them to standard space.
+This is part of a continuous development on creating average flow territory templates and figures.bNativeSpaceProcessing
from TestDataSet for now, return this when bNativeSpaceProcess
is made more modularxASL_SysMove
error in Windows when a path includes whitespaces ' 'xASL_str2num
& xASL_init_LoadMetaData
)x.S.SUBJECTID
and S.DAT
data for the last subject/sessionxASL_im_CreateAnalysisMask
in native space mode when in parallel executionstrcmp
by strcmpi
xASL_adm_UnzipNifti
& xASL_io_SaveNifti
when path is incompletexASL_module_Population
)xASL_init_LoadMetaData
iRow
counting fix in xASL_bids_Add2ParticipantsTSV
xASL_im_ClipExtremes
3D_spiral
instead of 3D spiral
xASL_qc_TestExploreASL
: improve Table creationxASL_qc_TestExploreASL
: Complete functionality by allowing Windows parallelization & testing the Windows ExploreASL compilation. Also added unit testing framework in the same issue.xASL_io_Nifti2Im
: manage the detection of odd scalingxASL_SysMove
: diz illegal symbols WindowsxASL_wrp_CreatePopulationTemplates
: minor bugfixIssue #118 xASL_adm_GzipAllFiles
doesn't crash anymore in Windows
Issue #116 ExploreASL testing fixes:
+xASL_bids_parms2BIDS.m
now deals correctly with vectors and SliceReadoutTime = 'shortestTR'
: created function for this: xASL_quant_SliceReadoutTime_Shortest_TR
Versions included & used third-party tools (see /External/README_SPM.txt):
+Provide a lesion or ROI mask, to be used not only for cost function masking but also as standard space ROI for ROI-analysis
+ This use is now easier, by simply adding Lesion_FLAIR_1.nii
or Lesion_T1_2.nii
etc, and visualization improved. These masks are now automatically created (where lesion can be any other ROI):
Intralesional
+Contralateral (iii)
+Option x.S.bMasking added, allowing specifying masking separately for:
+bSusceptibilityMask
+pGM>0.7
)brainmasking when loading for lower memory usage
+Affine registration improved & Discrete Cosine Transform (DCT) non-linear registration option added, including an option with partial volume correction built-in for improved DCT-based registration
+xASL_adm_UnixPath()
for Unix system calls, for correct path usage (e.g. for spaces that need escaping).m
to .json
for DataPar file - subject-regexpxASL_adm_LoadParms
for converting parameters ASL flavors to BIDS/ExploreASL internallyExploreASL
for ExploreASL_Master
xASL_csvWrite, xASL_csvRead, xASL_tsvRead, xASL_tsvWrite
xASL_io_Nifti2Im
now detects erroneously extreme high scaling (potential import issue with Philips RescaleSlope)
+ issues a warning and/or tries to fix automatically for FLAIR/T1w imagesExploreASL_Import
for different ASL flavorsxASL_vis\_\*
instead of xASL_im\_\*
)Versions included & used third-party tools (see /External/README_SPM.txt
):
xASL_adm_DefineASLSequence.m
(#16)x.ApplyQuantification = [0 0 0 0 0];
(#14)help ExploreASL_Master
where you can replace ExploreASL_Master by the actual function nameThis is the first release version.
+Versions included & used third-party tools (see /External/README_SPM.txt):
+++I am new to ASL-MRI and I do not know how to import and process data. Where should I start?
+
We recommend to start with our ASL-BIDS and Basics tutorials. For more details on the BIDS data format in general, we recommend to read the BIDS documentation.
+++I would like to use ExploreASL, but I do not have a Matlab license. Can you help me?
+
ExploreASL is based on a variety of toolboxes that were written in Matlab. We have an ExploreASL GUI, a compiled version, and a docker integration though, so that everyone can use ExploreASL without Matlab license fees - see the Installation Tutorial.
+++Doing x worked just fine in ExploreASL version a but doesn't work in version b. What should I do now?
+
We recommend to check out the Change Log tab. Changes between different versions of ExploreASL are documented there.
+++I developed a nice method/idea on how to process a specific kind of dataset. How can I support ExploreASL by adding my code to it?
+
We always look forward to new methods and tools to improve ExploreASL. Please feel free to contact the developer team, we normally answer to e-mails pretty quickly.
+++I was reprocessing a dataset with ExploreASL version b which was previously processes with version a. Now I get weird warnings. What should I do now?
+
Parameters and settings can change between different versions of ExploreASL. We try to keep it to a minimum, but sometimes there is no way around it. Check the dataPar template and the Change Log tab, to find out if some of your x-structure variables have changed.
+++I have a question that is not in the list above. What should I do now?
+
Please feel free to contact the developer team, we normally answer to e-mails pretty quickly. There are also bi-weekly meetings of the developer team, so if you feel like you could contribute to our open-source project or you would like to ask a question in person, feel free to ask for an invite.
+ + + + + + +Format:
+[resultText] = xASL_adm_BreakString(textToPrint,SymbolToFill, bColor, bNewLines, bPrintImmediately)
+
+Description:
+Pads symbols left and right of a string. By default it adds new lines, and colors, and prints the string, with +a possibility to turn each of these options off.
+Format:
+[OutputNumber] = xASL_adm_CatchNumbersFromString(InputString)
+
+Description:
+Extracts a number from a char array.
+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.
+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:
+For executable files we also want 775. +Note that the permission to 'execute a folder' means opening them.
+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.
+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:
+NB: still need to add xASL_module_func & xASL_module_dwi for EPAD
+Format:
+x = xASL_adm_CleanUpX(x)
+
+Description:
+Clean-Up before processing pipeline.
+Format:
+[RMS] = xASL_adm_CompareDataSets(RefAnalysisRoot,SourceAnalysisRoot,x,type,mutexState)
+
+Description:
+Compare data sets is used to ...
+Format:
+[NewList] = xASL_adm_CompareLists(list1, list2)
+
+Description:
+This script compares two single dimension lists.
+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.
+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.
+Format:
+[iSubj iSess] = xASL_adm_ConvertSubjSess2Subj_Sess(nSessions, iSubjSess)
+
+Description:
+Converts combined SubjectSession index to subject & session +indices. Useful for data lists in ExploreASL.
+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.
+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.
+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.
+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:
+PM: Simplify/optimize this code, to make filename variable changing, +search within subject-directories, etc. Combine the parts searching for +missing & summarizing count.
+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.
+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.Q.Sequence. +It does so by checking known combinations of readout dimensionality +(x.Q.readoutDim) and Vendor, knowing the product sequences of the Vendors.
+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...
+Format:
+[parms pathDcmDictOut] = xASL_adm_Dicom2Parms(imPar, 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.
+Format:
+xasl_adm_FindByRegExp(root, dirSpecs[, varargin])
+
+Description:
+Recursively find files in the root directory according to the dirSpecs.
+Format:
+INDEX = xASL_adm_FindStrIndex(ARRAY, STRING)
+
+Description:
+Similar to find, but then for a cell array filled with strings. +Only takes 4 dimensions.
+Format:
+nameConversionTable = xASL_adm_GetDeprecatedFields()
+
+Description:
+This script is mainly used to improve backwards +compatibility. Check the usage in both xASL_adm_LoadX +and xASL_io_ReadDataPar.
+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.
+Format:
+num = xASL_adm_GetNumFromStr(str)
+
+Description:
+Obtains single number from string. +CAVE there should only be one number!
+Format:
+scaleFactor = xASL_adm_GetPhilipsScaling(parms, header)
+
+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. +The function works with Philips-specific scale-slopes: +RWVSlope = Real world value slope (0040,9225) +MRScaleSlope (2005,100e), (2005,110e), (2005,120e) +RescaleSlopeOriginal (2005,0x140a), (2005,110a) +These are different from the standard slopes in DICOM that are used as display slopes in Philips: +RescaleSlope (0028,1053) +With new version of dcm2niix-20220720 and ExploreASL-1.10.0, dcm2niix does RWVSlope scalings correctly and we do not have to fix that.
+Format:
+UserName = xASL_adm_GetUserName()
+
+Description:
+Get the name of the current user.
+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.
+Format:
+[INname, OUTname] = xASL_wrp_LesionResliceList(x,bLesion_T1,bLesion_FLAIR,bROI_T1,bROI_FLAIR)
+
+Description:
+Creates list of structural image paths to reslice.
+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:
+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
+Format:
+mergedStruct = xASL_adm_MergeStructs(mainStruct, secondaryStruct)
+
+Description:
+It merges two structures. It takes everything from the mainStruct and keep it as it is. It adds all fields from the secondaryStructure +to the main structure while checking for duplicates. It is not overwriting anything, all duplicit content is taken from mainStruct. +It works iteratively by correctly merging also the substructs.
+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.
+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).
+Format:
+info =xASL_adm_ParReadHeader(filename)
+
+Description:
+Function for reading the header of a Philips Par / +Rec MR V4.* file.
+Format:
+xASL_adm_RemoveDirectories(root)
+
+Description:
+Script to remove all ExploreASL related paths.
+Format:
+xASL_adm_RemoveLogFilesForRerun(rootDir);
+
+Description:
+Removes all log files from any directory containing .log files.
+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).
+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
+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.
+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
+Format:
+[outputString] = xASL_adm_SortStringNumbers(inputString[, numberPatternInString])
+
+Description:
+This function sorts strings based on numbers +Normal matlab sort would sort {'ASL_1', 'ASL_2', 'ASL_12'} +to {'ASL_1', 'ASL_12', 'ASL_2'}, +this function sorts them +to {'ASL_1', 'ASL_2', 'ASL_12'}
+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.
+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.
+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.
+Format:
+[Parms] = xASL_adm_uiGetInput(Parms)
+
+Description:
+Checks whether input fields are present, or requests them.
+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:
+Format:
+[bidsPar, TypeIs, pathOrig, pathDest] = xASL_bids_BIDS2Legacy_CompilePathsForCopying(bidsPar, TypeIs, ModalityIs, RunIs, iSubjSess, BIDS, TypeRunIndex, ModalityFields, pathLegacy_SubjectVisit)
+
+Description:
+Compile paths for BIDS to Legacy copying.
+Format:
+[bidsPar, pathOrig, pathDest, TypeIs] = xASL_bids_BIDS2Legacy_ManageSidecars(bidsPar, pathOrig, pathDest, TypeIs)
+
+Description:
+Manage JSON sidecars for BIDS2Legacy conversion.
+Format:
+xASL_bids_BIDS2Legacy_ParseModality(BIDS, bidsPar, SubjectVisit, iSubjSess, ModalitiesUnique, nModalities, bOverwrite, pathLegacy_SubjectVisit)
+
+Description:
+Parse modality for BIDS to Legacy conversion.
+Format:
+xASL_bids_BIDS2Legacy_ParseScanType(modalityConfiguration, SubjectVisit, RunsUnique, RunsAre, bOverwrite, Reference, bidsPar, ModalityIs, iSubjSess, BIDS, ModalityFields, pathLegacy_SubjectVisit)
+
+Description:
+Parse scan type during BIDS to Legacy conversion.
+Format:
+xASL_bids_BIDS2xASL_CopyFile(pathOrig, pathDest, bOverwrite)
+
+Description:
+Copy files for BIDS to Legacy conversion.
+Format:
+jsonOut = xASL_bids_BIDSifyASLJSON(jsonIn, studyPar, headerASL)
+
+Description:
+It makes all the conversions to a proper BIDS structure, 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
+Format:
+jsonOut = xASL_bids_BIDSifyASLNII(jsonIn, bidsPar, pathIn, pathOutPrefix)
+
+Description:
+It modifies the NIfTI file to take into account several BIDS +specifics. Specifically, it applies the previously calculated +scalings, and it saves the ASLcontext.tsv file,
+Format:
+jsonOut = xASL_bids_BIDSifyAnatJSON(jsonIn)
+
+Description:
+It makes all the conversions to a proper BIDS structure, 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
+Format:
+[jsonOut,bTimeEncoded, bTimeEncodedFME] = xASL_bids_BIDSifyCheckTimeEncoded(jsonIn, jsonOut, nVolumes)
+
+Description:
+Check for time encoded sequence.
+Format:
+[jsonOutM0, jsonOutASL] = xASL_bids_BIDSifyM0(jsonIn, jsonASL, studyPar, pathM0In, pathM0Out, headerASL)
+
+Description:
+It makes all the conversions to a proper BIDS structure, checks the existence of all BIDS +fields, removes superfluous fields, checks all the conditions and orders the structure on +the output. It works according to the normal BIDS, or ASL-BIDS definition. It modifies +the NIfTI file to take into account several BIDS specifics. +Specifically, it applies the previously calculated scalings.
+Format:
+[bImportedExploreASL, bImportedSameVersion, versionExploreASLBIDS, bImportedBETA] = xASL_bids_CheckDatasetDescription(datasetDescription, versionExploreASL)
+
+Description:
+Check the dataset_description.json field contents with special regard to the import version.
+Format:
+strError = xASL_bids_CompareFieldLists(jsonStructA, jsonStructB, fieldList, ignoreFields)
+
+Description:
+This script compares the content of two JSON files for +the BIDS flavor testing.
+Format:
+[identical,differences,dn] = xASL_bids_CompareStoreDifference(bPrintReport,differences,dn,allFiles,iFile)
+
+Description:
+Store the difference found in a TEXT file.
+Format:
+[identical,results,reportTable] = xASL_bids_CompareStructures(pathDatasetA,pathDatasetB,[bPrintReport,threshRmseNii,detailedOutput,printWarnings,ignoreLogs]);
+
+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.
+Format:
+[identical,differences] = xASL_bids_CompareStructuresCheckContent(filesDatasetA,filesDatasetB,pathDatasetA,pathDatasetB,identical,bPrintReport,detailedOutput,threshRmseNii)
+
+Description:
+This script iterates over the provided files (filesDatasetA,filesDatasetB). +There are different comparisons implemented for JSON, TSV, TEXT, & NIFTI files.
+Format:
+[differences,identical,dn] = xASL_bids_CompareStructuresJSON(differences,identical,bPrintReport,allFiles,iFile,dn,currentFileA,currentFileB)
+
+Description:
+This script compares the content of two JSON files for +the BIDS flavor testing.
+Format:
+[differences,identical,dn] = xASL_bids_CompareStructuresNIFTI(differences,identical,bPrintReport,detailedOutput,allFiles,iFile,dn,currentFileA,currentFileB,threshRmseNii)
+
+Description:
+This script compares the content of two NIFTI files for +the BIDS flavor testing.
+Format:
+[differences,identical,dn] = xASL_bids_CompareStructuresTEXT(differences,identical,bPrintReport,allFiles,iFile,dn,currentFileA,currentFileB)
+
+Description:
+This script compares the content of two TEXT files for +the BIDS flavor testing.
+Format:
+[differences,identical,dn] = xASL_bids_CompareStructuresTSV(differences,identical,bPrintReport,allFiles,iFile,dn,currentFileA,currentFileB)
+
+Description:
+This script compares the content of two TSV files for +the BIDS flavor testing.
+Format:
+x = xASL_bids_CompleteBIDS2Legacy(x)
+
+Description:
+Finish the remaining conversion steps, which are not done for each subject individually.
+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.
+Format:
+[json] = xASL_bids_CreateDatasetDescriptionTemplate(draft, versionExploreASL)
+
+Description:
+This script creates a JSON structure which can be saved +using xASL_io_WriteJson 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.
+Format:
+xASL_bids_DRO2BIDS(droTestPatient, [droSubject, deleteGroundTruth, exploreaslVersion])
+
+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_wrp_BIDS2Legacy script. +An exemplary usage is shown in the unit test called +xASL_ut_UnitTest_function_BIDS2Legacy.
+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.
+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]).
+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
+Format:
+NiftiPaths = xASL_bids_MergeNifti(NiftiPaths, seqType[, niiTable])
+
+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:
+dcm2nii outputs GEs deltaM and M0scan separately, even though they are scanned in a single sequence and should belong together +Siemens sometimes stores all controls and labels separately, which need to be reordered according their acquisition order
+This function performs the following steps in subfunctions:
+Format:
+jsonIn = xASL_bids_MergeStudyPar(jsonIn,studyPar,bidsModality);
+
+Description:
+Check if required fields exist in studyPar but not in jsonIn or if we can find them in other ways.
+The BIDSification of JSON metadata requires at least some basic fields. If dcm2niix can't extract +fields like Manufacturer from the DICOM data (strict anonymization), we need to be able to read them +from the studyPar JSON (manually inserted). Alternatively we can check other DICOM tags for information.
+This function can potentially be enhanced in future release to fix other fields besides the Manufacturer as well. +To enable this functionality for different modalities, we introduced the bidsModality parameter.
+This function is called by:
+xASL\_bids\_BIDSifyM0
xASL\_bids\_BIDSifyASLJSON
xASL\_bids\_BIDSifyAnatJSON
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.
+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.
+Format:
+[parameterList,phoenixProtocol] = xASL_bids_PhoenixProtocolReader(rawPhoenixProtocol)
+
+Description:
+Function to parse the raw phoenix protocol. This function is usually called from xASL_bids_GetPhoenixProtocol.
+Format:
+xASL_bids_ValidateNiftiName(fileName,perfType)
+
+Description:
+Validate the NIFTI filename based on the regular expressions from bids-matlab.
+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
+Format:
+imageType = xASL_bids_determineImageTypeGE(jsonPar)
+
+Description:
+Determine the image type of a GE DICOM.
+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:
+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
+The following options are processed: +1. Included - The M0 file is included in the ASL timeseries as specified in the aslContext +2. Separate - M0 image is already provided as a separate image - checks for its existence +3. Estimate - If a single M0 values is provided then keep it, just rename the field +4. Absent - In this case we use the control image as pseudo-M0, but we have to verify if there is no background suppression +or if yes, then the background suppression timings also need to be specified
+Format:
+xASL_dev_DocCrawler(inputPath)
+
+Description:
+This function checks each individual file header from the ExploreASL source coude and +extracts the information. The results is saved as a markdown file to be used for +Deploying the documentation web.
+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).
+Format:
+xASL_dev_DocInitialize
+
+Description:
+This function generates all markdown files, which are necessary for the mkdocs documentation - i.e. it initializes the MD files needed +for deploying the documentation. It copies the manually edited MD files and crawls through function headers to ready everything for the +deployment
+Format:
+xASL_adm_MakeStandalone(outputPath, bCompileSPM, 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:
+Format:
+[x] = xASL_adm_RunFSL(FSLCommand, x[, OutputZipping, NicenessValue, bVerbose])
+
+Description:
+This function runs an FSL command from ExploreASL:
+Supports .nii & .nii.gz, Linux, MacOS & Windows (WSL)
+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
+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.
+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.
+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.
+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
+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:
+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.S.masks.WBmask, which completely +engulfes pGM, pWM & pCSF.
+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.
+Format:
+[identical,RMSE] = xASL_im_CompareNiftis(pathA,pathB)
+
+Description:
+Compare two niftis. Untouched comparison based on copies.
+Format:
+[DiceCoeff] = xASL_im_ComputeDice(imA, imB)
+
+Description:
+This function calculates the Dice coefficient of image overlap.
+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:
+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
+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:
+Format:
+xASL_im_CreateSliceGradient(x)
+
+Description:
+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:
+Format:
+[LR_flip_YesNo] = xASL_im_DetermineFlip(PathOrientationResults)
+
+Description:
+This functions check determinants before and after image processing +(nii.mat0 vs nii.mat, respectively) to find any potential +left-right processing. This function performs the following +steps: +1. Determine correct row, differs between Matlab versions +2. If units are printed as second row, the data starts on the third row +3. Determine column indices +4. Find left-right flips
+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.
+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
+Format:
+el = xASL_im_DilateErodeSphere(R)
+
+Description:
+Creates a 3D structuring element (binary) sphere with the given diameter (R) and size 2*R+1
+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:
+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.
+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!).
+Format:
+xASL_im_FlipNifti(pathInput[, flipAxis, bOverwrite])
+
+Description:
+This function allows correcting an inappropriate flip in the image matrix. It +will not change the orientation matrix in the header but the image +itself. So any NifTI program will not be aware of this flip!
+This function runs the following steps: +1. Manage if we overwrite the new NIfTI +2. Manage if we zip the new NIfTI +3. Load image from NIfTI +4. Flip image +5. Save image to NIfTI
+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
+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.S.masks.WBmask
, which completely
+engulfes pGM, pWM & pCSF
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.
+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.
+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:
+All these masks are masked by a brainmask (pGM+pWM)>0.5
This function performs the following steps:
+Format:
+[ImOut, VisualQC] = xASL_im_M0ErodeSmoothExtrapolate(ImIn, DirOutput, NameOutput, pvGM, pvWM, brainCentralityMap[, LowThreshold])
+
+Description:
+This function erodes, smooths & extrapolates M0 in MNI standard space (tested at 1.5x1.5x1.5mm as used in ExploreASL). +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.
+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(DirOutput,['M0\_im\_proc\_' NameOutput '.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
This function performs the following steps:
+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:
+pGM>0.5
maskNote 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
+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:
+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.
+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.
+Format:
+image_out = xASL_im_NormalizeLabelingTerritories( imageIN, GMmask, x)
+
+Description:
+Normalizes per perfusion territory mask should be GM mask.
+Format:
+[pc, score, eigenvalues, tsquare, loadings, Xmean] = xASL_im_PCA(dataIn)
+
+Description:
+Perform a Principal Component Analysis.
+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
+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).
+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:
+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.
+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
+Format:
+xASL_im_ReplaceLabel(pathNifti, LabelNumbersOld, LabelNumbersNew, pathNewNifti)
+
+Description:
+This function replaces label values/numbers inside a NIfTI +image, by the following steps:
+Format:
+imOutput = xASL_im_ResampleLinear(imInput, newSize)
+
+Description:
+Downsample or upsample an image from its old to a new resolution.
+Format:
+xASL_im_RestoreOrientation(PathNIfTI)
+
+Description:
+This function reverts the NIfTI header orientation matrix +to the original orientation from the scanner/dcm2nii conversion.
+Format:
+xASL_im_SkullStrip(InPath, PathMNIMask, x, OutPath)
+
+Description:
+Creates skull-stripped T1w image based on MNI -> native +space registration from segmentation.
+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.
+Format:
+xASL_im_SplitImageLabels(ImagePaths, LabelTable[, OutputFolder, bOverwrite, ResampleDir, SubRegExp, sessionFolder])
+
+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:
+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.
+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.
+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).
+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.
+Format:
+s = xASL_imp_AppendNiftiParameters(nii_files)
+
+Description:
+Append Nifti Parameters.
+Format:
+[s, FieldNames] = xASL_imp_AppendParmsParameters(parms)
+
+Description:
+Append Parms Parameters.
+Format:
+x = xASL_imp_BasicParameterChecks(x)
+
+Description:
+Basic parameter checks for the import pipeline.
+Format:
+[dcm2niiCatchedErrors] = xASL_imp_CatchErrors(WarningID, WarningMessage, WarningLine, WarningFileName, WarningPath, scan_name, scanpath, destdir, dcm2niiCatchedErrors, imPar, StackIn)
+
+Description:
+Catch reported warnings/errors, print them if verbose, & add them to a structure of warnings/errors to be stored for later QC.
+Format:
+[x] = xASL_imp_CheckDirectoriesAndPermissions(x)
+
+Description:
+Check directories and permissions.
+Format:
+bTimeEncodedFME = xASL_imp_CheckIfFME(jsonIn[, jsonOut, bTimeEncoded])
+
+Description:
+Check if the sequence, based on its JSON structure, is a FME (Fraunhofer Mevis) time encoded sequence.
+Format:
+[x] = xASL_imp_CheckImportSettings(x)
+
+Description:
+Basic import checks before execution of dcm2nii
+Format:
+xASL_imp_CreateSummaryFile(thisSubject, PrintDICOMFields, x)
+
+Description:
+Create summary file.
+For the detailed description of the overview sub-structure (thisSubject & thisVisit) +please check out the description within xASL_imp_DetermineSubjectStructure.
+Format:
+[resultJSON, bTimeEncoded, bTimeEncodedFME] = xASL_imp_DCM2NII_CheckIfFME(nii_files, bTimeEncoded, bTimeEncodedFME)
+
+Description:
+Check if the current sequence is a FME (Fraunhofer Mevis) time encoded sequence.
+Format:
+[x, thisSubject, dcm2niiCatchedErrors, PrintDICOMFields] = xASL_imp_DCM2NII_ConvertScan(x, matches, thisSubject, dcm2niiCatchedErrors, thisVisit, thisRun, scanFields)
+
+Description:
+Run DCM2NII for one individual scan.
+Format:
+xASL_imp_DCM2NII_ReorderTimeEncoded(nii_files, bTimeEncoded, timeEncodedMatrixSize, vectorPLD, resultJSON)
+
+Description:
+Reorder TEs and PLDs accordingly for time encoded sequences.
+Format:
+xASL_imp_DCM2NII_SanityChecks(x, thisSubject, thisVisit)
+
+Description:
+Sanity check for missing elements.
+Format:
+[x, nii_files, summary_line, globalCounts, ASLContext] = xASL_imp_DCM2NII_Subject_SortASLVolumes(x, globalCounts, scanpath, scan_name, nii_files, iSubject, iVisit, iSession, iScan)
+
+Description:
+Sort ASL Volumes.
+Format:
+[globalCounts, x, summary_line, destdir, scanpath, scan_name, dcm2niiCatchedErrors, nii_files, first_match] = xASL_imp_DCM2NII_Subject_StartConversion(globalCounts, x, bSkipThisOne, summary_line, destdir, scanpath, scan_name, dcm2niiCatchedErrors, scanFields)
+
+Description:
+Start of DCM2NII subject conversion.
+Format:
+[parms, pathDcmDict] = xASL_imp_DCM2NII_Subject_StoreJSON(imPar, SavePathJSON, first_match, bUseDCMTK, pathDcmDict)
+
+Description:
+Store JSON.
+Format:
+[x] = xASL_imp_DetermineStructureFromSourcedata(x)
+
+Description:
+Determine structure from sourcedata.
+Format:
+x = xASL_imp_DetermineSubjectStructure(x)
+
+Description:
+Determine subject/session/run structure from sourcedata or temp data.
+The main goal is to create a sub-structure of x called x.importOverview. +x.importOverview does include a separate field for each subject. +Each subject has visit fields and visits have run fields. +All of this is used to track the number of subjects, number of visits, number of runs, +number of scans, etc. reliably. Within later parts of the pipeline it is also possible +to extract the current subject, current visit or current run to determine the part of +a population/subject/visit/run we're working on right now. We mostly used the variables +thisSubject, thisVisit, etc. for that.
+Format:
+imPar = xASL_imp_Initialize(studyPath, imParPath)
+
+Description:
+Initialize DCM2NII.
+Format:
+x = xASL_imp_NII2BIDS_Run(x, bidsPar, studyPar, listRuns, nameSubjectSession, bidsLabel, iRun)
+
+Description:
+NII2BIDS conversion for a single run.
+Format:
+xASL_imp_NII2BIDS_RunAnat(bidsPar, studyPar, subjectSessionLabel, outSessionPath, listRuns, iRun, nameSubjectSession)
+
+Description:
+NII2BIDS conversion for a single sessions, single run.
+Format:
+xASL_imp_NII2BIDS_RunPerf(imPar, bidsPar, studyPar, subjectSessionLabel, inSessionPath, outSessionPath, listRuns, iRun)
+
+Description:
+NII2BIDS conversion for a single sessions, single run.
+Format:
+[jsonLocal, bJsonLocalM0isFile] = xASL_imp_NII2BIDS_Subject_DefineM0Type(studyPar, bidsPar, jsonLocal, pathM0, linkM0prefix)
+
+Description:
+Define M0 Type
+Format:
+x = xASL_imp_PreallocateGlobalCounts(nSubjects, subject, visit)
+
+Description:
+Preallocate space for (global) counts.
+Format:
+x = xASL_imp_ReadSourceData(x)
+
+Description:
+Read source data.
+Format:
+studyParSpecificSubjVisitSess = xASL_imp_StudyParPriority(studyParAll[, subjectName, sessionName, runName, bVerbose])
+
+Description:
+Takes studyPar with possibly several studyPar instances and resolves the priority and saves the individual studyPar. +First studyPar instance has the lowest priority, following ones are more important and review previous variables. +The alias hierarchy within each studyPar instance contains a list of regexp to be matched against subject/session/run. +If subject doesn't exist or regexp doesn't exist or aliasHierarchy doesn't exist, it allows it.
+Format:
+imPar = xASL_imp_TokenBackwardsCompatibility(imPar)
+
+Description:
+Fix the token backwards compatibility.
+Format:
+x = xASL_imp_UpdateDatasetRoot(x)
+
+Description:
+Update x.opts.DatasetRoot to dataset_description.json after NII2BIDS conversion
+Format:
+[x] = xASL_init_BIDS2Legacy(x)
+
+Description:
+Checks the necessary input directories and loads the BIDS directory structure that should be done only once for all subjects and not +for each subject separately
+Format:
+[x] = xASL_init_DataLoading(x)
+
+Description:
+Load dataset by adding relevant fields to xASL x struct.
+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:
+Format:
+[x] = xASL_init_DefineDataDependentSettings(x)
+
+Description:
+Define ExploreASL environment parameters, dependent of loaded data.
+Format:
+[x] = xASL_init_DefineIndependentSettings(x)
+
+Description:
+Define ExploreASL environment parameters, independent of loaded data.
+Format:
+[x] = xASL_init_DefinePaths(x)
+
+Description:
+Define paths used by ExploreASL.
+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:
+Format:
+
+[x] = xASL_init_DetermineRequiredPaths(x)
+
+Description:
+Check the BIDS dataset root for the metadata JSON files.
+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:
+Format:
+x = xASL_init_Import(x)
+
+Description:
+Initialization before xASL_module_Import.
+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:
+Format:
+[bAborted, xOut] = xASL_init_Iteration(x, moduleName[, dryRun, stopAfterErrors])
+
+Description:
+Parses the settings and runs the DatabaseLoop sub-function.
+Format:
+[x] = xASL_init_LoadDataParameterFile(x)
+
+Description:
+Load data parameter file.
+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:
+Format:
+[SubjectNlist, TimePoint, IsSubject, SubjectID_FirstVolume, VolumeList, VolumeN] = 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:
+Format:
+x = xASL_adm_CleanUpX(x)
+
+Description:
+Add maps and atlases.
+Format:
+x = xASL_init_PrintCheckSettings(x)
+
+Description:
+Check whether pre-defined settings existed in dataPar.json
.
Prints these on the screen as the start of the pipeline. +Runs following steps:
+Format:
+xASL_init_PrintUserFeedback(x)
+
+Description:
+Print user feedback.
+Format:
+x = xASL_init_Process(x)
+
+Description:
+Initialization before ExploreASL_Process.
+Format:
+[x] = xASL_init_RemoveLockDirs(x)
+
+Description:
+Remove 'lock-dir' if present from aborted previous run, for current subjects only.
+Format:
+[x] = xASL_init_SubStructs(x)
+
+Description:
+Initialize the ExploreASL x structure substructs/fields. +Only fields which do not exist so far are added. +This script is supposed to help with the overall modularity of ExploreASL. +This script is identical to the function ExploreASL_Initialize_SubStructs within +ExploreASL_Initialize. We can not call this script from ExploreASL_Initialize, +since the paths are not initialized at that part of the script yet.
+Format:
+x = xASL_init_Toolboxes(x)
+
+Description:
+Check & load ancillary toolboxes, versions and paths.
+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.
+Format:
+
+[x] = xASL_init_checkDatasetRoot(x)
+
+Description:
+Check the ExploreASL parameter "DatasetRoot".
+Format:
+xASL_init_printSettings(x)
+
+Description:
+Print chosen settings.
+Format:
+x = xASL_io_CheckDeprecatedFieldsX(x[, bVerbose])
+
+Description:
+Check deprecated fields of x and fix them based on a conversion table. +This table is used within:
+It is not only used to convert deprecated x structure +fields to fields within up-to-date substructures of x, but +also to rename fields and to move them back and forwards +for the comparison with BIDS parameters within +xASL_bids_parms2BIDS e.g., which is why it is important to +make sure that if a row within the table is used to move & +rename, that there is also another row where the new +fieldname is moved to the same substructure.
+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:
+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.
+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).
+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:
+Format:
+xASL_io_MergeTextFiles(pathA,pathB,pathOut[,headerText])
+
+Description:
+Merge text files A and B and write the output to the pathOut file.
+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).
+Format:
+[x] = xASL_io_ReadDataPar(pathDataPar[, bStudyPar])
+
+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.
+Format:
+json = xASL_io_ReadJson(pathJSON)
+
+Description:
+This function reads a JSON file located at the given path and decodes it using the Matlab built-in function JSONDECODE. The output is a Matlab +structure with the decoded JSON content.
+Format:
+textArray = xASL_io_ReadTextFileLineByLine(pathTextFile)
+
+Description:
+Read a text file line by line.
+Format:
+[Info] = xASL_io_ReadTheDicom(bUseDCMTK, DicomPath)
+
+Description:
+This function tries to read a DICOM and throws a warning if it fails to
+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. +If cbf images are included and there is a single other image like deltaM or control or label, then +cbf image is excluded as a dummy.
+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;
+Format:
+xASL_io_WriteJson(pathJSON, json[, bOverwrite])
+
+Description:
+This function writes a Matlab structure into a JSON file located at the given path encoding it using the Matlab function +JSONENCODE.
+Format:
+[niifiles, ScanNameOut, usedinput, msg] = xASL_io_dcm2nii(inpath, destdir, series_name, imPar, myPath)
+
+Description:
+Convert DICOM NIfTI/BIDS format using the dcm2nii command line utility.
+Format:
+[x] = xASL_qc_AddLoggingInfo(x, loggingEntry)
+
+Description:
+Logging of errors and warnings within the x structure.
+Format:
+[AI_perc] = xASL_qc_AsymmetryIndex(ImageIn)
+
+Description:
+Extract voxel-wise asymmetry index for QC purposes.
+Format:
+[QA_Output] = xASL_qc_CAT12_IQR(InputImage, InputC1, InputC2, InputC3, bFLAIR)
+
+Description:
+Prepare and run CAT12s QC parameters (also for other images).
+Format:
+[IsValid] = xASL_qc_CheckValidityJSON(PathJSON)
+
+Description:
+This function loads a QC JSON (simply JSON file, won't +take any exotic files) and simply check whether there is any empty value +after a key. If this is the case, it will throw a warning, which will skip +reading this JSON by the xASL_io_ReadJson, avoiding the crash that +this may result in.
+Format:
+x = xASL_qc_CollectParameters(x, iSubject, ScanType, CollectQCFunction)
+
+Description:
+This function collects QC parameters for a module.
+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
+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
+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
+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.
+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
+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
+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.
+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
+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.
+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.
+Format:
+[anatQA] = xASL_qc_PCPStructural(PathT1, Pathc1T1, Pathc2T1, x, PopPathT1)
+
+Description:
+This function computes several anatomical QC parameters as proposed in SPM Univariate Plus:
+REFERENCES: +Preprocessed Connectome Project Quality Assurance Protocol (QAP): +http://preprocessed-connectomes-project.org/quality-assessment-protocol/ +http://ieeexplore.ieee.org/document/650886/
+Format:
+xASL_qc_PrintOrientation(niftiList, outputDir, outputFile);
+
+Description:
+This function lists NifTI orientation matrices before and after +image processing, respectively nii.mat0 and nii.mat. In ExploreASL this +is used for QC to detect accidental left-right flips, as these can occur +unnoticed as the brain structure appears relatively symmetrical. +This can be detected by negative determinants. +Also, this can be used to detect any significant differences in +acquisition or image processing.
+So orientation parameters and determinants should be similar across +all scans from single scanner/coil, and registration should not +give a relatively negative determinant. +Results are saved in a TSV file
+This functions performs the following steps: +1. Print the header +2. Load the data +3. Print original orientation matrix +4. Print current orientation matrix +5. Print registration transformation matrix +6. Print FileName +7. Get statistics (mean & SD)
+Format:
+xASL_qc_ReportLeftRightFlips(dirRoot [, bZip])
+
+Description:
+This function identifies and reports illegal left-right +flips for image matrices within a NIfTI. This can be useful as these are +not readily observed by the human eye, as the left and right hemispheres +are too symmetrical by default.
+All NifTIs are found recursively (i.e. in the folder and its subfolders), +irregardless of them being .nii or .nii.gz.
+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.
+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:
+Format:
+xASL_qc_WADQC_GenerateDescriptor(x, iSubject)
+
+Description:
+This QC function generates a JSON descriptor for Gaspare' +QCDC script, by the following steps:
+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:
+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/
+Format:
+[ScaleImage[, CBF, ATT, ABV, Tex]] = xASL_quant_ASL(PWI, M0_im, imSliceNumber, x[, bUseBasilQuantification])
+
+Description:
+This script performs a multi-step quantification, by +initializing a ScaleImage that travels through this script & gets changed by the following quantification +factors:
+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)
+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:
+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.
+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:
+Format:
+[CBF_nocalib, ATT_map, ABV_map, Tex_map, resultFSL] = xASL_quant_FSL(PWI, x)
+
+Description:
+This script performs quantification of the PWI using the FSL Basil/Fabber pipeline. Final calibration to +physiological units is performed by dividing the quantified PWI by the M0 image/value. +Fabber is used instead of Basil for multiTE data.
+This function performs the following steps:
+Format:
+[ControlIm, LabelIm, OrderContLabl] = xASL_quant_GetControlLabelOrder(ASLTimeSeries)
+
+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. Works also for multiPLD but only for sequences +with alternative control/label or label/control order
+Format:
+imMeanControl = xASL_quant_GetMeanControl(x, imASLTimeSeries)
+
+Description:
+This function calculates the mean control image. It automatically checks (and corrects if required) +the control order of ASL timeseries and takes into account if multiPLD or Hadamard data are provided
+Format:
+[imDecoded] = xASL_quant_HadamardDecoding(imPath, xQ)
+
+Description:
+Hadamard-4 & Hadamard-8 Decoding.
+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:
+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:
+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.Q.readoutDim, 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.
+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
+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:
+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).
+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
+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.
+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:
+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:
+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.
+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.
+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
+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.
+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)).
+Format:
+mssim=xASL_stat_MeanSSIM(imRef,imSrc[,dynRange])
+
+Description:
+Calculates the similarity index according to Want et al.
+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.
+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.
+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
+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:
+Format:
+y = xASL_stat_QuantileNan(x[,quant, dim])
+
+Description:
+Calculates a quantile, but ignoring NaNs in the calculation
+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
+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).
+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.
+Format:
+y = xASL_stat_SumNan(x[,dim])
+
+Description:
+It uses the function SUM, but it sets all the NaNs to zero before calling it.
+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:
+PM: Allow entering one group only +PM: could extend with xASL_qc_TanimotoCoeff
+Format:
+y = xASL_stat_VarNan(x[,w,dim])
+
+Description:
+It behaves in a similar way as VAR.
+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.
+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.
+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.
+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.
+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.
+Format:
+[x] = xASL_vis_AddIM2QC(x,parms);
+
+Description:
+Checks which images already are loaded, and adds new image.
+Format:
+[ImOut, FileName] = xASL_vis_CreateVisualFig(x, ImIn[, DirOut, IntScale, NamePrefix, ColorMap, bClip, MaskIn, bWhite, MaxWindow, bTransparancy, bVerbose, bContour])
+
+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:
+This function assumes that the first image is a grayscale background +image (e.g. for transparancy reasons), if there are multiple +images
+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.
+Format:
+ImageOut = xASL_vis_CropParmsApply(ImageIn,CropParameters)
+
+Description:
+This function crops 2D image matrices.
+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.
+Format:
+xASL_vis_OverlapT1_ASL( x, ASL)
+
+Description:
+Part of ExploreASL. +Shows spatial agreement ASL and probability maps.
+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
+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.
+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.
+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.
+ + + + + + +Format:
+x = xASL_wrp_DCM2NII(x)
+
+Description:
+Run the dcm2nii part of the import.
+Format:
+[x, PrintDICOMFields, dcm2niiCatchedErrors] = xASL_wrp_DCM2NII_Subject(x, matches, dcm2niiCatchedErrors)
+
+Description:
+Run DCM2NII for one individual subject.
+Format:
+xASL_wrp_Deface(x)
+
+Description:
+Run defacing.
+xASL\_spm\_deface
)Format:
+x = xASL_wrp_NII2BIDS(x)
+
+Description:
+Run the NII2BIDS conversion.
+Format:
+x = xASL_wrp_NII2BIDS_Subject(x, bidsPar, studyParAll, nameSubjectSession)
+
+Description:
+Run NII to ASL-BIDS for one individual subject.
+The ExploreASL Software is distributed under the license described below, designed +to encourage collabortion while at the same time aiming to reuse commercial profit for academical purpose (e.g. hire an ExploreASL developer). All contents, except for those in the folder //External, are proprietary of ExploreASL. The content in the folder //External is not subject to this license.
+Provisionary license ExploreASL. This license will be renewed soon after legal checks. +ExploreASL, Release 0.999 (c) 2020, Amsterdam University Medical Center (the "Software") +The Software remains the property of Amsterdam University Medical Center (AUMC, "the University").
+The Software is distributed "AS IS" under this License solely for +non-commercial use in the hope that it will be useful, but in order +that the University as a charitable foundation protects its assets for +the benefit of its educational and research purposes, the University +makes clear that no condition is made or to be implied, nor is any +warranty given or to be implied, as to the accuracy of the Software, +or that it will be suitable for any particular purpose or for use +under any specific conditions. Furthermore, the University disclaims +all responsibility for the use which is made of the Software. It +further disclaims any liability for the outcomes arising from using +the Software.
+The Licensee agrees to indemnify the University and hold the +University harmless from and against any and all claims, damages and +liabilities asserted by third parties (including claims for +negligence) which arise directly or indirectly from the use of the +Software or the sale of any products based on the Software.
+No part of the Software may be reproduced, modified, transmitted or +transferred in any form or by any means, electronic or mechanical, +without the express permission of the University. The permission of +the University is not required if the said reproduction, modification, +transmission or transference is done without financial return, the +conditions of this License are imposed upon the receiver of the +product, and all original and amended source code is included in any +transmitted product. You may be held legally responsible for any +copyright infringement that is caused or encouraged by your failure to +abide by these terms and conditions.
+You are not permitted under this License to use this Software +commercially. Use for which any financial return is received shall be +defined as commercial use, and includes (1) integration of all or part +of the source code or the Software into a product for sale or license +by or on behalf of Licensee to third parties or (2) use of the +Software or any derivative of it for research with the final aim of +developing software products for sale or license to a third party or +(3) use of the Software or any derivative of it for research with the +final aim of developing non-software products for sale or license to a +third party, or (4) use of the Software to provide any service to an +external organization for which payment is received. If you are +interested in collaborating or contributing to this Software, please +contact Henk Mutsaerts (h.j.mutsaerts@amsterdamumc.nl). If you are +interested in using this Software commercially, please contact +Innovation Exchange Amsterdam ("IXA"), the technology transfer company +of the University, to negotiate a license.
+ + + + + + +Format:
+[result, x] = xASL_module_Import(x)
+
+Description:
+Import batch T1
, T2
, FLAIR
, DWI
, fMRI
, M0
, ASL
data from dicom 2 NIfTI in ASL-BIDS format and structure.
+Uses dcm2niiX for the conversion, and additionally collects important DICOM header data
+and puts them in .json
sidecars to be used with the ExploreASL pipeline.
+This function takes any folder input, but the folder input should be
+specified in the x.modules.import.imPar definition. Follow the steps below, for study "MyStudy"
located on "//MyDisk"
:
//MyDisk/MyStudy
+sourcedata folder containing DICOMs: //MyDisk/MyStudy/sourcedata
//MyDisk/MyStudy/sourcedata
, set up the folderstructure in
+ExploreASL_ImportConfig.m. This setup uses the SPM form of regular
+expressions, which can be daunting at first, but are very flexible.
+Easiest is to study other examples, before creating your own.
+For this example, let's say we have //MyDisk/MyStudy/sourcedata/ScanType/SubjectName
+because we downloaded our data from XNAT, ordered per ScanType first,
+and then per subject.BRIEF EXPLANATION:
+Let's suppose we don't have sessions (only a single structural and functional scan per subject)
+The names of our scans comes out of XNAT as '3D\_FLAIR\_eyesClosed'
, 'T1w\_MPRAGE'
and 'PCASL\_10\_min'
+and the subject names are 'MyStudy001'
.. 'MyStudy002'
.. etc.
+imPar is now contained inside x.modules.import.imPar
()
tell the script that this is a token (i.e. subject, session, ScanType)
+Examples:
+imPar.folderHierarchy = {'^(3D\_FLAIR|T1w|PCASL).*', '^(Sub-\d{3})$'};
+here we say that there are two folder layers '', separated by comma ,
+where the names between brackets are used to define what is what.
+^
means that the foldername has to start with the following, $ means that the previous has to be the end of the foldername
+.\*
means anything, anylength, \d{3}
means three digits()
in imPar.folderHierarchy: position 1==subject
, 2==visit
, 3==session
, 4==ScanType
+Examples:
+imPar.tokenOrdering = [2 3 0 1];
stating that subject is the 2nd token, visit is the 3rd token, session has no token (i.e. no session) and ScanType is the 1st tokenimPar.tokenVisitAliases = {'Screening','\_1'; 'Month\_12','\_2'; 'Month\_24','\_3'; 'Month\_36','\_4'; 'Month\_48','\_5'};
+Note that if you specify tokenVisitAliases, the folders will receive
+the indices (e.g. \_1 \_2 \_3
), or even \_1
only with a single Visit). If you don't specify
+them, they will not get this postfix.'T1'
'FLAIR'
'ASL4D'
'M0'
'ASL4D\_RevPE'
'func'
'func\_NormPE'
'func\_RevPE'
'dwi'
'dwi\_RevPE'
'DSC4D'
+Examples:
+imPar.tokenScanAliases = {'^3D\_FLAIR$', 'FLAIR'; '^T1w$', 'T1'; '^PCASL$', 'ASL4D'};
imPar.tokenSessionAliases = {}; % as we don't have sessions
Any (X|Y|Z) expression is referred to as a "captured group" +All captured groups defined in tokenOrdering, scanAliases, visitAliases, and sessionAliases are "tokens" +While it is simplest if all captured groups in folderHierarchy represent tokens (for the user and bugfixing), this is not required
+Format:
+[result, x] = xASL_module_Structural(x)
+
+Description:
+This first ExploreASL module processes the structural +images, i.e. high-resolution T1w and FLAIR (if present), on an individual (i.e. subject-to-subject) basis. +If a FLAIR is present, this is processed first to obtain a WMH mask to fill the hypointense lesions on the T1w, +before segmenting the T1w. For the T1w segmentation this module uses CAT12 +by default but if this fails it falls back to SPM after trying to +optimize the image contrast. This module has the following steps/submodules/wrappers:
+010\_LinearReg\_T1w2MNI
- Ensure the alignment of subjects' anterior commissure (AC) with the AC in MNI & apply this to all images020\_LinearReg\_FLAIR2T1w
- Align the FLAIR (if present) with T1w030\_FLAIR\_BiasfieldCorrection
- Perform a biasfield correction (if not performed by LST in following steps)040\_LST\_Segment\_FLAIR\_WMH
- Segment WMH lesions on FLAIR (if present)050\_LST\_T1w\_LesionFilling\_WMH
- Use WMH segmentation to fill lesions on T1w060\_Segment\_T1w
- Tissue segmentation on T1w070\_CleanUpWMH\_SEGM
- Extra WMH cleanup of some over- and under-segmentation080\_Resample2StandardSpace
- Clone all images to standard space090\_GetVolumetrics
- Obtain whole-brain volumes of GM, WM, CSF, WMH100\_VisualQC
- Obtain QC parameters & save QC Figures110\_DoWADQCDC
- QC for WAD-QC DICOM server (OPTIONAL)Format:
+[result, x] = xASL_module_ASL(x)
+
+Description:
+This ExploreASL module processes the ASL +images, i.e. ASL4D, M0, etc (if present), on an individual (i.e. session-to-session, where session indicates BIDS "run") basis. +Both 2D and 3D options are automatially chosen, as well as processing of time-series (if available), such as motion correction and outlier +exclusion. This module has the following submodules/wrappers:
+010\_TopUpASL
- FSL TopUp geometric distortion correction (if M0 images with reversed phase-encoding are present)020\_RealignASL
- If time-series are present, motion correction and outlier exclusion (ENABLE)030\_RegisterASL
- Registration of ASL to T1w anatomical images (if lacking, to MNI images)040\_ResampleASL
- Resample ASL images to standard space050\_PreparePV
- Create partial volume images in ASL space with ASL resolution060\_ProcessM0
- M0 image processing070\_CreateAnalysisMask
- Create mask using FoV, vascular outliers & susceptibility atlas080\_Quantification
- CBF quantification090\_VisualQC\_ASL
- Generate QC parameters & images100\_WADQC
- QC for WAD-QC DICOM server (OPTIONAL)This module performs the following initialization/admin steps:
+C. Cleanup before rerunning
+D - ASL processing parameters
+D5. Multi-TE parsing
+E - ASL quantification parameters
+Format:
+[result, x] = xASL_module_Population(x)
+
+Description:
+This ExploreASL module processes all available images on the +group level. It assumes that all images were adequately processed in the +previous modules. It will perform the following group-wise processing and +checks:
+010\_CreatePopulationTemplates
- Create population average images, to compare scanners, cohorts etc without physiological variance020\_CreateAnalysisMask
- Generate a group-level mask by combining individuals masks, for ROI-based analysis & VBA030\_CreateBiasfield
- When there are multiple scanners, create scanner-specific biasfields (uses Site.mat for this)040\_GetDICOMStatistics
- Create TSV file with overview of DICOM parameters050\_GetVolumeStatistics
- Create TSV file with overview of volumetric parameters060\_GetMotionStatistics
- Create TSV file with overview of motion parameters065\_GetRegistrationStatistics
- Create TSV file with overview of the registration statistics070\_GetROIstatistics
- Create TSV file with overview of regional values (e.g. qCBF, mean control, pGM etc)080\_SortBySpatialCoV
- Sort ASL_Check QC images by their spatial CoV in quality bins090\_DeleteTempFiles
- Delete temporary files100\_GZipAllFiles
- Zip files to reduce disc space usage of temporary and non-temporay NIfTI filesFormat:
+xASL_adm_DeleteManyTempFiles(x)
+
+Description:
+This function removes as many files as possible.
+Format:
+[nSessions, bSessionsMissing] = xASL_adm_GetPopulationSessions(x)
+
+Description:
+This function looks for the maximum amount of sessions that +are present in selected processed files present in the Population folder.
+Format:
+xASL_adm_GzipAllFiles(ROOT, bFolder, bUseLinux, pathExternal)
+
+Description:
+This function zips NIfTI files or folders recursively and deletes +the original file/folder after zipping.
+Format:
+[x] = xASL_im_CreateAnalysisMask(x, Threshold)
+
+Description:
+This function takes the mean population-based probability +maps of masks, thresholds and combines them:
+A. Creation GM, WM & WholeBrain masks by p>0.5 +B. Create, combine & save vascular, susceptibity & FoV +masks: +- MaskVascular +- MaskSusceptibility = MaskSusceptibility & MaskFoV +C. Create & save VBA mask +- MaskAnalysis = MaskVascular & MaskSusceptibility +- x.S.VBAmask = MaskAnalysis & GMmask +D. Visualization: Creates a figure with columns being +following maps/masks overlaid over mean population T1w: +1. FoV probability 0-50% missing voxels +2. Vascular 0-7.5% missing voxels +3. Susceptibility 0-50% missing voxels +4. Analysis mask
+Format:
+xASL_qc_SortBySpatialCoV(x, Threshold1, Threshold2)
+
+Description:
+This function organizes the ASL QC images in //analysis/Population/ASLCheck +into CBF, vascular and artifactual contrast per the +spatial CoV thresholds defined above, in folders: +//analysis/Population/ASLCheck/1_CBFContrast +//analysis/Population/ASLCheck/2_VascularContrast +//analysis/Population/ASLCheck/3_ArtifactualContrast +Invalid spatial CoV numbers (e.g. NaN) will go to: +//analysis/Population/ASLCheck/4_Unknown_sCoV +Note: these outputs need to be visually checked; but +pre-sorting them by spatial CoV puts them already in +categories that are quick to skim through and manually +correct by moving the images
+The idea is then that only category 1 images are used +for perfusion (CBF) analyses, both categories 1 & 2 for the +vascular (sCoV) analyses, and the category 3 images excluded +from analysis.
+PM: this code does not include multiple sessions per subject yet! +NB: this code uses the //analysis/Population/Stats/CoV_qCBF*TotalGM*.csv file, +make sure that this file isn't edited!
+Format:
+xASL_stat_ComputeWsCV(x)
+
+Description:
+Calculates the within and between-subject +coefficient of variance (wsCV and bsCV respectively), to estimate the +power to detect effects.
+This requires 4D images that have been split.
+Format:
+[x] = xASL_stat_GetAcquisitionTime(x)
+
+Description:
+This functions collects the DICOM field AcquisitionTime from +each json sidecar (& parms.mat for backward compatibility) and saves them +in the participants.tsv. Additionally, it creates a AcquisitionTime histogram of the +full study, which can be useful to check time of scanning -> can +influence physiological CBF variability.
+Format:
+xASL_stat_GetDICOMStatistics(x, ScanType, HasSessions)
+
+Description:
+This functions prints DICOM metadata (e.g. parameters used +for quantification) and collects them in a single tsv (per BIDS). +Summarizes this for the total population. +Can be useful to detect software upgrades, where only slight +parameter changes can hint on quantification changes. +This function carries out the following steps:
+Format:
+xASL_stat_GetMotionStatistics(x)
+
+Description:
+This functions collects motion stats, with the following steps:
+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:
+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
+Format:
+xASL_stat_GetRegistrationStatistics(x)
+
+Description:
+Loads the data from the study given in the QC_collection*.json files. Goes through all subjects and +sessions and prints the Tanimoto coefficients that define the quality of the registrations. Steps:
+Format:
+xASL_stat_GetVolumeStatistics(x)
+
+Description:
+This functions collects motion stats, with the following. Steps:
+Format:
+xASL_wrp_CreateBiasfield(x)
+
+Description:
+This function creates a smooth biasfield as intensity map to +normalize intensities between different +sequences/scanner/sites within a single study. +This is a simple pragmatic approach and is not validated, +but is the best we can do.
+First acquires average additive & multiplicative factors for total GM, +then does a smooth voxel-wise rescaling. This doesn't make an assumption +whether site or sequence differences are additive or multiplicative, +but rather fits them both. Global scaling it performed to GM CBF == 60 mL/100g/min
+NB: make sure that sequence resolution differences have been +taken in account before creating these biasfields +PM: add normalization of between-subjects SD as well. +PM: are there other things we can normalize?
+Note that NaNs in the images are ignored (so for each voxel +only the subjects without a NaN in the voxel are considered)
+This function has the following sections:
+Format:
+xASL_wrp_CreatePopulationTemplates(x[, bSaveUnmasked, Compute4Sets, SpecificScantype, bSkipWhenMissingScans, bRemoveOutliers, FunctionsAre])
+
+Description:
+This function creates simple parametric images, a.k.a. templates, for +different image/scan types, on population level, as well as for different +sets (e.g. sites/scanners/cohorts, etc) if specified. By default these +images are masked, and transformed into a single column, for quick +computations with low memory usage. The default parametric images that +are created are the mean, between-subject SD, and the maximal intensity +projection (MIP). The latter can e.g. identify intra-vascular signal that +is similar between different subjects. Other parametric maps can be +decommented (now commented out for speed).
+Any new addition to participants.tsv will be recognized and loaded, for +the generation of new parametric maps for groups specifically +(needs to be set in input argument bCompute4Sets)
+If a set only includes a combination of the following SetOptions: +left, right, l, r, n/a, NaN (irrespective of capitals) +each image with option right/r, will be flipped in the left-right +direction, and left/right will not be treated as separate groups. +This function performs the following steps:
+Format:
+xASL_wrp_GetROIstatistics(x)
+
+Description:
+This wrapper organizes the computation of statistics for different ROIs +in a [1.5 1.5 1.5] mm MNI space:
+This document describes the ExploreASL internal x-structure that contains processing settings and also sequence parameters. Normally, you do not have to modifies the processing paramaters and the default values are recommended for most studies. Also, you do not have to insert of modify the sequence parameters as these are normally all obtained from the JSON-files for data saved in ASL-BIDS. However, you can change both the processing settings and sequence parameters by providing them in a dataPar.json
file in the ROOT\derivatives\ExploreASL\dataPar.json
. Alternatively, you can provide the file at ROOT\dataPar.json
during the import and it will be automatically copied to the ROOT\derivatives\ExploreASL\dataPar.json
location. Note that for missing parameters, default will be used. Provided sequence parameters will be ignored if they will be already contained in individual subject's JSON sidecars, and will only be considered when missing for each particular subject.
Below, we list all useful parameters that can be set by users for both basic and advanced processing. See a full list of parameters in Developer Tutorial. Note that the parameters are grouped to several groups by their function - do not forget to add the full hierarchy when creating the DataPar.json
- see the example at the end of this page. Note that the tables below use Matlab notation and the example file is in JSON notation
Within x.external
you can find parameters related to external tools and the coding environment.
x.external.[...] |
+Description | +Defaults | +
---|---|---|
bAutomaticallyDetectFSL |
+Boolean to automatically detect the FSL version if disabled, this function will try to use the system-initialized FSL and throw an error if FSL is not initialized. | +OPTIONAL, DEFAULT = false | +
Basic information about the session names within a study.
+x.[...] |
+Description | +Defaults | +
---|---|---|
SESSIONS |
+Use this to define sessions. Example ('.json' file): ["ASL_1","ASL_2"] |
+OPTIONAL, DEFAULT = {'ASL_1'} |
+
session.options |
+This is how the sessions will be called, example: {'baseline' 'drug'} . For FEAST, this should be {'crushed' 'non-crushed'} . |
+OPTIONAL | +
Dataset related parameters can be found in this subfield.
+x.dataset.[...] |
+Description | +Defaults | +
---|---|---|
subjectRegexp |
+String with regular expression for ExploreASL to find subjects by foldername, example: ^\d{3}$ for three digits |
+REQUIRED | +
exclusion |
+Cell with list of subjects to exclude, example: {'005' '018'} |
+OPTIONAL, DEFAULT = empty | +
ForceInclusionList |
+Use this field if you want to use a selection of subjects rather than taking all available subjects from directories. Example: load(fullfile(x.D.ROOT,'LongitudinalList.mat') ). |
+OPTIONAL, DEFAULT = use all subjects | +
Parameters to define M0-processing choices and also extra information about M0-scan position within the ASL series if not specified in the ASLcontext.tsv already. Note that these parameters can be added either to the general dataPar.json
but also to the ASL4D.json
of each subject to affect the processing of this subject only.
x.modules.asl.[...] |
+Description | +Defaults | +
---|---|---|
M0_conventionalProcessing |
+Boolean - use the conventional M0 processing (per consensus paper), options: 1 = standard processing, 0 = new image processing (improved masking & smoothing). | +OPTIONAL, DEFAULT = 0 | +
M0_GMScaleFactor |
+Add additional scale factor to multiply the M0 image by This can be useful when you have background suppression but no control/M0 image without background suppression. If you then know the M0 scalefactor for the GM, you can use the control image as M0 and use this parameter to scale back what was suppressed by background suppression. Note that there is no option for separate tissue scaling (e.g. WM & GM), because ExploreASL pragmatically smooths the M0 a lot, assuming that head motion and registration between M0 & ASL4D will differ between patients and controls. | +OPTIONAL, default = 1 | +
M0PositionInASL4D |
+A vector of integers that indicates the position of M0 in TimeSeries, if it is integrated by the Vendor in the DICOM export. Will move this from ASL4D.nii to M0.nii Note that the x.modules.asl.M0PositionInASL4D parameter is independent from the x.Q.M0 parameter choice. Example for Philips 3D GRASE = '[1 2]' (first control-label pair). Example for Siemens 3D GRASE = 1 first image. Example for GE 3D spiral = 2 where first image is PWI & last = M0. Empty vector should be given (= [] or = null (in JSON)) if no action is to be taken and nothing is removed. | +OPTIONAL, DEFAULT = [] (no M0 in timeseries) |
+
DummyScanPositionInASL4D |
+A vector of integers that indicates the position of Dummy scans in TimeSeries if they are integrated by the Vendor in the DICOM export. This allows to remove the dummy scans or noise scans that are part of the Timeseries. A new ASL4D.nii is saved with dummy scans removed and the original is backed-up. Works in a similar way as M0PositionInASL4D, both can be entered at the same time and both indicate the original position in the Timeseries independend of each other. Example for Siemens 2D EPI = [79 80] Skip the control-label pair used for noise measurements. Example for certain Siemens 3D GRASE = 2 Skip the first dummy control image. Empty vector should be given (= [] or = null (in JSON)) if no action is to be taken and nothing is removed. |
+OPTIONAL, DEFAULT = [] (no M0 in timeseries) |
+
Please use these fields to modify the quantification model parameters for the entire study. Note that normally, the default values are used for each field-strength and these values do not have to be provided. Note that these parameters can be added either to the general dataPar.json
but also to the ASL4D.json
of each subject to affect the processing of this subject only.
x.Q.[...] |
+Description | +Defaults | +
---|---|---|
bUseBasilQuantification |
+True for using BASIL quantification in addition to ExploreASL's quantification. | ++ |
BASIL.bMasking |
+For for BASIL/FABBER to quantify only over a mask provided by ExploreASL | +OPTIONAL, DEFAULT = true | +
BASIL.bSpatial |
+True for BASIL to use automated spatial smoothing | +OPTIONAL, DEFAULT = false | +
BASIL.bInferT1 |
+True for BASIL to infer variable T1 values | +OPTIONAL, DEFAULT = false | +
BASIL.bInferATT |
+True for BASIL to infer arterial component and quantify ATT | +OPTIONAL, DEFAULT = true | +
BASIL.Exch |
+True for BASIL to model of the exchange of labeled water in the capilliary bed . Options : mix = Well-mixed single compartment, simple = Simple single compartment of T1 of blood, 2cpt = A two compartment exchange model following Parkes & Tofts, spa = Single pass approximation from St. Lawrence | +OPTIONAL, DEFAULT = simple | +
BASIL.Disp |
+True for BASIL to model label dispersion. Options : none = No dispersion, gamma = Gamma dispersion kernal (vascular transport function), gauss = Temporal gaussian dispersion kernal, sgauss = Spatial gaussian dispersion kernal | +OPTIONAL, DEFAULT = none | +
BASIL.ATTSD |
+Set parameter standard deviation of ATT for BASIL fitting | +OPTIONAL, DEFAULT = 1.0 | +
BASIL.bCleanUp |
+Delete temporary files creates for FSL quantification | +OPTIONAL, DEFAULT = true | +
Lambda |
+Brain/blood water coefficient (mL 1H/ mL blood). Example: 0.32 (for GSP phantom). |
+OPTIONAL, DEFAULT = 0.9 | +
T2art |
+T2* of arterial blood, only used when no M0 image (ms). |
+OPTIONAL, DEFAULT = 50 @ 3T | +
BloodT1 |
+T1 relaxation time of arterial blood (ms). Defaults (Alsop MRM 2014), 1800 for GSP phantom. | +OPTIONAL, DEFAULT = 1650 @ 3T | +
TissueT1 |
+T1 relaxation time of GM tissue (ms). Defaults (Alsop MRM 2014). | +OPTIONAL, DEFAULT=1240 @ 3T | +
nCompartments |
+Number of modeled compartments for quantification. Options: 1 = a single-compartment quantification model (default by concensus paper), 2 = a dual-compartment quantification model. | +OPTIONAL, DEFAULT = 1) | +
SaveCBF4D |
+Boolean, true to also save 4D CBF timeseries, if ASL4D had timeseries. | +OPTIONAL, DEFAULT=false | +
All ASL module related parameters are stored within this subfield. Use these for extra ASL-processing options or to turn OFF/ON certain steps. Note that these parameters can be added either to the general dataPar.json
but also to the ASL4D.json
of each subject to affect the processing of this subject only.
x.modules.asl.[...] |
+Description | +Defaults | +
---|---|---|
motionCorrection |
+Boolean to perform motion correction in case of timeseries. Options: 1 = on, 0 = off. |
+OPTIONAL, DEFAULT = 1 | +
SpikeRemovalThreshold |
+Minimal t-stat improval needed to remove motion spikes. Examples: 1 = effectively disabling spike removal. |
+OPTIONAL, DEFAULT = 0.01 | +
SpikeRemovalAbsoluteThreshold |
+Motion threshold in mm for removing motion spike volumes. Examples: 0.05 , 0 = disabling spike removal. |
+OPTIONAL, DEFAULT = 0 | +
bRegistrationContrast |
+Specifies the image contrast used for registration: 0 = Control->T1w, 1 = CBF->pseudoCBF from template/pGM+pWM (skip if sCoV>0.667), 2 = automatic (mix of both), 3 = option 2 & force CBF->pseudoCBF irrespective of sCoV. |
+OPTIONAL, DEFAULT = 2 | +
bAffineRegistration |
+Specifies if the ASL-T1w rigid-body registration is followed up by an affine registration: 0 = affine registration disabled, 1 = affine registration enabled, 2 = affine registration automatically chosen based on spatial CoV of PWI. |
+OPTIONAL, DEFAULT = 0 | +
bDCTRegistration |
+Specifies if to include the DCT registration on top of Affine, all other requirements for affine are thus also taken into account the x.modules.asl.bAffineRegistration must be >0 for DCT to run: 0 = DCT registration disabled 1 = DCT registration enabled if affine enabled and conditions for affine passed, 2 = DCT enabled as above, but use PVC on top of it to get the local intensity scaling right. |
+OPTIONAL, DEFAULT = 0 | +
bRegisterM02ASL |
+Boolean specifying whether M0 is registered to mean_control image (or T1w if no control image exists). It can be useful to disable M0 registration if the ASL registration is done based on the M0, and little motion is expected between the M0 and ASL acquisition. If no separate M0 image is available, this parameter will have no effect. This option is disabled automatically for 3D spiral: 0 = M0 registration disabled, 1 = M0 registration enabled (DEFAULT). |
+OPTIONAL, DEFAULT = 0 | +
bUseMNIasDummyStructural |
+When structural (e.g. T1w) data is missing, copy population-average MNI templates as dummy structural templates. With this option, the ASL module copies the structural templates to fool the pipeline, resulting in ASL registration to these templates. While the rigid-body parameters might still be found somewhat correctly, with this option it is advised to enable affine registration for ASL as well, since ASL and these dummy structural images will differ geometrically. When disabled, an error will be issued instead when the structural image are missing. 1 = enabled, 0 = disabled. |
+OPTIONAL, DEFAULT = 0 | +
bPVCNativeSpace |
+Performs partial volume correction (PVC) in ASL native space using the GM and WM maps obtained from previously segmented T1-weighted images. Skipped with warning when those maps do not exist and are not resampled to the ASL space. PVC can take several minutes for larger scans (e.g. 128x128x30), so it is deactivated by default. 1 = enabled, 0 = disabled. |
+OPTIONAL, DEFAULT = 0 | +
PVCNativeSpaceKernel |
+Kernel size for the ASL native space PVC. This is ignored when x.modules.asl.bPVCNativeSpace is set to 0. Equal weighting of all voxels within the kernel is assumed. 3D kernel can be used, but any of the dimension can be also set to 1. Only odd number of voxels can be used in each dimension (e.g. [3 7 5] not [2 3 1] ). |
+OPTIONAL, DEFAULT = [5 5 1] for bPVCGaussianMM==0, [10 10 4] for bPVCGaussianMM==1 |
+
bPVCGaussianMM |
+If set to 1, PV-correction with a Gaussian weighting is used instead of the equal weights of all voxels in the kernel ('flat' kernel) as per Asllani's original method. Ignored when x.modules.asl.bPVCNativeSpace is set to 0. Unlike with the flat kernel when the size is defined in voxels, here the FWHM of the Gaussian in mm is defined in each dimension. The advantage is twofold - continuous values can be added and a single value can be entered which is valid for datasets with different voxel-sizes without having a kernel of different effective size.1 = enabled, use Gaussian kernel with FWHM in mm given in PVCNativeSpaceKernel, 0 = disabled, use 'flat' kernel with voxels given in PVCNativeSpaceKernel. |
+OPTIONAL, DEFAULT = 0 | +
bMakeNIfTI4DICOM |
+Boolean to output CBF native space maps resampled and/or registered to the original T1w/ASL, and contrast adapted and in 12 bit range allowing to convert the NIfTI to a DICOM file, e.g. for implementation in PACS or other DICOM archives. If set to true, an additional CBF image will be created with modifications that allow it to be easily implemented back into a DICOM for e.g. PACS: 1. Remove peak & valley signal, remove NaNs, rescale to 12 bit integers, apply original orientation (2 copies saved, with original ASL and T1w orientation). | ++ |
ApplyQuantification |
+A vector of 1x6 logical values specifying which types on quantified images should be calculated and saved. Fields: 1) Apply ScaleSlopes ASL4D (xASL_wrp_Quantify, future at dcm2niiX stage), 2) Apply ScaleSlopes M0 (xASL_quant_M0, future at dcm2niiX stage), 3) Convert PWI a.u. to label (xASL_wrp_Quantify, future at xASL_wrp_Reslice?), 4) Quantify M0 a.u. (xASL_quant_M0, corrects for incomplete T1 relaxation), 5) Perform division by M0. 6) Apply all scaling. Examples: ASL4D is an already quantified CBF image, disable all quantification '[0 0 0 0 0 0]' . To compare label but not CBF (e.g. label in vessels or sinus vs tissue): [1 1 1 1 0 1]' . Note that the output always goes to CBF.nii. |
+OPTIONAL, DEFAULT = '[1 1 1 1 1 1]' = all enabled |
+
All structural module related parameters are stored within this subfield. Use these to configure processing options of the structural module. Note that some of these settings are directly in the modules
and some are in modules.structural
.
x.modules.[...] |
+Description | +Defaults | +
---|---|---|
bRunLongReg |
+Run longitudinal registration. | +OPTIONAL, DEFAULT = 0 | +
bRunDARTEL |
+Run between-subject registration/create templates. | +OPTIONAL, DEFAULT = 0 | +
WMHsegmAlg |
+Choose the LST algorithm 'LGA'/'LPA' for WMH segmentation | +OPTIONAL, DEFAULT = 'LPA' | +
structural.bSegmentSPM12 |
+Boolean to specify if SPM12 segmentation is run instead of CAT12. Options: 1 = run SPM12, 0 = run CAT12. | +OPTIONAL, DEFAULT = 0 | +
structural.bHammersCAT12 |
+Boolean specifying if CAT12 should provide Hammers volumetric ROI results. | +OPTIONAL, DEFAULT = 0 | +
structural.bFixResolution |
+Resample to a resolution that CAT12 accepts. | +OPTIONAL, DEFAULT=false | +
population.bNativeSpaceAnalysis |
+Output final results calculated also in the subject's native space. | +OPTIONAL, DEFAULT=false | +
General settings can be found in this subfield.
+x.settings.[...] |
+Description | +Defaults | +
---|---|---|
Quality |
+Boolean specifying on which quality the pipeline should be run, options: 1 = normal quality, 0 = lower quality, fewer iterations and lower resolution of processing for a fast try-out. |
+OPTIONAL, DEFAULT = 1 | +
DELETETEMP |
+Boolean for removing the temporary files. Options: 0 = keeping all files, 1 = delete temporary files created by the pipeline. |
+OPTIONAL, DEFAULT = 1 | +
SkipIfNoFlair |
+Boolean to skip processing of subjects that do not have a FLAIR image. These parameters can be useful when some data is still complete, but one would like to start image processing already. Options: 1 = skip processing of a subject that does not have a FLAIR image 0 = do not skip anything. |
+OPTIONAL, DEFAULT = 0 | +
SkipIfNoASL |
+Boolean to skip processing of subjects that do not have a ASL image. Options: 1 = skip processing of a subject that does not have a ASL image, 0 = do not skip anything. |
+OPTIONAL, DEFAULT = 0 | +
SkipIfNoM0 |
+Boolean to skip processing of subjects that do not have a M0 image. Options: 1 = skip processing of a subject that does not have a M0 image, 0 = do not skip anything. |
+OPTIONAL, DEFAULT = 0 | +
stopAfterErrors |
+Number of allowed errors before job iteration is stopped | +(OPTIONAL, DEFAULT = inf) | +
bLesionFilling |
+Boolean for lesion filling in structural module (submodule 5). | +(OPTIONAL, DEFAULT = true) | +
bAutoACPC |
+Boolean whether center of mass alignment should be performed before SPM registration. | +(OPTIONAL, DEFAULT = true) | +
The x.S
subfield contains masking & atlas related parameters.
x.S.[...] |
+Description | +Defaults | +
---|---|---|
bMasking |
+Vector specifying if we should mask a ROI with a subject-specific mask (1 = yes, 0 = no): [1 0 0 0] = susceptibility mask (either population-or subject-wise), [0 1 0 0] = vascular mask (only subject-wise), [0 0 1 0] = subject-specific tissue-masking (e.g. pGM>0.5), [0 0 0 1] = WholeBrain masking (used as memory compression) [0 0 0 0] = no masking at all, [1 1 1 1] = apply all masks, Can also be used as boolean, where 1 = [1 1 1 1] , 0 = [0 0 0 0] . Can be useful for e.g. loading lesion masks outside the GM. |
+OPTIONAL, DEFAULT=1 | +
DataTypes |
+Vector of cells specifying which images to take data from, in the ROI analysis. E.g., | +OPTIONAL, DEFAULT = | +
Atlases |
+Vector specifying the atlases which should be used within the population module. Default definition within the Population Module: x.S.Atlases = {'TotalGM','DeepWM'} . Available atlases (please check the atlas NIfTI and accompanying files for more information): Free atlases: TotalGM : Mask of the entire GM './External/SPMmodified/MapsAdded/TotalGM.nii' , TotalWM : Mask of the entire WM './External/SPMmodified/MapsAdded/TotalWM.nii.gz' , DeepWM : Mask of the deep WM './External/SPMmodified/MapsAdded/DeepWM.nii.gz' , WholeBrain : Mask of the entire brain './External/SPMmodified/MapsAdded/WholeBrain.nii.gz' , MNI_Structural : MNI cortical atlas './External/Atlases/MapsAdded/MNI_Structural.nii.gz' , Tatu_ACA_MCA_PCA : Original vascular territories by Tatu et al. './External/SPMmodified/MapsAdded/VascularTerritories/Tatu_ACA_MCA_PCA.nii.gz' , Tatu_ICA_PCA : Tatu - only ICA and PCA './External/SPMmodified/MapsAdded/VascularTerritories/Tatu_ICA_PCA.nii' , Tatu_ICA_L_ICA_R_PCA : './External/SPMmodified/MapsAdded/VascularTerritories/Tatu_ICA_L_ICA_R_PCA.nii.gz' , Tatu_ACA_MCA_PCA_Prox_Med_Dist : Tatu separated to distal/medial/proximal of ACA/MCA/PCA './External/SPMmodified/MapsAdded/VascularTerritories/Tatu_ACA_MCA_PCA_Prox_Med_Dist.nii.gz' , Mindboggle_OASIS_DKT31_CMA : Mindboggle-101 cortical atlas './External/Atlases/Mindboggle_OASIS_DKT31_CMA.nii.gz' . Free for non-commercial use only: DKT : Desikan-Killiany atlas './External/Atlases/Desikan_Killiany_MNI_SPM12.nii.gz' , HOcort_CONN : Harvard-Oxford cortical atlas './External/Atlases/HOcort_CONN.nii.gz' , HOsub_CONN : Harvard-Oxford subcortical atlas './External/Atlases/HOsub_CONN.nii.gz' , Hammers : Alexander Hammers's brain atlas './External/Atlases/Hammers.nii.gz' , HammersCAT12 : Hammers atlas adapted to DARTEL template of IXI550 space './External/Atlases/HammersCAT12.nii' , Thalamus : Harvad-Oxford thalamus atlas './External/Atlases/Thalamus.nii.gz' . |
+OPTIONAL, DEFAULT={'TotalGM','DeepWM'} |
+
An example configuration file is given below. Note that we include a large number of options and sequence parameters with the purpose of showing the correct formatting of the file and in the praxis no dataPar.json
or only a couple of parameters are typically provided.
{"x": {
+ "dataset": {
+ "subjectRegexp": "^\\d{3}$",
+ "exclusion": ""},
+ "SESSIONS": ["ASL_1","ASL_2"],
+ "S":{"Atlases": ["Thalamus", "HOcort_CONN", "TotalGM"]},
+ "session":{
+ "options": ["baseline","drug"]},
+ "external":{
+ "bAutomaticallyDetectFSL": 1},
+ "Q":{
+ "SliceReadoutTime": 30,
+ "T2art": 50,
+ "BloodT1": 1650},
+ "settings":{
+ "Quality": 1,
+ "DELETETEMP": 1,
+ "bAutoACPC": false},
+ "modules":{
+ "bRunLongReg": true,
+ "structural": {
+ "bSegmentSPM12": 1},
+ "asl":{
+ "M0PositionInASL4D": [1, 2],
+ "bUseMNIasDummyStructural": 1,
+ "bPVCNativeSpace": 1,
+ "PVCNativeSpaceKernel": [10 10 4],
+ "bPVCGaussianMM": 1}}}
+}
+
+Note that sequence parameters should always be defined during the Import through studyPar.json
. Only in rare cases when DICOM files are not available for the initial import, extra sequence parameters can be supplemented just for the processing. This should only be done in rare cases and otherwise is this practice discouraged.
Parameters of the ASL sequence. Note that these parameters should have been defined in the ASL-BIDS format for each subject and saved in its JSON-sidecar. These fields, when provided in a dataPar.json
file are only used if the corresponding ASL-BIDS field is missing. Use of these parameters is thus discouraged unless really needed.
x.Q.[...] |
+Description | +Defaults | +
---|---|---|
M0 |
+Choose which M0 option to use: 'separate_scan' = for a separate M0 NIfTI (needs to be in the same folder called M0.nii ), 3.7394*10^6 = (or any other value) single M0 value to use, 'UseControlAsM0' = will copy the mean control image as M0.nii and process as if it was a separately acquired M0 image (taking TR etc from the ASL4D.nii ). In case the Background Suppression is used, it will automatically try to compensate for it, 'Absent' = will skip any M0 processing; this requires an already quantified CBF image |
+REQUIRED | +
BackgroundSuppressionNumberPulses |
+Used to estimate decrease of labeling efficiency. Options: 0 = (no background suppression), 2 = labeling efficiency factor 0.83 (e.g. Philips 2D EPI & Siemens 3D GRASE), 4 = labeling efficiency factor 0.81 (e.g. Philips 3D GRASE), 5 = labeling efficiency factor 0.75 (e.g. GE 3D spiral). |
+REQUIRED | +
BackgroundSuppressionPulseTime |
+Vector containing timing, in ms, of the background suppression pulses before the start of the readout (per BIDS). REQUIRED when x.Q.UseControlAsM0 & x.Q.BackgroundSuppressionNumberPulses>0. | +Check description | +
PresaturationTime |
+Time in ms before the start of the readout, scalar, when the slice has been saturated (90 degree flip) this has to come before all the bSup pulses, but doesn't need to be always specified. Defaults to PLD (PASL) or PLD+LabDur ((P)CASL). | +OPTIONAL | +
readoutDim |
+String specifying the readout type. Options: '2D' for slice-wise readout, '3D' for volumetric readout. |
+REQUIRED | +
Vendor |
+String containing the Vendor used. This parameter is used to apply the Vendor-specific scale factors, options: 'GE_product', 'GE_WIP', 'Philips', 'Siemens'. | +REQUIRED for ASL | +
Sequence |
+String containing the sequence used. Options: '3D_spiral', '3D_GRASE', '2D_EPI' . |
+REQUIRED for ASL | +
LabelingType |
+String containing the labeling strategy used. Options: 'PASL' (pulsed Q2-TIPS), 'CASL' (CASL/PCASL). Note: pulsed without Q2TIPS cannot be reliably quantified because the bolus width cannot be identified CASL & PCASL are both continuous ASL methods, identical quantification. |
+REQUIRED for ASL | +
Initial_PLD |
+Value of PLD (ms), for 3D this is fixed for whole brain, for 2D this is the PLD of first acquired slice, example: 1800. | +REQUIRED for ASL | +
LabelingDuration |
+Value of labeling duration (ms), example: 1800. | +REQUIRED for ASL | +
SliceReadoutTime |
+Value (ms) of time added to the PLD after reading out each slice, example: 31. Other option = 'shortestTR' ; shortest TR enabled gives each sequence the minimal TR. This enables calculating slice delay per subject. |
+REQUIRED for 2D ASL | +
An example configuration file is given below for the sequence parameters. Please combine these with the configuration file above.
+{"x": {
+ "Q":{
+ "BackgroundSuppressionNumberPulses": 2,
+ "LabelingType": "CASL",
+ "Initial_PLD": 1800,
+ "LabelingDuration": 1800,
+ "SliceReadoutTime": 30,
+ "T2art": 50,
+ "BloodT1": 1650},
+}
+}
+
+
+
+
+
+
+
+ The following requirements are necessary to robustly execute the ExploreASL workflow. ExploreASL is tested on Debian/Ubuntu 20.04 LTS with Matlab 2019a. Using an older version of Linux or Matlab could lead to errors.
+Versions of included & used third-party tools:
+Format:
+function [k,Pc] = CorrClusTh(SPM,u,alpha,guess)
+
+Description:
+Finds the corrected cluster size (spatial extent) threshold for a given +cluster defining threshold u and FWE-corrected level alpha.
+Format:
+xASL_Copy(SrxASL_SysCopyath, DstPath[, bOverwrite, bVerbose)])
+
+Description:
+Copies a file to a file or a directory to a directory. For a file, it zips it in the end if the destination path contains nii.gz. +It also makes sure that only one of .nii and .nii.gz exists +in the destination directory. It is faster than the default +Matlab function, and runs on multiple OSes.
+NB: This function calls xASL_SysMove for the actual copying. +Run xASL_SysMove instead of xASL_Move if you don't want the +.nii|.nii.gz management/checking
+Format:
+xASL_Move(SrcPath, DstPath[, bOverwrite, bVerbose])
+
+Description:
+Moves a file to a file, a file to a directory, or a directory to a directory. It manages the unzipping or zipping according to the extension +after the move. And it makes sure that only one of .nii and .nii.gz exists in the destination directory. +Bypass inefficient Matlab stuff on Linux and Windows, but +can only move on the same file system.
+NB: This function calls xASL_SysMove for the actual moving. +Run xASL_SysMove instead of xASL_Move if you don't want the +.nii|.nii.gz management/checking
+Format:
+xASL_SysCopy(SrcPath, DstPath, bOverwrite, bVerbose)
+
+Description:
+Copies a file to a file or a directory to a directory. Bypass inefficient matlab stuff on linux and windows, +but can only move on the same file system.
+Format:
+xASL_SysMove(SrcPath, DstPath[, bForce, bSourceCheck])
+
+Description:
+Moves a file to a file, a file to a directory, or a directory to a directory. SBypass inefficient matlab stuff on linux and windows, but can only move on same file system!
+Format:
+xASL_TrackProgress(iCurrent[, iMax])
+
+Description:
+Counts the percentage of the work done and display on the screen. Either iCurrent of iMax are given. Or only the percentages are given.
+Format:
+TimeString = xASL_adm_ConvertSeconds2TimeString(Seconds)
+
+Description:
+Converts number to time +input hh (with minutes in fractions/floating point) -> output hhmm +Inverse from xASL_adm_ConvertTime2Nr.
+Format:
+[newString] = xASL_adm_ConvertSlash( StringOriginal,ForceUnix)
+
+Description:
+Converts Windows forward slashes to backward slashes +Prevents confusion file separation & regular expression forward slashes +in Windows.
+Format:
+status = xASL_adm_CreateDir(strPath) create all missing subdirs
+status = xASL_adm_CreateDir(strPath, strBranch) create strBranch (if missing) under existing strPath
+status = xASL_adm_CreateDir(strPath, nMaxNewDirs) impose limit on the number of new directories
+
+Description:
+Recursively creates missing directories at the given path or for given subdirectories, with an option +to limit the number of newly created directories.
+Format:
+filepaths = xASL_adm_DeleteFileList(strDirectory, strRegEx[, bRecurse, nRequired])
+xASL_adm_DeleteFileList(strDirectory, strRegEx[, bRecurse, nRequired])
+
+Description:
+Delete the files that match regular expression STRREGEXP in the given directory STRDIRECTORY. +Deletes recursively if specified in BRECURSE. Deletes all files unless the number is specified +by NREQUIRED, if the number is not met, then does not delete anything and throws an error.
+Format:
+filepaths = xASL_adm_GetFileList(strDirectory[, strRegEx, mode, nRequired, bGetDirNames])
+
+Description:
+List files or directories from a given path. And optionally uses regular expressions to filter the result +with option to set a minimal requirement on the number of results.
+Format:
+pathOut = xASL_adm_GzipNifti(pathIn [,bOverwrite])
+
+Description:
+Take the input file, zips it, overwriting any existing zipped file and return the path of the zipped file.
+Format:
+xASL_adm_ManageMoCoMat(PathIn)
+
+Description:
+This function manages the orientation matrices that SPM puts +in an external .mat sidecar file if there are more than 1 +volumes. The first volume should be equal to the orientation +header of the NIfTI, if not, we assume that the NIfTI +header is correct. +This function performs several checks & corrects if +necessary, combined with throwing a warning:
+Format:
+[PathIs] = xASL_adm_UnixPath(PathIs[, bTryWSL])
+
+Description:
+This function performs the following steps to convert a path to a path that is compatible with the Unix-filesystem +as used in e.g. Linux/MacOS. It also has special support for Windows Subsystem for Linux (WSL), +though this should only be activated specifically for WSL calls.
+Note that we want to use this function for most Unix calls +(to fix paths), but in the case of WSL only for some calls, +where Matlab in Windows calls Linux-code through WSL (e.g. +for FSL) - these have to be explicitly specified by the bTryWSL option.
+Format:
+pathOut = xASL_adm_UnzipNifti(pathIn[, bOverwrite])
+
+Description:
+Takes the input file, unzips if needed, delete the zipped file and return the path to the unzipped file. +If the input is already unzipped, then does nothing, but returns the original filename - so it +can be run just to be sure a file is unzipped without much overhead. +Returns error if more than one file is in the archive, if the filename does not exist, is a directory etc. +If there's a NII and NII.GZ already existing, then return error, or just overwrite in case overwrite is set to 1
+Format:
+[srcOut, dstOut] = xASL_adm_ZipFileNameHandling(srcIn, dstIn)
+
+Description:
+Adjusts the source and destination filenames of a nifti file to reflect if NII or NII.GZ exist on the input. +If either .nii or .nii.gz is corrupt, it automatically deletes the corrupt one and keeps the healthy one, +while reporting a warning. This happens when you restart the pipeline after it crashed, if it crashed while unzipping.
+Format:
+[PathTSV, CellContents] = xASL_bids_csv2tsvReadWrite(PathIn[, bDeleteCSV, bWriteTSV])
+
+Description:
+This function PathIn and loads it, also trying CSV or TSV +extensions if these exist. It outputs the contents to a cell array. If a +CSV file exists but not a TSV file, it converts and replaces the CSV to +TSV file, per BIDS. This function has the following parts:
+Format:
+[CellContents] = xASL_csvRead(PathCSV)
+
+Description:
+This function loads a comma-separated value (csv) file - which +is the format that BIDS prefers - and outputs it to a cell array.
+Format:
+xASL_csvWrite(InputCell, PathCSV[, bOverwrite])
+
+Description:
+Legacy function, please use xASL_tsvWrite instead, as this function might be discontinued in the future. +For usage, type help xASL_tsvWrite.
+Format:
+xASL_delete(InputPath)
+
+Description:
+Delete the file in the given path. If a NIFTI file with extension '.nii' or '.nii.gz' is given, +Then delete both the .nii and .nii.gz files.
+Format:
+xASL_exist(PathIn[,Type])
+
+Description:
+Check if the given path exists, wrapper around the Matlab +exist function, to allow checking for either .nii or .nii.gz +Otherwise, exist is used normally.
+Format:
+[Fpath, Ffile, Fext] = xASL_fileparts(InputPath)
+
+Description:
+Returns the path, file name, and file extension for InputPath using the fileparts.m function. +If a file ending at nii.gz is given, then the whole nii.gz is returned as the extension. +Does not verify the existence of the file, or existence of .nii or .nii.gz
+Format:
+[IMout] = xASL_im_ConvertMap2Mask(IMin)
+
+Description:
+Provides a robust way of conversion of +a continuous map to a binary mask, which can be used for lesions, ROIs, +or tissue probability maps. Based on the assumption that a map should +be thresholded at 50% to form a map, which is often the case for +automatic segmentations.
+Format:
+[dist, x, y, z] = xASL_im_DistanceTransform(im)
+
+Description:
+Calculates the distance transform in a binary image +Uses Borgefors Chamfers computation of Euclidean distance in 3D using a +5x5x5 window.
+Format:
+xASL_im_FillNaNs(InputPath[, UseMethod, bQuality, VoxelSize])
+
+Description:
+This function fills any NaNs in an image. In SPM, any voxels +outside the boundary box/field of view are filled by NaNs +when resampling. These NaNs can confuse some algorithms, +hence it doesn't hurt replacing them in some cases (e.g. for +flowfields). Also, smoothing restricted in a mask is done in +ExploreASL with the function xASL_im_ndnanfilter, after +first setting all voxels outside the mask to NaN. In this +case, this functon can be useful to extrapolate the smoothed +image to avoid any division artifact near brain edges (e.g. +for reducing the M0 image to a smooth biasfield). +This function performs the following 3 steps:
+Format:
+[Ycls, LesionImOut] = xASL_im_LesionRemoval4CAT(Ycls, PathIn)
+
+Description:
+For all lesion masks in the anatomical directory, remove +them from the current segmentations.
+Format:
+[imOut] = xASL_im_ResampleIM(imIn, matIn, matOut, dimOut[, interpolationType])
+
+Description:
+Resamples an input image imIn oriented according to the homogeneous matrix matIn to and output +image imOut that has dimension dimOut and matrix matOut. This allows to resample images between +two spaces with different orientation and matrix sizes. It uses the Matlab interp3 function and +the interpolation method used by this method can be chosen. Note that the recommended use of this +function is resampling between space with similar resolution or upsampling. For downsampling, simple +interpolation does not delivery correct results respecting the point-spread-function and a combination of +xASL_im_PreSmooth and xASL_spm_reslice should be used instead.
+Format:
+xASL_im_SaveOriginal4CAT(Ycls, PathIn)
+
+Description:
+Save the segmentation before lesion masking.
+Format:
+[imConv] = xASL_mex_conv3Dsep(im,kX,[kY,kZ])
+
+Description:
+3D separable convolution with a supplied kernel +It converts the results to double +Returned is the convoluted image +The wrapper makes sure that kX are Nx1 format, removes nan, and removes +excessive zeros at the ends.
+Format:
+[Y,fil] = xASL_im_ndnanfilter(X,filterType,F,WNAN)
+
+Description:
+This function applies a 3-dimensional convolution of X with given kernel. +NaNs elements are taken into account (ignored).
+By default, edges are not padded and one-sided filter is used at the image edges.
+Notes:
+* For the Gaussian filter, use (previous N, new FWHM)
+N= 1 ~ FWHM 0.94
+Format:
+imOut = xASL_io_Nifti2Im(niftiIn [, ImageSize])
+
+Description:
+This function loads a NIfTI image matrix with flexible input +(as explained under INPUT: niftiIn). It does the following.
+Format:
+[NiftiObject, pathIn] = xASL_io_ReadNifti(pathIn)
+
+Description:
+Read Nifti file given by the path. Return the NII object. And also return the actual path to the loaded +Nifti if by any reason the name changed during the function runtime (e.g. unzipping).
+Format:
+xASL_io_SaveNifti(pathOrigNifti, pathNewNifti, imNew[, nBits, bGZip, newMat])
+
+Description:
+It loads the pathOrigNifti, takes all the parameters from it, and creates a new Nifti file with +these parameters, but new image matrix from imNew. It saves the result in pathNewNifti. +It runs the following steps:
+Format:
+[DataOut] = xASL_num2str(DataIn[, stringFormat, bConcatenate, stringDelimiter])
+
+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. +Column vectors are converted to row vectors.
+Format:
+[OutputN] = xASL_round(InputN[, PrecisionN])
+
+Description:
+Recent Matlab versions support a second input that specifies that number of decimals to round at, +but earlier Matlab versions do not support this. For backward compatibility, use this wrapper instead of round.
+Format:
+xASL_spm_admin(pathIn[, bPadComma1])
+
+Description:
+This SPM admin function takes a NIfTI path and does a few +checks to make this valid to SPM. It accepts both .nii and .nii.gz. +It runs the following steps:
+Format:
+xASL_spm_reslice(refPath, srcPath[, srcAffinePath, bInvAffine, bQuality, NewName, InterpolationPar])
+
+Description:
+This wrapper runs SPM's reslice function (a.k.a. coregister: reslice) which resamples a source image into the space of a reference image, +taking into account any orientation differences between the two images that are defined in the orientation matrix in the NIfTI header. +When the source image contains multiple volumes, they are all resampled. +The source image will get the same orientation matrix as the reference image, +as it is now in the same space as the reference image. This can be useful when two images are to be compared voxel-by-voxel, e.g. when +overlaying a CBF image over a structural image, or when wanting to use a mask from a different space. When after running this function, the +reference and source images are not in alignment, they need to be registered first (i.e. xASL_spm_register). +Resampling/reslicing needs an interpolation method to know from which voxels of the source image, a voxel in the new image will be computed. +A simplistic explanation is that this determines the number of surrounding neighborhood voxels it uses to determine the new voxel value. +The example syntax below would reslice/resample the CBF image to the T1w space (assuming the Affine was done to register CBF to T1w) +It also works with the external .mat file of the source file that has the same name as the source file. It also can optionally take a _sn.mat containing the +affine transformation information.
+Format:
+xASL_spm_smooth(pathIn, fwhmSmooth, pathNew])
+
+Description:
+This SPM wrapper runs SPM's smooth function, which spatially smooths the input image with a Gaussian kernel. +In the case of multiple volumes (i.e. a 4D NIfTI), each 3D volume is spatially smoothed separately. +Note that smoothnesses combine with Pythagoras' rule (i.e. sum quadratically)
+Format:
+y = xASL_stat_MeanNan(x[,dim])
+
+Description:
+It calculates the sum using the SUM functions and divides by the number of values but ignoring NaNs.
+Format:
+y = xASL_stat_MedianNan(x[,dim])
+
+Description:
+It calculates the MEDIAN along the given dimension, but it sets all the NaNs to zero before calling it.
+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.
+Format:
+
+[result1, result2] = xASL_system(Command[, bVerbose])
+
+Description:
+This function allows running a system call from Matlab in an optimized fashion. +E.g., it will use user-specific CLI initializations, which are in ~/.bashrc +or ~/.zshrc (depending on the CLI used, Linux by default uses bash, macOS by default uses zsh).
+It runs the following steps:
+Format:
+[CellContents] = xASL_tsvRead(PathTSV[, bStruct])
+
+Description:
+This function loads a tab-separated value (TSV) file - which +is the format that BIDS prefers - and outputs it to a cell array.
+Format:
+xASL_tsvWrite(InputCell, PathTSV[, bOverwrite, bCSV])
+
+Description:
+This function loads a cell array and prints it to a +tab-separated value (TSV) file, which is the format that BIDS prefers.
+Format:
+xASL_wrp_DARTELSaveIntermedTrans(Yy, u, odim, rdim, idim, Mar, mat, M0, M1, nameOut, numIteration)
+
+Description:
+This function is called from the CAT12 segmentation function to save the intermediate results +of the DARTEL transformation. Normally, the registration only saves the final results - +the final transformation field. This function enables to save also the intermediate transformation field. +It takes all the internal variables from the transformation and save the field to a sub-directory 'mri' +that normally contains all the intermediate results of the CAT12 segmentation. It adds a 'y_' prefix +and adds the specified iteration number as postfix.
+Format:
+xASL_wrp_GSSaveIntermedTrans(y, idim, odim, rdim, M0, M1, R, M1t, M1r, nameOut, numIteration)
+
+Description:
+This function is called from the CAT12 segmentation function to save the intermediate results +of the Geodesic shooting transformation. Normally, the registration only saves the final results - +the final transformation field. This function enables to save also the intermediate transformation field. +It takes all the internal variables from the transformation and save the field to a sub-directory 'mri' +that normally contains all the intermediate results of the CAT12 segmentation. It adds a 'y_' prefix +and adds the specified iteration number as postfix.
+ + + + + + +Format:
+xASL_wrp_CleanUpWMH_SEGM(x)
+
+Description:
+This submodule aims to clean up WMH under- or oversegmentations in a conservatively & robust way, +i.e. erring on the side of caution. It uses input from the tissue class segmentation (e.g. CAT12) to repair the +WMH segmentation (e.g. LST LPA/LGA or externally provided). Note that before running the tissue segmentation, the T1w was +(conservatively) filled for WMH lesions. % This function is not tested a lot, so mainly conservatively set up to improve the +WMH volumetrics, rather than improve the registration.
+This submodule contains the following steps:
+Format:
+xASL_wrp_FLAIR_BiasfieldCorrection(x)
+
+Description:
+This submodule performs a biasfield correction on T1w and applies it on FLAIR. This can be useful, when there are large lesions +on the FLAIR that hamper capturing the biasfield nicely on the FLAIR itself. In such cases, the biasfield of the T1w might be easier to obtain +and should be the same as the FLAIR, provided they are scanned in the same scan session (i.e.g same scanner, same coil). +BE CAREFUL: this submodule assumes that the biasfields of the T1w and FLAIR are comparable, which is not the case when one of the two (or both) are +already biasfield corrected.
+Format:
+xASL_wrp_GetVolumetrics(x)
+
+Description:
+This submodule computes the total volume for each of the tissue classes & stores them in a TSV file (per BIDS). +This is computed from the native space segmentation derivatives (GM, WM & CSF), from which the ICV & relative volumes can be +calculated. This is performed for CAT12 or SPM12 (whichever was used), and optionally for a WMH_SEGM.
+Format:
+xASL_wrp_LST_Segment_FLAIR_WMH(x, rWMHPath[, WMHsegmAlg])
+
+Description:
+This submodule runs the LST WMH segmentation, either with LGA or LPA. +LPA is the default choice, it outperforms LGA a bit, depending on the image quality. These algorithms +perform optimally with 3T images, with good contrast. Generally, LPA oversegments whereas LGA undersegments. +The LPA oversegmentation is corrected in a later submodule. If a WMH_SEGM +already existed, the LST is run quickly as dummy only, to be replaced by +the original WMH_SEGM image. This function has the following parts:
+Format:
+xASL_wrp_LST_T1w_LesionFilling_WMH(x)
+
+Description:
+This submodule runs the LST WMH-based T1w lesion filling, which should improve the registration & segmentation +of the T1w by e.g. CAT12/SPM12. The WMH can be either segmented in the previous submodule by LST LGA/LPGA or provided externally. +Before lesion filling, we clean up the WMH segmentation, to make the lesion filling a bit more conservative. Sometimes the WMH +segmentation oversegments inside the GM (as there can be hyperintensities on the FLAIR) & we don't want to lesion-fill these +on the T1w (which would turn their intensities in intensities similar to WM, leading to misclassifications by the T1w segmentation). +Note that this is submodule only performs the lesion filling, and the clean up is also performed for the lesion filling only. +A more thorough WMH clean up (for e.g. WMH volumetrics) is performed later in the Structural module, using also the results from the +T1w segmentation.
+Note when changing the lesion filling here, LST lesion filling expects a probability map, doesnt work nicely with binary mask +This function runs the following steps:
+Format:
+xASL_wrp_LinearReg_FLAIR2T1w(x[, bAutoACPC])
+
+Description:
+This submodule registers FLAIR linearly to the T1w +The same transformation is applied to all other related scans (FLAIR-segmented lesions, WMH specifically or other lesions) +This is required to enable the application of T1w derivatives (e.g. transformations to standard space, tissue segmentation) for FLAIR +and vice versa (e.g. WMH lesion-filling).
+Format:
+xASL_wrp_LinearReg_Others2T1w(x[, bAutoACPC])
+
+Description:
+This submodule registers T1c and T2 linearly to the T1w
+Format:
+xASL_wrp_LinearReg_T1w2MNI(x[, bAutoACPC])
+
+Description:
+This submodule registers T1w linearly to the center of MNI space, a.k.a. ACPC alignment +The same transformation is applied to all other related scans (ASL4D, M0, FLAIR, etc.) +This facilitates MNI-based algorithms (e.g. SPM-based segmentation), and allows for visual QC with all images +roughly in the same space. This submodule first clips high values that can bias the registration algorithm, then performs +a center of mass-based ACPC alignment, and then several iterations of SPM coregistration. +Assuming that this submodule is run at the start of ExploreASL, all NIfTI orientation matrices are restored before running the registration.
+Format:
+xASL_wrp_Resample2StandardSpace(x)
+
+Description:
+This submodule resamples all structural images & their derivatives to standard space. It uses the transformation +fields that were obtained previously in the Structural module, concatenates all transformations into a single transformation +(if not already done) & applies the transformation with a single interpolation (either trilinear for low quality or probability +maps, or 2nd order B-spline). Finally, it computes the Jacobian determinants (i.e. the derivative of the transformation field) +to obtain a map of the volumetric effects of the transformation. This Jacobian map is multiplied with the standard space resampled +images, to restore their (local & global) total volume. The sum of volumes in native & standard space are compared as QC. +This submodule is not only part of the structural module, but can be repeated when the transformation map is edited, e.g. after +longitudinal registration or after creation of a group-wise template.
+Format:
+[x] = xASL_wrp_SegmentT1w(x, bSegmentSPM12)
+
+Description:
+This submodule segments high resolution structural/anatomical scans into GM/WM/CSF/soft tissue/bone/air tissue classes. +It will save GM/WM/CSF in native space, and the transformation from native to standard space. +This transformation includes Geodesic Shooting/DARTEL for CAT12.
+This submodule contains the following steps:
+Format:
+xASL_wrp_VisualQC_Structural(x)
+
+Description:
+This submodule performs several visualizations for visual & quantitative QC.
+This tutorial gives an example of useful functions that can be used outside of the pipeline for certain image operations, evaluations, and statistics. More information can be found in the reference manual.
+Moreover, we list here the internal parameters in ExploreASL that can be used either to supply further parameters or to modify certain advanced parameters during ExploreASL runtime.
+Let's assume you want to read in a NIFTI image and apply a mask on it. As a good first step we always recommend to initialize ExploreASL
first by running the following command.
[x] = ExploreASL();
+
+Now let's read in the image by defining the image path and using the xASL_io_Nifti2Im
function.
pathNIFTI = fullfile(x.MyPath,'External','TestDataSet','analysis','Sub-001','T1.nii');
+image = xASL_io_Nifti2Im(pathNIFTI);
+
+Maybe we want to mask the image. The image and the mask do not have the same resolution though, which means we need to resample either the mask or the image. The following commands will resample the mask to the image size.
+pathMask = fullfile(x.MyPath,'External','SPMmodified','MapsAdded','brainmask.nii');
+mask = xASL_io_Nifti2Im(pathMask);
+maskResampled = xASL_im_ResampleLinear(mask, size(image));
+
+To mask the image we multiply the image matrix with the mask matrix. This way all voxels outside of the mask are set to 0.
+image = image.*maskResampled;
+
+Then we can save the image as a NIFTI again and open it with our favorite NIFTI viewer.
+xASL_io_CreateNifti(fullfile(x.MyPath,'export.nii'), image);
+
+xASL_io_Nifti2Im
does unzip your image, so make sure to revert those changes within the ExploreASL directory later using git reset
or git revert
.
Matlab offers two functions to copy or move files and folders from a source
to a destination
within your file system. These functions are copyfile
and movefile
. To improve speed and multi OS compatibility, we wrote two similar functions, called xASL_Copy
and xASL_Move
. In the following example we copy a file called fileA
from the folder C:\Users\Test_One
to C:\Users\Test_Two
. We then move the file back to C:\Users\Test_One
and overwrite the original fileA
. Finally, we rename fileA
to fileB
.
% Copy fileA from Test_One to Test_Two
+xASL_Copy('C:\Users\Test_One\fileA.txt', 'C:\Users\Test_Two\fileA.txt');
+
+% Move fileA back to Test_One and overwrite the original fileA
+xASL_Move('C:\Users\Test_Two\fileA.txt', 'C:\Users\Test_One\fileA.txt', 1);
+
+% Rename fileA to fileB
+xASL_Move('C:\Users\Test_One\fileA.txt', 'C:\Users\Test_One\fileB.txt', 1);
+
+Often we need to find a list of files in a certain directory. To do this, we can use xASL_adm_GetFileList
. Let's assume there are five files called fileA
, fileB
, fileC
, fileD
and fileE
in C:\Users\Test_One
. We know that all names start with file
, so we can use this for our regular expression. Check out the example below on how you can get a cell array containing the paths of all these files.
strDirectory = 'C:\Users\Test_One';
+strRegEx = '^file.+$';
+filepaths = xASL_adm_GetFileList(strDirectory, strRegEx);
+
+The ExploreASL x
structure is the main object used to define pipeline settings. Besides pipeline settings you can also find processing parameters and metadata there. This manual contains the complete list of all parameters including those that can only be modified during runtime and by developers. Basic and advanced settings for the users that are modifiable in configuration files are listed in the Processing Tutorials.
General options can be found in this subfield.
+Fieldname | +Description | +
---|---|
x.opts.DatasetRoot | +Dataset root directory of the current BIDS dataset. This is also the first input argument of ExploreASL . |
+
x.opts.ImportModules | +Vector to define which import modules should be executed. This is also the second input argument of ExploreASL . |
+
x.opts.ProcessModules | +Vector to define which processing modules should be executed. This is also the third input argument of ExploreASL . |
+
x.opts.bPause | +Boolean to set if you want to pause the pipeline before the processing. This is also the fourth input argument of ExploreASL . |
+
x.opts.iWorker | +This variable defines which of the parallel ExploreASL calls we are. This is also the fifth input argument of ExploreASL . |
+
x.opts.nWorkers | +This variable defines how many ExploreASL calls are made in parallel. This is also the sixth input argument of ExploreASL . |
+
x.opts.bImportData | +Boolean that is true if at least one import module is going to be executed. | +
x.opts.bProcessData | +Boolean that is true if at least one processing module is going to be executed. | +
x.opts.bLoadData | +Boolean that is true if the current BIDS dataset is going to be loaded. | +
x.opts.MyPath | +Path to the ExploreASL program. |
+
x.opts.dataParType | +String describing the type of input argument that was given for the DatasetRoot . This parameter is mainly supposed to help with backwards compatibility. |
+
All import module related parameters are stored within this subfield.
+Fieldname | +Description | +
---|---|
x.modules.import.settings.bCopySingleDicoms | +Boolean to define if single DICOMs should be copied during the import. | +
x.modules.import.settings.bUseDCMTK | +Boolean to define if DCMTK should be used for the import workflow. | +
x.modules.import.settings.bCheckPermissions | +Boolean to define if the workflow should check for permission issues. | +
The x.S
subfield contains masking & atlas related parameters.
Fieldname | +Description | +
---|---|
x.S.bMasking | +Vector specifying if we should mask a ROI with a subject-specific mask. | +
x.S.Atlases | +Vector specifying the atlases which should be used within the population module. | +
x.S.slices | +Slice numbers: defines which transversal slices to use by default. | +
x.S.slicesLarge | +Slice numbers: defines which transversal slices to use by default. | +
x.S.slicesExtraLarge | +Slice numbers: defines which transversal slices to use by default. | +
x.S.nSlices | +Length of x.S.slices. | +
x.S.nSlicesLarge | +Length of x.S.slicesLarge. | +
x.S.nSlicesExtraLarge | +Length of x.S.slicesExtraLarge. | +
x.S.TransCrop | +Cropping settings: defines default transversal cropping settings. | +
x.S.jet256 | +Jet 256 colormap. | +
x.S.gray | +Grayscale colormap. | +
x.S.red | +Red colormap. | +
x.S.yellow | +Yellow colormap. | +
x.S.green | +Green colormap. | +
x.S.blue | +Blue colormap. | +
x.S.purple | +Purple colormap. | +
x.S.turqoise | +Turqoise colormap. | +
x.S.orange | +Orange colormap. | +
x.S.colors_ROI | +Cell array containing the colormaps from above. | +
x.S.cool | +Cool colorbar. | +
x.S.hot | +Hot colorbar. | +
x.S.VoxelSize | +Voxel-size in mm of reslicing & DARTEL (default=1.5mm). | +
x.S.masks | +Contains skull and WBmask. | +
x.S.LabelClr | +64 label colors. | +
General settings can be found in this subfield.
+Fieldname | +Description | +
---|---|
x.settings.SelectParFile | +Variable which tells the import workflow if we have to ask the user for the study root directory a second time. | +
x.settings.stopAfterErrors | +Number of allowed errors before job iteration is stopped (default=inf). | +
x.settings.dryRun | +Dry run does not execute the module (default=0). | +
x.settings.bOverwrite | +Re-running makes no sense if you're not overwriting existing files. | +
x.settings.BILAT_FILTER | +Bilateral filter by Matthan Caan (original=1, more recent=2). | +
x.settings.DELETETEMP | +Boolean for removing the temporary files. | +
x.settings.Quality | +Quality setting for ExploreASL processing. Set to 1 for normal high-quality processing or to 0 for low-quality test runs. |
+
x.settings.bReproTesting | +n/a | +
x.settings.Pediatric_Template | +n/a | +
x.settings.bLesionFilling | +Boolean for lesion filling in structural module (submodule 5). | +
x.settings.bAutoACPC | +Boolean whether center of mass alignment should be performed before SPM registration. | +
x.settings.bGetControlLabelOrder | +n/a | +
x.settings.SkipIfNoFlair | +Boolean to skip processing of subjects that do not have a FLAIR image. | +
x.settings.SkipIfNoASL | +Boolean to skip processing of subjects that do not have a ASL image. | +
x.settings.SkipIfNoM0 | +Boolean to skip processing of subjects that do not have a M0 image. | +
Dataset related parameters can be found in this subfield.
+Fieldname | +Description | +
---|---|
x.dataset.name | +String for the name of the study. | +
x.dataset.subjectRegexp | +String with regular expression for ExploreASL to find subjects by foldername. | +
x.dataset.exclusion | +Cell with list of subjects to exclude. | +
x.dataset.ForceInclusionList | +Use this field if you want to use a selection of subjects rather than taking all available subjects from directories. | +
In these subfields we store path related values.
+Fieldname | +Description | +
---|---|
x.dir.sourceStructure | +Path to the sourceStructure.json file. | +
x.dir.studyPar | +Path to the studyPar.json file. | +
x.dir.dataset_description | +Path to the dataset_description.json file. | +
x.dir.dataPar | +Path to the dataPar.json file. | +
x.D.ROOT | +Path to the root directory. | +
In x.Q
you can find sequence and quantification related parameters.
Fieldname | +Description | +
---|---|
x.Q.M0 | +Choose which M0 option to use. | +
x.Q.BackgroundSuppressionNumberPulses | +Used to estimate decrease of labeling efficiency. | +
x.Q.BackgroundSuppressionPulseTime | +Vector containing timing, in ms, of the background suppression pulses before the start of the readout (per BIDS). | +
x.Q.PresaturationTime | +Time in ms before the start of the readout, scalar, when the slice has been saturated (90 degree flip) this has to come before all the bSup pulses, but doesn't need to be always specified. | +
x.Q.readoutDim | +String specifying the readout type. | +
x.Q.Vendor | +String containing the Vendor used. | +
x.Q.Sequence | +String containing the sequence used. | +
x.Q.LabelingType | +String containing the labeling strategy used. | +
x.Q.Initial_PLD | +Value of PLD (ms), for 3D this is fixed for whole brain, for 2D this is the PLD of first acquired slice. | +
x.Q.LabelingDuration | +Value of labeling duration (ms). | +
x.Q.SliceReadoutTime | +Value (ms) of time added to the PLD after reading out each slice. | +
x.Q.bUseBasilQuantification | +True for using BASIL quantification in addition to ExploreASL's quantification. | +
x.Q.Lambda | +Brain/blood water coefficient (mL 1H/ mL blood). | +
x.Q.T2art | +T2* of arterial blood at 3T, only used when no M0 image (ms). |
+
x.Q.BloodT1 | +T1 relaxation time of arterial blood (ms). Defaults (Alsop MRM 2014), 1800 for GSP phantom. | +
x.Q.TissueT1 | +T1 relaxation time of GM tissue (ms). Defaults (Alsop MRM 2014). | +
x.Q.nCompartments | +Number of modeled compartments for quantification. | +
x.Q.SaveCBF4D | +Boolean, true to also save 4D CBF timeseries, if ASL4D had timeseries. | +
Parameters for additional modules are stored within the main level of x.modules
.
Fieldname | +Description | +
---|---|
x.modules.bRunLongReg | +Run longitudinal registration. | +
x.modules.bRunDARTEL | +Run between-subject registration/create templates. | +
All structural module related parameters are stored within this subfield.
+Fieldname | +Description | +
---|---|
x.modules.structural.bSegmentSPM12 | +Boolean to specify if SPM12 segmentation is run instead of CAT12. | +
x.modules.structural.bHammersCAT12 | +Boolean specifying if CAT12 should provide Hammers volumetric ROI results. | +
x.modules.structural.bFixResolution | +Resample to a resolution that CAT12 accepts. | +
All ASL module related parameters are stored within this subfield.
+Fieldname | +Description | +
---|---|
x.modules.asl.motionCorrection | +Boolean to perform motion correction in case of timeseries. | +
x.modules.asl.SpikeRemovalThreshold | +Minimal t-stat improval needed to remove motion spikes. | +
x.modules.asl.bRegistrationContrast | +Specifies the image contrast used for registration. | +
x.modules.asl.bAffineRegistration | +Specifies if the ASL-T1w rigid-body registration is followed up by an affine registration. | +
x.modules.asl.bDCTRegistration | +Specifies if to include the DCT registration on top of Affine. | +
x.modules.asl.bRegisterM02ASL | +Boolean specifying whether M0 is registered to mean_control image (or T1w if no control image exists). | +
x.modules.asl.bUseMNIasDummyStructural | +When structural (e.g. T1w) data is missing, copy population-average MNI templates as dummy structural templates. | +
x.modules.asl.bPVCNativeSpace | +Performs partial volume correction (PVC) in ASL native space using the GM and WM maps obtained from previously segmented T1-weighted images. | +
x.modules.asl.PVCNativeSpaceKernel | +Kernel size for the ASL native space PVC. | +
x.modules.asl.bPVCGaussianMM | +If set to 1, PV-correction with a Gaussian weighting is used instead of the equal weights of all voxels in the kernel ('flat' kernel) as per Asllani's original method. | +
x.modules.asl.bMakeNIfTI4DICOM | +Boolean to output CBF native space maps resampled and/or registered to the original T1w/ASL, and contrast adapted and in 12 bit range allowing to convert the NIfTI to a DICOM file. | +
x.modules.asl.ApplyQuantification | +A vector of 1x5 logical values specifying which types on quantified images should be calculated and saved. | +
All population module related parameters are stored within this subfield.
+Fieldname | +Description | +
---|---|
... | +n/a | +
Within x.external
you can find parameters related to external tools and the coding environment.
Fieldname | +Description | +
---|---|
x.external.SPMVERSION | +String describing the version of SPM. | +
x.external.bAutomaticallyDetectFSL | +Boolean to automatically detect the FSL version if disabled, this function will try to use the system-initialized FSL and throw an error if FSL is not initialized. | +
Starting with version v1.7.0, ExploreASL will support an import workflow which allows the user to convert DICOM and NIFTI data to the ASL-BIDS format. Since ExploreASL does not fully utilize the BIDS format internally, there will also be an automated workflow to convert from ASL-BIDS to the ExploreASL legacy format (starting with version v1.10.0, this will be done automatically if needed). In the following subsections we will explain how you can use the automated ExploreASL import workflow to convert your input data to ASL-BIDS and how you can process it.
+To start ExploreASL, you utilize the ExploreASL
script. Below is a basic description of the most typical use cases:
Initialization only: +To only initialize the package, you execute:
+[x] = ExploreASL();
Initialization adds paths to all atlases and functions needed for ExploreASL execution. Initialization is also run automatically before any command for processing or importing data.
+Processing ASL-BIDS data:
+To fully process data in ASL-BIDS format located in drive/.../datasetRoot/rawdata
(note that since version v1.10.0, the rawdata
are converted to the Legacy format in derivatives
automatically without needing to call the import:
[x] = ExploreASL('drive/.../datasetRoot', 0, 1);
Importing DICOM to ASL-BIDS:
+To import DICOM data located in drive/.../datasetRoot/sourcedata
and convert them to ASL-BIDS format (see more in Tutorial on Import):
[x] = ExploreASL('drive/.../datasetRoot', [1 1 0], 0);
Importing DICOM to ASL-BIDS:
+To import DICOM data located in drive/.../datasetRoot/sourcedata
to ASL-BIDS and fully process them:
[x] = ExploreASL('drive/.../datasetRoot', [1 1 0], 1);
Structural and ASL processing of ASL-BIDS data:
+To run the Structural and ASL processing on data in ASL-BIDS format located in drive/.../datasetRoot/rawdata
:
[x] = ExploreASL('drive/.../datasetRoot', 0, [1 1 0]);
Population module on pre-processed data:
+To run the Population module on previously processed data stored in drive/.../datasetRoot/derivatives/ExploreASL
:
[x] = ExploreASL('drive/.../datasetRoot', 0, [0 0 1]);
Below is a complete description of all the options for import and processing. ExploreASL is executed with the following command:
+[x] = ExploreASL([DatasetRoot, ImportModules, ProcessModules, bPause, iWorker, nWorkers])
+
+Parameter descriptions:
+DatasetRoot
: Path to the BIDS dataset root directory, which contains either the DICOM data in sourcedata
subfolder, or ASL-BIDS data in rawdata
subfolder or already processed data with ExploreASL in derivatives\ExploreASL
subfolder (OPTIONAL
)
+ | DatasetRoot | +
---|---|
Type | +CHAR ARRAY |
+
Default | +Prompting user input | +
ImportModules
: Multi-step import workflow. Note that either a vector is provided or a scalar (which is then translated as [1 1 0]
, i.e. skipping the deface module unless explicitly turned on) (OPTIONAL
). Note that the BIDS to LEGACY conversion from the ASL-BIDS in rawdata
to ExploreASL format in derivatives\ExploreASL
is now run automatically when needed as part of the Processing Module
DCM2NII
: Run the DICOM to NIFTI conversion from sourcedata
subfolder and saves to derivatives\ExploreASL\temp
subfolderNII2BIDS
: Run the NIFTI to BIDS conversion from subfolder derivatives\ExploreASL\temp
and saves the complete ASL-BIDS data to a rawdata
subfolderDEFACE
: Run the defacing of structural scans with input and output to the rawdata
subfolderImportModules | +DCM2NII | +NII2BIDS | +DEFACE | +
---|---|---|---|
Type | +BOOLEAN |
+BOOLEAN |
+BOOLEAN |
+
Default | +false |
+false |
+false |
+
ProcessModules
: Multi-step processing pipeline. Either a full vector, or scalar turning all options either on or off, can be used (OPTIONAL
)
STRUCTURAL
: Run the Structural ModuleASL
: Run the ASL ModulePOPULATION
: Run the Population ModuleProcessModules | +STRUCTURAL | +ASL | +POPULATION | +
---|---|---|---|
Type | +BOOLEAN |
+BOOLEAN |
+BOOLEAN |
+
Default | +false |
+false |
+false |
+
bPause
: Pause workflow before ExploreASL pipeline to review input parameters (OPTIONAL
)
+ | bPause | +
---|---|
Type | +BOOLEAN |
+
Default | +false |
+
iWorker
: Allows parallelization when called externally - see the option below (OPTIONAL
)
+ | iWorker | +
---|---|
Type | +INTEGER |
+
Default | +1 |
+
nWorkers
: Allows parallelization when called externally - it assumes that the user calls himself nWorkers
instances of ExploreASL and that the current instance has number iWorker
. It (OPTIONAL
)
+ | nWorkers | +
---|---|
Type | +INTEGER |
+
Default | +1 |
+
In the following examples, we want to show how you can use the revised import workflow and how the conventional processing is done now. Another example for the import module is shown in the Import Tutorial.
+Converting DICOM source data according to the ASL BIDS standard can be done using the new import workflow. For the upcoming release v1.7.0 we're preparing an exemplary DICOM source dataset based on the ASL DRO. To run this workflow, you have to use the path to your dataset root directory. This dataset root directory should contain a sourceStructure.json
file, a studyPar.json
file (see Import Tutorial for details) and optionally also a dataPar.json
file (see the Processing Tutorial Processing Tutorial). Do not forget to set up the source dataset in drive/.../datasetRoot/sourcedata
correctly. We're working on a flavor library, to enable the import and processing of a wide variety of different sequence, vendor, and scanner combinations.
The first step to convert your DICOM source data to NIFTI source data is to run the following command:
+[x] = ExploreASL('drive/.../datasetRoot', [1 0 0],1);
Here we tell ExploreASL to run the DCM2NII
import module by setting the first boolean variable of the ImportModules
to 1
. The output is save to drive/.../datasetRoot/derivatives/ExploreASL/temp
Let's assume we have intermediate NIFTI data now in drive/.../datasetRoot/derivatives/ExploreASL/temp
. To convert this intermediate data to ASL-BIDS raw data, we have to run the second part of the import workflow. To run the second step, we set the second variable of the ImportModules
to 1
. Similar to the previous step, we pass the datasetRoot
directory to ExploreASL. The output is then written to drive/.../datasetRoot/rawdata
.
[x] = ExploreASL('drive/.../datasetRoot', [0 1 0], 0);
There's also a new option to deface your structural scans. To do this, you can run the third step of the import workflow. This is done by setting the third variable of the ImportModules
to 1
. Similar to the previous steps, we pass the DatasetRoot
directory to ExploreASL. Both input and output directory is drive/.../datasetRoot/rawdata
[x] = ExploreASL('drive/.../datasetRoot', [0 0 1], 0);
Right now, ExploreASL still uses the conventional data structure. The conversion from our ASL-BIDS rawdata to the ExploreASL legacy format is done (since version v1.10.0) automatically as the first step of the Processing Module if needed. The input ASL-BIDS data from drive/.../datasetRoot/rawdata
are converted to drive/.../datasetRoot/derivatives/ExploreASL/
This step will also copy and adapt your provided drive/.../datasetRoot/rawdata/dataPar.json
file to drive/.../datasetRoot/derivatives/ExploreASL/dataPar.json
or create a default one if drive/.../datasetRoot/rawdata/dataPar.json
is missing. To adapt your pipeline, you can edit the drive/.../datasetRoot/derivatives/ExploreASL/dataPar.json
file before running the Structural and ASL modules.
If you just want to use the conventional ExploreASL processing pipeline, you can simply turn off the import workflow by setting all ImportModules
variables to 0
individually or by using a single 0
for the ImportModules
. This results in the following notation:
[x] = ExploreASL('drive/.../datasetRoot', 0, 1);
To run individual modules, you can set the ProcessModules
individually. If you only want to the Structural Module
for example, you can use a [1 0 0]
vector. To run all modules, you can use a single 1
or a vector of ones, which should look like this [1 1 1]
. Running the just the structural module or the full processing pipeline can therefore be done like this as well:
[x] = ExploreASL('drive/.../datasetRoot', 0, [1 0 0]);
+[x] = ExploreASL('drive/.../datasetRoot', 0, [1 1 1]);
Note that the ASL-BIDS standard was introduced relatively recently and there are still certain differences between BIDS and ExploreASL terminology as shown below:
+In ExploreASL, we differentiate visits and sessions mostly by the fact that within a single session a single structural scan (for each contrast) and one or more ASL scans are acquired (typically during the same scanning session and with or without repositioning). Different visits are separated by days/months or in special case several hours and the whole scanning protocol is acquired on each Visit including one or more ASL scan. So across sessions, the same structural images are used. Across Visits, the structural scans are newly acquired. In BIDS-ASL, we use the terms Sessions and Runs instead of Visits and Sessions in ExploreASL.
+Here is an example:
+Running the full pipeline including both import workflow and processing pipeline, can be done by setting both ImportModules
and ProcessModules
to 1
.
[x] = ExploreASL('drive/.../datasetRoot', 1, 1, 0, 1, 1);
Any sensible combinations of import and processing submodules are of course also possible.
+Compared to versions before v1.7.0, we changed both name and behavior of the SkipPause
variable. The variable is called bPause
now. Setting it to true
or 1
, will result in the pipeline being paused before the processing. We removed the iModules
, but the functionality of ProcessModules
is basically the same. We use boolean notation now, so instead of [1 2 3]
you have to use [1 1 1]
now.
The overall import functionality is a work in progress right now. We expect stable behavior in release v1.7.0
though. If you plan on using the develop
branch until then, you have to live with more or less unstable import behavior.
BIDS to Legacy conversion is now not done as the last step of import, but it is run automatically when needed (i.e. BIDS data existing and Legacy data not present) as the first step of the Processing Module.
+ + + + + + +Main function of the import module is to convert input DICOM data to the BIDS format in rawdata
subfolder. Sequence parameters missing in the DICOMs are supplied in the studyPar.json
file.
A separate import module has been created to convert DICOM data to BIDS:
+*.json
files,This import module uses regular expressions and the directory structure can be can be flexibly defined as long as it is fixed per study. +The search function then searches across these directories and copies all files to the ExploreASL directory structure, and performs the conversion to NIFTI if necessary.
+For the import of the data, the best is to execute...
+ExploreASL('/home/username/Path_for_the_root_folder', 1, 0);
+
+...where 1 here is the whole Import module, which is divided in 3 parts [1 1 1]
- more details are provided in the Tutorial on ExploreASL Execution.
After running the import module, it is important to validate that your data are complete and in proper BIDS, using the BIDS validator, which can be found HERE. The BIDS validator will also give you hints if your data or metadata differ between scans, which can occur if a scanner is updated.
+The ExampleStudy has an original directory structure as follows: ExampleStudy/sourcedata/subject/session/scan_ID
, and the directories containing the DICOMs. See image below:
ExampleStudy/
+ sourcedata/
+ 101/
+ Session1/
+ M0/
+ PSEUDO_10_min/
+ T1_weighted/
+ Session2/
+ ...
+ 102/
+ ...
+
+ExploreASL first write the temporary NIfTI files to ExampleStudy/derivatives/ExploreASL/temp/subject/
.
And finally writes the BIDS data into ExampleStudy/rawdata/
:
ExampleStudy/
+ rawdata/
+ sub-101/
+ perf/sub-101_run-1_asl.nii.gz
+ perf/sub-101_run-1_asl.json
+ perf/sub-101_run-1_asl_context.tsv
+ perf/sub-101_run-1_m0.nii.gz
+ perf/sub-101_run-1_m0.json
+ perf/sub-101_run-2_asl.nii.gz
+ perf/sub-101_run-2_asl.json
+ perf/sub-101_run-2_asl_context.tsv
+ perf/sub-101_run-2_m0.nii.gz
+ perf/sub-101_run-2_m0.json
+ anat/sub-101_t1w.nii.gz
+ sub-102/
+ ...
+
+Ideally, before running the import, the data are accompanied by two configuration files
+ExampleStudy/sourcestructure.json
+ExampleStudy/studyPar.json
The content of the sourcestructure.json
and studypar.json
files is explained below.
The sourcestructure.json
file contains the following code (different for each study):
{
+ "folderHierarchy": ["^(\\d{3}).*", "^Session([12])$","^(PSEUDO_10_min|T1-weighted|M0)$"],
+ "tokenOrdering": [ 1 0 2 3],
+ "tokenSessionAliases": ["^1$", "ASL_1", "^2$", "ASL_2"],
+ "tokenVisitAliases": ["", ""],
+ "tokenScanAliases": [ "^PSEUDO_10_min$", "ASL4D", "^M0$", "M0", "^T1-weighted$", "T1w"],
+ "bMatchDirectories": true,
+ "dcm2nii_version":"20220720",
+}
+
+Note that we are using an outdated notation here - Visit/Session/Scan. In BIDS, this corresponds to Sessions/Runs/Scans - this will be updated in the future.
+"folderHierarchy": ["^(\\d{3}).*", "^Session([12])$","^(PSEUDO_10_min|T1-weighted|M0)$"]
+
+This specifies the names of all directories at all levels. In this case, we have specified regular expressions for directories at three different levels:
+^(\\d{3}).*
^Session([12])$
^(PSEUDO_10_min|T1-weighted|M0)$
This means that we will identify three directory levels, each with a certain name, following regular expressions (find more in the matlab definition of regular expressions). Note that \\
is used in the JSON to be correctly read and parsed as a single \
for the regular expression.
At each directory level, it first decides if the directory matches the regular expression, then it also decides if it extract tokens from the string or not - typically tokens are in brackets. More below.
+^(\\d{3}).*
^\\d{3}.*
Tokens information extracted from the directory name at each directory level. +The tokens are numbered by the directory level and can be later used to label patients, sequences etc. See tokenOrdering below.
+We use normal characters and metacharacters. +Expressions from characters and metacharacters are then further coupled with quantifiers, grouping operators, and conditional operators. +Some basic regular expressions are described here with examples - for a full description see the link above:
+Metacharacters:
+.
-- any character -- '..ain'
== 'drain'
== 'train'
!= 'pain'
!= 'rain'
[c1c2]
-- any character within the brackets -- '[rp.]ain'
== 'rain'
== 'pain'
== '.ain'
!= 'wain'
\d
-- any numeric digit, equivalent to [0-9]
Quantifiers (applied on an expression):
+expr*
-- repeat 0+ times -- '.*'
can give anythingexpr?
-- repeat 0 or 1 times - '.?'
== ''
== 'p'
!= 'pp'
expr+
-- repeat 1+ timesexpr{n}
-- repeat n times consecutivelyGrouping operators (allows to capture tokens):
+expr
-- group elements and capture tokens as a part of the text -- '(.)ain'
matches * * 'rain'
or 'pain'
and returns 'r'
or 'p'
as a token(?:expr)
-- group elements but do not capture tokensAnchors:
+^expr
-- beginning of a text -- '^M.*'
is any string starting with Mexpr$
-- end of the text -- '.*M$'
is any string ending with MConditional operators:
+expr1|expr2
-- matches expression 1 or 2Some examples of strings:
+^(\d{3}).*
-- a string starting with 3 digits and any ending, the digits are extracted as tokens. 001a, 212abasd, 231absd
.
^(P\d{2})$
-- a string starting with P and ending with two digits, the whole string is taken as a token. P12, P32
.
.*(T1_MPR|pcasl|M0).*\.PAR$
-- a string with any beginning, containing T1_MPR or pcasl or M0 (this is taken as a token), and ending by .PAR
. test_T1_MPR_testtest.PAR, another_pcasl.PAR, M0_test_.PAR
.
.*(T1|ASL).*(PCASL|PASL)
-- extracts string containing T1 or ASL and PCASL and PASL. Two tokens are extracted. In the above example, the first level is subject, which has three digits (e.g. 101
or 102
), specified by \d{3}
as regular expression. This is between brackets ( )
to define that this is the first token.
Again, note that the actual strings are given here and all \
have to be escaped when written to a json-file as \\
.
"tokenOrdering": [ 1 0 2 3],
+
+Tokens (parts of the directory names) were extracted according to the regular expressions above. Here we decide how the tokens are used.
+This is specified by "tokenOrdering": [patientName, SessionName, ScanName]
"tokenOrdering": [1 0 2 3];
= first token is used for patient name, second for session name, third for scan name"tokenOrdering": [1 0 0 2];
= first token is used for patient name, second for scan name, session name is not assigned"tokenOrdering": [1 0 3 2];
= first token is used for patient name, third for session name, second for scan name"tokenOrdering": [2 0 1 3];
= second token is used for patient name, first for session name, third for scan name"tokenOrdering": [2 1 0 3];
= second token is used for patient name, first for visit name, third for scan nameIf multiple visits are present - use the following notation to mark them:
+"tokenVisitAliases":["session_1","1","session_2","2","session_3","3","session_4","4","session_5","5","session_6","6","session_7","7"],`
+
+"tokenSessionAliases": ["^1$", "ASL_1", "^2$", "ASL_2"],
+
+The second token defines the name of the session. The token was extracted using a regular expression *^Session([12])$*
. This can represent a string Session1
or Session2
. And either 1
or 2
is taken as the token.
In the session-aliases, each row represents one session name. The first column is the regular expression for the token, the second column gives the final name.
+^1$ ASL_1
^2$ ASL_2
Here, the token name ^1$
- that is a string equaling to "1"
is replaced in the analysis folder by the session name ASL_1
.
"tokenScanAliases": [ "^PSEUDO_10_min$", "ASL4D", "^M0$", "M0", "^T1-weighted$", "T1w"],
+
+The third token defines the name of the scan. Each row represents one scan name. The first column is the regular expression for the token, the second column gives the final name of the scan.
+^PSEUDO_10_min$ ASL4D
^M0$ M0
^T1-weighted$ T1w
The DICOMs in the directory PSEUDO_10_min
are thus extracted to a NIFTI file called ASL4D.nii
.
Note: The names ASL4D, M0, T1, FLAIR and WMH_SEGM are fixed names in the pipeline data structure. ASL4D and T1 are required, whereas M0, FLAIR and WMH_SEGM are optionally. When M0 is available, the pipeline will divide the perfusion-weighted image by the M0 image in the quantification part. When FLAIR and WMH_SEGM are available, tissue misclassification in the T1 gray matter (GM) and white matter (WM) because of white matter hyperintensities (WMH) will be corrected.
+Set to true
if it should look for directories and DICOM files inside them. Set to false
when directly separate files are identified by the folder-hierarchy string.
This optional parameter can be used to perform import with an older version of dcm2nii rather than the latest default 20220720
. This is exceptionally needed when the new dcm2nii version does not work well with the data. An alternative is 20190902
.
In the current example of ExampleStudy, we have two subjects: 101 and 102 with each two ASL sessions.
+In ExploreASL, each subject has a single T1 scan and can have multiple ASL sessions.
+This is the case when the anatomy is not expected to change for the different ASL sessions, e.g. when scans are repeated before and after a CO2 or treatment challenge.
+The data structure will be derivatives\ExploreASL\SubjectName\T1.nii
for the anatomical scans (T1 or FLAIR) and derivatives\ExploreASL\SubjectName\ASL_1\ASL4D.nii
and derivatives\ExploreASL\SubjectName\ASL_2\ASL4D.nii
for ASL sessions.
If it concerns a follow-up study, where scan sessions have months or years in between them and brain anatomy is expected to change significantly between the scan sessions, then the data should be set up as a longitudinal study design.
+In this case, different time points are set up as derivatives\ExploreASL\SubjectName_1\T1.nii
and derivatives\ExploreASL\SubjectName_2\T1.nii
for two longitudinal scans of the same subject, where _1
designates the time point.
+So a longitudinal study with two ASL scans per scan session (e.g. a medication challenge is repeated with 6 months time difference) would look like:
derivatives\ExploreASL\SubjectName_1\T1.nii
, derivatives\ExploreASL\SubjectName_1\ASL_1\ASL4D.nii
& derivatives\ExploreASL\SubjectName_1\ASL_2\ASL4D.nii
for the first time point and
derivatives\ExploreASL\SubjectName_2\T1.nii
, derivatives\ExploreASL\SubjectName_1\ASL_2\ASL4D.nii
& derivatives\ExploreASL\SubjectName_2\ASL_2\ASL4D.nii
for the second time point.
The studyPar.json
file contains information about the data that is supposed to be used in the import and filled into the ASL-BIDS sidecar. It should then contain vital parameters of the sequences that are not available inside the DICOM files on the import. This refers to both modality agnostic BIDS parameters describing the dataset in general, an modality specific MRI BIDS parameters describing mostly the ASL data.
+The are both saved in an unstructured JSON file using the original BIDS notation for both tags and their values. See an example below:
{"Authors":["Alzheimers Disease Neuroimaging Initiative"],
+"DatasetType":"raw",
+"License":"http://adni.loni.usc.edu/terms-of-use/",
+"Acknowledgements":"http://adni.loni.usc.edu/data-samples/access-data/groups-acknowledgements-journal-format/",
+"HowToAcknowledge":"ADNI website: http://adni.loni.usc.edu/",
+"Funding":["Alzheimers Disease Neuroimaging Initiative"],
+"ReferencesAndLinks":["http://adni.loni.usc.edu/"],
+"DatasetDOI":"http://adni.loni.usc.edu/",
+"VascularCrushing":false,
+"LabelingType":"PCASL",
+"BackgroundSuppression":true,
+"M0":true,
+"ASLContext":"m0scan,deltam",
+"Manufacturer":"GE",
+"ArterialSpinLabelingType":"PCASL",
+"PostLabelingDelay":2.025,
+"LabelingDuration":1.45,
+"BackgroundSuppressionNumberPulses":4,
+"BackgroundSuppressionPulseTime":[1.465,2.1,2.6,2.88]}
+
+Note that many of these parameters do not have to be provided (describing the dataset in general). And many of them can be automatically extracted from DICOMs. ExploreASL during import reports which are the missing REQUIRED and RECOMMENDED parameters to help with that. It also checks for the basic logic and validity of these parameters and also reports if provided values differ from the retrieved DICOM values. Note that several fields (PLD, labelingDuration etc.) can be provided both as vectors and scalars and in ASL-BIDS should either be a scalar or the vector dimension should match to the volume number. ExploreASL automatically corrects for this. E.g. for a multi-PLD sequence with 3 different PLDs and 9 volumes, you can provide only
+"PostLabelingDelay":[1.0, 1.5, 2.0]
+
+in the studyPar.json
and ExploreASL automatically expands it during the import:
"PostLabelingDelay":[1.0, 1.5, 2.0,1.0, 1.5, 2.0,1.0, 1.5, 2.0]
+
+Also, the field ASLContext should be provided in a .TSV file in ASL-BIDS. ExploreASL import allows to enter it as a field to studyPar.json
and the automatically writes it into the .tsv file upon the import to ASL-BIDS - also expanding and repeating to the correct number of repetitions. Typically, you would use the following entry:
"ASLContext":"control, label",
+
+For a multi-PLD sequence with 7 volumes including an M0 as the first volume and then 3 pairs of control/label with different PLDs, the PLD
and LD
for the M0 should be set to 0 and for the remaining volumes set accordingly:
"PostLabelingDelay":[0, 1.0, 1.0, 1.5, 1.5, 2.0, 2.0],
+"LabelingDuration":[0, 1.45, 1.45, 1.45, 1.45, 1.45, 1.45]
+
+The studyPar.json
can be modified so that you can import different sequences with different parameters in a single run. Essentially, studyPar.json structure contains a list of contexts according to the standard definition, each context has a keyword that defines to what kind of data it should be applied. When a dataset fits to several contexts, the results of each context are taken into account and overwritten with the first context having the lowest priority.
The following applies
+1. The list of context is in a field called StudyPars
.
+2. The list is processed top to bottom and the matching fields are always overwritten.
+3. An extra added keywords SubjectRegExp
, VisitRegExp
, or SessionRegExp
that define strings Subject\Session\Run that sets required conditions to be fulfilled for each context.
+4. Missing any of tohse strings or an empty string means that the condition is fulfilled. The conditions are written in regexp format.
{"StudyPars":[
+{"DatasetType":"raw",
+"ArterialSpinLabelingType":"PCASL",
+"PostLabelingDelay": [2],
+"BackgroundSuppression":true,
+}
+{"SubjectRegExp":"",
+"SessionRegExp":"3",
+"BackgroundSuppression":false,
+}
+{"SubjectRegExp":"alpha.*|beta.*",
+"VisitRegExp":"1",
+"PostLabelingDelay": [3],
+}
+{"VisitRegExp":"2",
+"SessionRegExp":"",
+"PostLabelingDelay": [4],
+}]}
+
+The following cases will obtain the following parameters: +1. Subject gamma, session 1, run 1: Fits only to the first context. PostLabelingDelay 2, BSup true. +2. Subject gamma, session 1, run 3: Fits to the first and third context. PostLabelingDelay 2, BSup false. +3. Subject alpha1, session 1, run '': First to the first, second, and third context. PostLabeling delay 3, BSup false.
+ + + + + + +This tutorial describes where to download, how to install, and how to run ExploreASL either directly from Matlab, or using a compiled version or a docker that do not require Matlab license. All external software, like SPM and dcm2niix, is contained in all the downloads and does not need to be downloaded or installed separately. The only exception is the FSL software that needs to be downloaded and installed manually in case you want to process multi-PLD or time-encoded ASL data using BASIL. Please consult the FSL installation guide for installation of Windows Subsystem for Linux (WSL or WSL2) if you want to use FSL on Windows.
+ExploreASL GUI is a standalone wrapper around ExploreASL that provides a modern and user-friendly interface for importing, processing, analyzing, and visualizing ASL data with ExploreASL.
+The first thing you have to do, to use ExploreASL, is to clone the ExploreASL repository. If you want to run ExploreASL from Matlab, we recommend to clone the main repository directly from the official GitHub website. You also have the option to download the zipped version (click Donwload zip) or clone it with GitHub. Both stable release and latest beta version are available.
+If you are new to Matlab, we recommend checking out a Matlab tutorial. It can be helpful to add the ExploreASL directory to your Matlab paths. Open Matlab, select the Home tab, and add the ExploreASL directory including its subfolders using the Set Path option. Now change your working directory, using the Current Folder tab or the cd command, to the ExploreASL directory.
+Running a simple initialization is a good first check that everything is working
+ExploreASL();
+
+To run ExploreASL you have to type in the following command in the Command Window: ExploreASL
. You will need an already created ASL-BIDS dataset and specify the path to it, you can run the default ExploreASL pipeline like this:
DatasetRoot = 'C:\...\MY-BIDS-DATASET'; % Path to the Dataset folder, containing the ASL-BIDS data in C:\...\MY-BIDS_DATASET\rawdata
+ImportModules = [0 0 0 1]; % Import data from ASL-BIDS format to ExploreASL internal format
+ProcessModules = true;
+[x] = ExploreASL(DatasetRoot, ImportModules, ProcessModules);
+
+For running ExploreASL full import from DICOM data, please consult the Tutorial on Import. +You can also execute a test dataset provided with ExploreASL in the folder ExploreASL/External/TestDataSet:
+ExploreASL('/home/user/.../ExploreASL/External/TestDataSet', 0, 1);
+
+See more information in the Tutorial here.
+Precompiled ExploreASL is available for certain ExploreASL versions and OSes here. Providing a compiled version for every operating system and corresponding Matlab version is currently not feasible for us. Please feel free to ask the developers for a specific compiled version.
+A compiled version of ExploreASL always requires the corresponding Matlab Runtime. Please checkout the official Matlab Documentation. Download the Matlab Runtime of the Matlab Version which was used for the compilation. Make sure to install the Matlab Runtime correctly. If you're using Windows, it is important that the path to the Matlab Runtime is added to Windows PATH during the installation. To compile ExploreASL yourself, you have to run the xASL_adm_MakeStandalone.m
script.
Assume you have downloaded or compiled a file called xASL_latest.exe
. We recommend using the command line interface now. For this you can go to the address bar of your file explorer. Type in cmd
to open the command prompt in the current folder. The following command will start ExploreASL, import the ASL-BIDS dataset in sourcedata format, and process the dataset corresponding to your DatasetRoot
directory:
xASL_latest.exe "c:\MY-BIDS-DATASET" "1" "1"
+
+The executable will extract all necessary data from the CTF archive within the folder. This is totally normal. Within the command window you should see that ExploreASL is starting to process the given dataset:
+xASL_latest.exe "c:\MY-BIDS-DATASET" "1" "1"
+(insert example here)
+
+To test if it is possible to initialize ExploreASL without the processing of a dataset, you could run the following command:
+xASL_latest.exe "" "0" "0"
+
+The usual ExploreASL parameters (DatasetRoot
, ImportModules
, ProcessModules
, bPause
, iWorker
, nWorkers
) have to be given to the compiled ExploreASL version as strings. The resulting output could look like this:
xASL_latest.exe "" "0" "0"
+(insert example here)
+
+On Linux you can basically do the same as above. We can run the ExploreASL shell script with a specified Matlab MCR (here we use version 96 e.g.) using the following command:
+./run_xASL_latest.sh /usr/local/MATLAB/MATLAB_Runtime/v96/ "" "0" "0"
+
+Using the options "" "0" "0"
we initialize ExploreASL, but do not process a dataset. To run a dataset, we have to switch the ImportModules
and/or the ProcessModules
parameter from 0
to 1
and pass a path for the DatasetRoot
directory. This could look something like this:
./run_xASL_latest.sh /usr/local/MATLAB/MATLAB_Runtime/v96/ "/home/MY-BIDS-DATASET" "1" "1"
+(insert example here)
+
+First you have to pull an official docker image from the ExploreASL repository:
+docker pull exploreasl/xasl:latest
+
+Check out your local images using docker images
. If you want to rename the docker image, tag your image using the docker tag command:
docker tag exploreasl/xasl:latest xasl:my-version
+
+To start a docker container of ExploreASL v1.7.0 e.g., you can use the following command:
+docker run -e DATASETROOT=MY-BIDS-DATASET
+ -e IMPORTMODULES=1 -e PROCESSMODULES=1
+ -v /home/.../incoming:/data/incoming
+ -v /home/.../outgoing:/data/outgoing xasl:1.7.0
+
+DATASETROOT
is an environment variable which is a relative path to the DATASETROOT
directory of your dataset.IMPORTMODULES
and PROCESSMODULES
are the parameters of ExploreASL_Master/home/.../incoming:/data/incoming
is used to mount your dataset folder (/home/.../incoming
) to its corresponding docker dataset folder (/data/incoming
). /data/outgoing
) to its corresponding real output folder on your drive (/home/.../outgoing`).The main task of the processing module is to take BIDS input data located in rawdata
folder, convert them to ExploreASL internal (Legacy) structure in derivatives
subfolder and run processing with the processing parameters defined in the dataPar.json
file.
Before running the processing, it is important to validate that your data are complete and in proper BIDS, using the BIDS validator, which can be found HERE. The BIDS validator will also give you hints if your data or metadata differ between scans, which can occur if a scanner is updated.
+To run processing of BIDS data located in drive/.../datasetRoot/rawdata
, you simply execute this command:
[x] = ExploreASL('drive/.../datasetRoot', 0, 1);
+
+You can provide additional processing parameters in a file at drive/.../datasetRoot/dataPar.json
. An example content of the dataPar.json
file is given below on this page. A full reference manual is provided here.
Further options to import DICOM data are specified in the Import Tutorial, and different modes to execute ExploreASL are described in the Execution Tutorial. Below, you can find examples how to set-up the processing options.
+Here, we present how to setup the most basic things for the ExploreASL processing using the dataPar.json
. Note that you can combine the examples below and concatenate the content of given examples to a single dataPar.json
to have all the functionalities at once. Here, we only provide examples and full list of all options to set is given in this reference manual for Processing Parameters.
The atlases used in the ExploreASL population module can be defined in the x.S
sub-structure. If you are interested in the TotalGM
, TotalWM
, DeepWM
, Hammers
, HOcort_CONN
, HOsub_CONN
, and Mindboggle_OASIS_DKT31_CMA
atlases e.g., you can add the following lines to your dataPar.json
file.
{"x":{
+ "S": {"Atlases": ["TotalGM","TotalWM","DeepWM","Hammers","HOcort_CONN","HOsub_CONN","Mindboggle_OASIS_DKT31_CMA"]}
+}}
+
+ExploreASL currently uses BASIL to quantify multi-PLD, multi-TE and time-encoded data (the rest of the processing is done using ExploreASL, BASIL is only used for the quantification itself). Multi-TE sequences execute directly FABBER from FSL. Note that you need to install FSL on you computer for this. Use the following dataPar.json
to automatically locate installed FSL and to activate CBF quantification using BASIL:
{"x":{"Q":{"bUseBasilQuantification":1},
+"external":{"bAutomaticallyDetectFSL":true}}}
+
+In case that FSL is not detected automatically, or if there's a prefered FSL version, you can directly provide path to the FSL directory like this:
+{"x":{"Q":{"bUseBasilQuantification":1},
+"external":{"bAutomaticallyDetectFSL":true},
+"FSLdir":"/home/XASLuser/fsl/",
+"RootFSLdir":"/home/XASLuser/fsl/"}}
+
+Note that Tex estimation of BBB permeability from multi-TE data is supported starting at FSL version 6.0.7.1.
+ExploreASL uses the structural T1-weighted scans to obtain information about GM and WM tissues used later for evaluation and thresholding the CBF maps. Presence of T1w scans is thus expected for all ASL scans as T1w scans are anyway normally obtained. If a T1-weighted scan is missing, ExporeASL uses internally the average MNI brain instead, but this option needs to be activated explicitly:
+{"x":{"modules":{"asl":{"bUseMNIasDummyStructural":1}}}}
+
+By default, the regional values in the population module are calculated in the MNI space. Additionally, it is also possible to calculate the values in the native space of each subject. This is then done for all specified atlases that are converted for this purpose to the native space of each subject. If activated, both MNI and native space results are calculated.
+{"x":{"modules":{"population":{"bNativeSpaceAnalysis":true}}}}
+
+By default ExploreASL population module evaluates the regional values of CBF. Additionally, it is possible the automatically evaluate values of other parameters if appropriate parameter maps are/can be calculated such as the CBF (qCBF), arterial transit time (ATT), M0, Tex (Time of Exchange across BBB in BBB-ASL. CBF is done by default, but if specifying an own list of parameters, do not forget to add CBF
+{"x":{
+ "S": {"DataTypes": ["qCBF", "ATT", "M0", "Tex"]}
+}}
+
+You can freely combine all the given examples unless they are obvious conflicts between parameters. The five examples above can be combined into a single dataPar.json
file that will process multi-PLD file wit BASIL, even in the absence of a T1w scan and will use several atlases in the Population module:
{"x":{
+ "S": {"Atlases": ["TotalGM","TotalWM","DeepWM","Hammers","HOcort_CONN","HOsub_CONN","Mindboggle_OASIS_DKT31_CMA"], "DataTypes": ["qCBF", "ATT", "M0", "Tex"]},
+ "Q":{"bUseBasilQuantification":1},
+ "external":{"bAutomaticallyDetectFSL":true},
+ "modules":{"asl":{"bUseMNIasDummyStructural":1},"population":{"bNativeSpaceAnalysis":true}}
+}}
+
+Correct scaling between the M0 and ASL scans is still an issue for certain ASL implementations. While for most vendors and sequences, this is automatically detected, you might need to add a manual scaling of the M0-scans. Furthermore, in case that dummy scans are part of the ASL sequence, you can indicate their position in the ASL timeseries, so that they are skipped:
+{"x":{
+ "modules":{
+ "asl":{
+ "M0_GMScaleFactor": 10,
+ "DummyScanPositionInASL4D": [2,3]
+}}}}
+
+While partial-volume correction is outputted in the Population module as done per region, you can also activate standard Partial-volume correction in the ASL-native space and produce GM-CBF maps in native space (which are later converted to standard space). Additionally, you can switch ON/OFF certain ASL-processing steps:
+{"x":{
+ "modules":{
+ "asl":{
+ "motionCorrection": 0,
+ "bPVCNativeSpace": 1,
+ "PVCNativeSpaceKernel": [10 10 4],
+ "bPVCGaussianMM": 1
+}}}}
+
+The general settings allows to run ExploreASL in a faster mode at lower quality, or to not skip certain subjects if they are missing certain scans, or stop the pipeline after too many errors are reported:
+{"x":{
+ "settings":{
+ "Quality": 1,
+ "SkipIfNoASL": 1,
+ "SkipIfNoM0": 1,
+ "SkipIfNoFlair": 1,
+ "stopAfterErrors": 5
+}}}
+
+Sequence parameters should be specified in the Import part that converts DICOMs to BIDS -- see Import Tutorial.
+In the rare case where a sequence parameter would be missing in the ASL-BIDS format of data, and that it wouldn't be added in the Import or later, this parameter can be supplied as part of the dataPar.json
(although adding it directly to subject's JSON-sidecars is better). Similarly, we can alter the CBF quantification parameters and constants either for the whole study by adding it in dataPar.json
(or better adding the same parameters listed here directly to the subject's JSON-sidecar). Note that in dataPar.json, unlike in ASL-BIDS, most values are given in [ms] instead of [s]. Also, the parameters' name can differ slightly from the ASL-BIDS definition - more info is in Processing Parameters.
{"x":{
+ "Q":{
+ "BackgroundSuppressionNumberPulses": 2,
+ "BackgroundSuppressionPulseTime": [100, 500, 1500],
+ "Initial_PLD": 1800,
+ "T2art": 50,
+ "TissueT1": 1240
+}}}
+
+
+
+
+
+
+
+ This document provides a “quick start” walk-through for a dataset processed by ExploreASL. This can be either the attached example dataset (n=1) or a clinical study. It is always recommended to first test the compatibility of ExploreASL with the example dataset (Step 0 below), and to create a file report for steps 1-6, to get accustomed to the data and to make sure that ExploreASL runs properly. Note that ExploreASL is in development, so naming conventions may change, especially when we move to a complete BIDS adherence.
+First, try to run the test data set. Note that according to good practice, it is important to separate code and data. The user should copy //ExploreASL/External/TestDataSet/
to a directory with read and write permissions outside of the ExploreASL toolbox, and keep the ExploreASL directory structure unchanged. Let’s assume your copy of the TestDataSet is now in the folder /drive/folder/TestDataSet
. Open Matlab, go to the directory of ExploreASL, run ExploreASL(‘/drive/folder/TestDataSet’, 0, 1);
to process the TestDataSet. The dataPar.json
file in the example dataset contains all image processing and quantification parameters that ExploreASL needs. (Note that for your own study, you would need to create this parameter file. See the Processing Tutorial and Processing parameters. If you only want to run a quick test, we recommend to set the Quality
parameter within dataPar.json to 0. Please note that in the future, the structure of this test dataset will be replaced by the BIDS format. Also, you can add the same parameters to the JSON sidecars of the ASL NIfTI files, which will allow processing ASL scans with different parameters within the same study. In the case of a multi-center study, and/or multiple sequences or scanner updates, the JSON sidecars allow to have different ASL parameters within a single study.
Upon successful completion of the processing, ExploreASL creates a result file (//Population/Stats/ median_qCBF_(Native|Standard)Space_total_GM_n=1_*_PVC0.tsv
). Verify that the GM CBF here, without partial volume (PV) correction, i.e. PVC0)), is approximately 52 mL/100g/min
and with partial volume correction (i.e. PVC2) is approximately 65 mL/100g/min
. If this file does not exist, then there could be a problem with ExploreASL compatibility. If the file exists and values are the same as reported here, then your software and hardware are ExploreASL compatible. In case ExploreASL processing runs for the example data set and not for other datasets then the problem is probably data related and not compatibility related.
When you perform this walkthrough on your own data, there are three first main cases to note:
+>>> ExploreASL('/drive/folder/TestDataSet',0,1)
+
+ExploreASL will run the processing pipeline...
+==============================================================================================
+ ________ __ ______ ______ __
+/ | / | / \ / \ / |
+########/ __ __ ______ ## | ______ ______ ______ /###### |/###### |## |
+## |__ / \ / | / \ ## | / \ / \ / \ ## |__## |## \__##/ ## |
+## | ## \/##/ /###### |## |/###### |/###### |/###### |## ## |## \ ## |
+#####/ ## ##< ## | ## |## |## | ## |## | ##/ ## ## |######## | ###### |## |
+## |_____ /#### \ ## |__## |## |## \__## |## | ########/ ## | ## |/ \__## |## |_____
+## |/##/ ## |## ##/ ## |## ##/ ## | ## |## | ## |## ##/ ## |
+########/ ##/ ##/ #######/ ##/ ######/ ##/ #######/ ##/ ##/ ######/ ########/
+ ## |
+ ## |
+ ##/
+
+======================================= ExploreASL Settings ==================================
+Dataset Root /drive/folder/TestDataSet
+Import Modules
+Process Modules STRUCTURAL ASL POPULATION
+bPause False
+iWorker 1
+nWorkers 1
+==============================================================================================
+ExploreASL v1.9.0 initialized ...
+Automatically defining sessions...
+======================================= Additional Settings ==================================
+1 scans - 0 exclusions, resulting in 1 scans of:
+Longitudinal timePoint 1 = 1 scans - 0 exclusions = 1 scans
+ASL sessions: 1
+
+Ancillary data, sets: 4 sets are defined for 1 "SubjectsSessions"
+Set 1 = "session" options "ASL_1", codes for paired data
+Set 2 = "LongitudinalTimePoint" options "TimePoint_1", codes for paired data
+Set 3 = "SubjectNList" options "SubjectNList", codes for paired data
+Set 4 = "Site" options "SingleSite", codes for two-sample data
+x.D.ROOT /drive/folder/TestDataSet
+x.settings.DELETETEMP 1 (delete temporary files)
+x.settings.Quality 1 (0 = fast try-out; 1 = normal high quality)
+
+You should obtain a similar initial screen showing which subjects and scans are found to be processed (how many exclusions, how many subjects for each time point etc.), as well as potentially included co-variates (e.g. site, age, cohort, sex). Note that we run the pipeline on low quality (x.Quality=0
): while this will provide poorer results (segmentation, registration, etc) this will allow us to quickly test the full pipeline. On a relatively new computer, the full pipeline should run either within 5-10 min (x.Quality=0
) or 30-60 min (x.Quality=1
).
Check the files //ROOT/Missing*Files.csv
. These provide an overview of any missing files. Files can either be missing when they are not imported (Missing*NativeFiles.csv
, for native space files), or when they are not processed (mainly Missing*MNIFiles.csv
, for MNI space files). If no files are specified in these files, or they do not exist, this means that there were no missing files.
The structural module processes the anatomical (T1-weighted, T1w) images, to provide segmentations/partial volume (PV) maps and for spatial normalization to MNI space. Optionally, if FLAIR images exist, these are used to correct the white matter hyperintensities (WMH) on the T1w images. Check (from left to right):
+//Population/T1Check/Tra_Src_rT1_*.jpg
for T1w quality, structural anomalies, normalization to MNI//Population/T1Check/Tra_Reg_rT1_*.jpg
same as previous, but after lesion filling (if FLAIR exists)//Population/T1Check/Tra_Seg_rT1_*.jpg
for T1w segmentation (WM segmentation in red)//Population/TissueVolume/Tissue_volume_*.tsv
for the GM, WM and CSF volumesCheck, if FLAIR exists (from left to right):
+//Population/FLAIRCheck/Tra_Src_rFLAIR_*.jpg
for FLAIR quality, structural anomalies//Population/FLAIRCheck/Tra_Reg_rFLAIR_*reg.jpg
for WMH segmentation, compare with previous//Population/FLAIR_REGDIR/Tra_Seg_rFLAIR_*reg.jpg
for registration FLAIR->T1w
+(red=T1w WM segmentation)//Population/TissueVolume/WMH_LST_*.tsv
for the WMH Total Lesion Volume (TLV) and number (N) of WMHFor a population data quality overview (if nScans>1), inspect //Population/Templates/Template_mean_T1.nii, as well as //Population/Templates/Template_sd_T1.nii for the between-subject variation. Do the same for pGM and pWM, and FLAIR and WMH_SEGM if available.
+//Population/DICOMparameters/ASL4D_quantification_parameters.csv
and //Population/DICOMparameters/M0_quantification_parameters.csv
summarize the data in the files //ROOT/SubjectName/ASL_1/ASL4D_parms.mat
and //ROOT/SubjectName/ASL_1/M0_parms.mat
, including the different DICOM header parameters that are imported and can be used in the quantification process. It is important to check that the TR, TE, and scale slopes are comparable for all scans on a single scanner. If not, they allude to situations where the scans were performed with not completely similar protocols, due to e.g. a software update, or use of different scanners. Ignoring this can lead to undesired variance in the whole-brain CBF quantification.
The ASL module processes the perfusion (ASL, M0) images, from motion correction to registration to quantification and PV correction. Check for general ASL quality, vascular artifacts, good GM-WM contrast, WM-CSF contrast, artifacts on the temporal standard deviation (SD) images, geometrical distortion, and signal drop out from EPI susceptibility artifacts, whole-brain coverage (slice_gradient). Check also for registration to standard space, all images should be in the same position/orientation, i.e. meaning that you always see the same slices, with the same angulation. Check for motion artifacts as a bright halo around the CBF and temporal SD images. In a study QC report, you could show some worst, median, and best examples. Check (from left to right):
+//Population/ASLCheck/Tra_qCBF_untreated_*ASL_*.jpg
for the CBF images without vascular treatment (qCBF*)//Population/ASLCheck/Tra_Reg_pWM_qCBF_untreated_*ASL_*.jpg
for the ASL->T1w registration (T1w WM segmentation in red)//Population/SliceGradientCheck/SliceGradient_*.jpg
for the orientation of native slices in MNI spaceIf time-series exist (from left to right):
+//Population/RawSourceIMCheck/Tra_mean_control_*.jpg
for the inspection of the average ASL source image//Population/SD_SNR/Tra_SD*ASL_*.jpg
for the temporal SD image. This should be a smooth, noisy image, with only vascular peaks.//Population/MotionASL/rp_*ASL*motion.jpg
to inspect subject motion (net displacement vector)//Population/MotionASL/rp_*ASL*threshold_free_spike_detection.jpg
to inspect the performance of ENABLEIf an M0 scan exists (from left to right):
+//Population/M0Check/Tra_noSmooth_M0_*_ASL*.jpg
for the inspection of M0//Population/M0_Reg_ASL/Tra_Reg_pGM_noSmooth_M0_*ASL*.jpg
for the M0->T1w registration
+(pGM in red)//Population/M0_Reg_ASL/M0_im_proc_*.jpg
for processing of M0 into a smooth bias field (masking & smoothing). Verify that the mask correctly removes the CSF & extracranial signal, to avoid smoothing of this into the M0 bias field.If population data exists (i.e. nScans>1
):
+For a population data quality overview, inspect //Population/Templates/Template_mean_CBF.nii
, as well as //Population/Templates/Template_sd_CBF.nii
for the between-subject variation. Do the same for the other QC images if available.
A) Reproduce some of the above JPG images by loading the NIfTIs, creating an overlay, and scrolling through
+To go through the images in more detail, we advise using Chris Rorden’ mricron32.exe, which is a very light-weight, flexible, and easy-to-use tool. Please go to the population folder, and repeat the visual QC above in detail by opening the standard space NIfTIs. E.g., start with the original T1, resliced into standard space (rT1_ORI*.nii(.gz)
), and then overlay the gray matter (GM) and/or white matter (WM) segmentations (rc1T1*.nii(.gz)
and rc2T1*.nii(.gz)
respectively. You do this, by keeping the original T1 NIfTI open, in the top menu click ‘Overlay’
- ‘Add’ and select the NIfTI you want to overlay. Then you can select a color at the right drop-down menu. You can change the transparency of the overlay by ‘Overlay’ - ‘Transparency on background’. Then, keep the same NIfTI open, and start a second instance of mricron32, and load another NIfTI there, e.g. the FLAIR (rFLAIR*.nii(.gz)
), note how you can scroll through both NIfTIs in sync. (if this doesn’t work, you need to enable ‘View’ - ‘Yoke’ at both MRIcron instances). With the DEL key, you can activate the crosshair. You can layout the two MRIcron instances side-to-side by using the Windows key-Left Windows key-Right combination.
B) Relate the ASL CBF image to the structural T1w image
+Load the ASL image (qCBF*.nii(.gz)
and notice how much lower its resolution is compared to the structural/anatomical images. Then open the T1w and ASL images side to side, to scroll through them in sync, and notice how this allows you to identify the structural reference of your ASL perfusion signal. Can you observe structural contrast in the ASL image? Do you see that the CBF is indeed higher in the GM than in the WM?
C) Relate the temporal SD image to the structural T1w image
+Now do the same with the temporal SD image (SD*.nii.(gz)
, not SD_control*
), open it side-to-side with the T1w image. This image shows the temporal variations of the ASL signal. Where does this come from?
D) Overlay the CBF image over the T1w image
+To create a nice visualization, open the T1w NIfTI, and then load the ASL CBF image as an overlay. Then choose a nice color scale, proper transparency, and play with the low and high-intensity thresholds, to create an overlay of the CBF image in ‘false colors’ over the grayscale anatomical NIfTI. Again, notice the relatively low resolution (i.e. blurriness/smooth appearance) of the ASL image. Try to make a really nice overlay!
+E) Check the default, basic ROI overview of the data in //Population/Stats/*.tsv
. These filenames are built up as:
Values | +Description | +
---|---|
(mean\|median\|spatialCoV) |
+The statistic: either the mean, median, or coefficient of variance over the ROI | +
(qCBF_untreated) |
+The input data (this can be anything, e.g. M0, pGM, FLAIR) | +
(TotalGM\|DeepWM\|MNI_structural) |
+The applied atlas, which specifies which ROIs to use | +
(n=x) |
+The number of subjects in the analysis (these are rows in the TSV file) | +
(07-Mar-2019) |
+The date of the analysis | +
PVC(0\|2) |
+Partial volume correction (PVC) options: 0 (no PVC), 2 (two-compartment, classical PVC) | +
In the Stats folder's files, if the same T1w
is used for multiple runs (ASL_1
, ASL_2
etc.), the values concerning the structural derivatives only (e.g. volumetrics and ratio) will be printed only for the first run.
Start by opening ‘mean_qCBF_untreated_MNI_structural_n=1_07-Mar-2019_PVC2.tsv’. Notice that columns A to L are the ‘covariates’, whereas the remaining columns are the results of the ROI analysis. See the names of the MNI_structural atlas (Caudate, Cerebellum, Frontal, etc), and notice how from each of them, 3 columns are created, with the B (bilateral), L (left), or R (right) part of the ROI.
+F) Run an ROI analysis with a custom atlas
+1) Pick an atlas
+Go to folder /ExploreASL/External/AtlasesNonCommercial
and choose an atlas. Open the NIfTI file of the atlas, and notice how it has a label number for each ROI: you can see this number in the lower-left corner of MRIcron. By overlaying the atlas over the T1w of the subject, and creating a nice color scheme and transparency (e.g. color scheme ‘NIH’ and 60% transparency), and can see if you like the ROIs of this atlas for your analysis. Suggestions are ‘Hammers’, ‘HOcort_CONN’ (the CONN-toolbox version of the Harvard-Oxford atlas, cortical part), or HOsub_CONN (same as previous but subcortical part). Note how each NIfTI file of the atlases have their own .tsv file, which specifies the name of the ROIs (the column number corresponds to the label number in the NIfTI file). Remember the full path of the atlas NIfTI. Note that you can also provide your own atlas, as long as the ROIs contain the same label numbers in the NIfTI as in the .tsv file.
2) Pick a data type
+Pick the data type you want to perform your ROI analysis on, e.g. qCBF (see other available data types in the Population folder).
+3) Restart ExploreASL
+For this, we first need to restart ExploreASL, but without running the whole analysis (since we already did this). +Open Matlab, initialize ExploreASL using the command [x] = ExploreASL_Initialize;. To process a dataset you can use the ExploreASL function. Tell ExploreASL which dataset to load, by providing the path of your data parameter file to ExploreASL by running [x] = ExploreASL_(‘drive/folder/dataPar.son’). Notice how this loads the dataset without any processing (i.e. without running the structural, ASL, or any other modules).
+4) Run the ROI analysis, by typing in Matlab:
+x.S.InputDataStr = 'qCBF';
+% (qCBF can be replaced by another datatype)
+x.S.InputAtlasPath = '/ExploreASL/External/AtlasesNonCommercial/HOcort_CONN.nii';
+% (replace this by the atlas of your choice)
+xASL_wrp_GetROIstatistics(x);
+% (Note that this may provide a warning that x.Sequence is not defined yet,
+% if you haven't predefined any ASL sequence yet (which should go semi-automatically
+% with your own data). x.Sequence should contain your ASL sequence, e.g. x.Sequence
+% = ‘2D_EPI’ (in the case of the TestDataSet))
+
+E) Check the ROI analysis
+Repeat the steps in (E) above, but then with the correct atlas name. Note how the ROIs (columns M and upwards) are now the bilateral (B), left (L) and right (R) parts of the atlas you selected. +Recommendable software
+Free software that is recommendable, includes:
+When not indicated otherwise, installation settings should be kept on default.
+ + + + + + +\n {translation(\"search.result.term.missing\")}: {...missing}\n
\n }\n