v1.5.1

ExploreASL · Apr 20, 2021 · 79cc2cc · 79cc2cc
1 parent 6ae51ae
commit 79cc2cc
Show file tree

Hide file tree

Showing 9 changed files with 1,010 additions and 782 deletions.
diff --git a/docs/Functions.md b/docs/Functions.md
@@ -493,7 +493,7 @@ Creates list of structural image paths to reslice.
 #### Format
 
 ```matlab
-[Parms, x, Oldx] = xASL_adm_LoadParms(ParmsPath[, x, bVerbose])
+[Parms, x] = xASL_adm_LoadParms(ParmsPath[, x, bVerbose])
 ```
 
 #### Description
@@ -673,20 +673,6 @@ pipeline visualization parts are repeated.
 
 
 
-----
-### xASL\_adm\_SaveJSON.m
-
-#### Format
-
-```matlab
-xASL_adm_SaveJSON(data, jsonFileName)
-```
-
-#### Description
-Saves the values in the structure 'data' to a file in JSON format.
-
-
-
 ----
 ### xASL\_adm\_SaveX.m
 
@@ -852,57 +838,71 @@ Creates several structures necessary for configuring the DICOM to BIDS conversio
 
 
 ----
-### xASL\_bids\_Dicom2JSON.m
+### xASL\_bids\_CreateDatasetDescriptionTemplate.m
 
 #### Format
 
 ```matlab
-[parms pathDcmDictOut] = xASL_bids_Dicom2Parms(imPar, pathIn[, pathJSON, dcmExtFilter, bUseDCMTK, pathDcmDictIn])
+[json] = xASL_bids_CreateDatasetDescriptionTemplate(draft)
 ```
 
 #### 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.
+This script creates a JSON structure which can be saved
+using spm\_jsonwrite to get a dataset\_description.json template.
+Missing fields that are required are added. BIDSVersion checked against the current configured version.
+Remaining fields will be validated. Other fields not belonging to dataset\_description.json are ignored.
+
+
+
+----
+### xASL\_bids\_DRO2BIDS.m
+
+#### Format
+
+```matlab
+xASL_bids_DRO2BIDS(droTestPatient,[droSubject])
+```
 
+#### Description
+Prepare DRO test patient for BIDS2RAW conversion.
+This script uses the output of the asldro python script and
+converts it into a bids structure that can be read by our
+xASL\_bids\_BIDS2Legacy script.
+An exemplary usage is shown in the unit test called
+xASL\_ut\_UnitTest\_function\_BIDS2Legacy.
 
 
 
 ----
-### xASL\_bids\_GetPhoenixProtocol.m
+### xASL\_bids\_Dicom2JSON.m
 
 #### Format
 
 ```matlab
-[xasl,parameters,parameterList,phoenixProtocol] = xASL_bids_GetPhoenixProtocol(pathData,bUseDCMTK)
+[parms pathDcmDictOut] = xASL_bids_Dicom2Parms(imPar, pathIn[, pathJSON, dcmExtFilter, bUseDCMTK, pathDcmDictIn])
 ```
 
 #### 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]).
+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.
 
 
 
 
 ----
-### xASL\_bids\_InsertJSONFields.m
+### xASL\_bids\_GetPhoenixProtocol.m
 
 #### Format
 
 ```matlab
-[ChildJSON] = xASL_bids_InsertJSONFields(ParentJSON, ChildJSON[, Fields2Skip])
+[xasl,parameters,parameterList,phoenixProtocol] = xASL_bids_GetPhoenixProtocol(pathData,bUseDCMTK)
 ```
 
 #### Description
-This function takes all parameters from the "parent" JSON & moves them into the "child" JSON.
-In case of co-existence of a field with different values,
-then the value in the child JSON will prevail, per BIDS inheritance.
-
-This function runs the following steps:
+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]).
 
-1. Load JSON or parms.mat (legacy), if the inputs were paths
-2. Insert the fields
-3. Save a new JSON file (if ChildJSON was a path)
 
 
 
@@ -947,11 +947,12 @@ of the last number in the filename (Y) alternating the tags and controls
 This function performs the following steps in subfunctions:
 
 1. xASL\_bids\_MergeNifti\_M0Files Generic merging of M0 files
-2. xASL\_bids\_MergeNifti\_SiemensASLFiles Merge Siemens ASL files with specific filename pattern
-3. xASL\_bids\_MergeNifti\_AllASLFiles Merge any ASL files
-4. xASL\_bids\_MergeNifti\_Merge Merge NiftiPaths & save to pathMerged
-5. xASL\_bids\_MergeNifti\_Delete Delete NiftiPaths and associated JSONs
-6. xASL\_bids\_MergeNifti\_RenameParms Find \*\_parms.m files in directory and shorten to provided name
+2. xASL\_bids\_MergeNifti\_GEASLFiles Merge GE ASL files and extract scan order from DICOM tags
+3. xASL\_bids\_MergeNifti\_SiemensASLFiles Merge Siemens ASL files with specific filename pattern
+4. xASL\_bids\_MergeNifti\_AllASLFiles Merge any ASL files
+5. xASL\_bids\_MergeNifti\_Merge Merge NiftiPaths & save to pathMerged
+6. xASL\_bids\_MergeNifti\_Delete Delete NiftiPaths and associated JSONs
+7. xASL\_bids\_MergeNifti\_RenameParms Find \*\_parms.m files in directory and shorten to provided name
 
 
 ----
@@ -1049,7 +1050,8 @@ 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.
+splitting of ASL and M0 NIFTIes if needed. Note that the sidecars are in BIDS, but the file-structure
+is already expected to be in Legacy format
 
 
 ## FSL
@@ -1851,6 +1853,8 @@ can be used in combination with xASL\_vis\_Imwrite.m
 #### Description
 Downsample (or upsample, works similarly) old\_res image to
 low\_res image, trilinear.
+We recommend using "xASL\_spm\_Resample" instead, because of
+better performance.
 
 **NB:** new\_res should fit exactly integer fold in old\_res
 
@@ -1986,50 +1990,8 @@ Simple rotation of the first two dimension of a ND image by
 
 
 
-----
-### xASL\_import\_json.m
-
-#### Format
-
-```matlab
-[x] = xASL_import_json(DataParFile)
-```
-
-#### Description
-This function reads in a DATA\_PAR file and creates the x
-structure. The name of the DATA\_PAR file is given as a string or
-character array. The output is the x structure.
-
-If the DATA\_PAR file is the dataset\_description.json file of the BIDS
-standard, the x structure is created according to BIDS.
-
-
-
-
 ## Initialization
 
-----
-### xASL\_init\_ConvertM2JSON.m
-
-#### Format
-
-```matlab
-[PathJSON] = xASL_init_ConvertM2JSON(PathM)
-```
-
-#### Description
-This function converts and replaces the legacy data parameter m-format
-by a JSON file. A DataPar.m was the settings/parameter file, specific to a dataset to be
-processed by ExploreASL, now replaced to JSON by BIDS.
-Note that the deployed/compiled version of ExploreASL
-requires the JSON file, this function should not be compiled
-along. This function performs the following steps:
-
-1. Run the m-file to load parameters
-2. Escape characters that are illegal in JSON
-3. Write the JSON
-
-
 ----
 ### xASL\_init\_DefaultEffectiveResolution.m
 
@@ -2288,6 +2250,22 @@ This function also corrects formating of certain parameters.
 
 
 
+----
+### xASL\_io\_ExportVTK.m
+
+#### Format
+
+```matlab
+xASL_io_ExportVTK(nifti, [mask, exportPath])
+```
+
+#### Description
+Export a VTK image file based on a 3D NIFTI or a 3D/4D image matrix.
+4D images will be exported as a VTK time series (export-1.vtk, export-2.vtk, etc.).
+This script uses vtkwrite (MIT License, Copyright 2016, Joe Yeh).
+
+
+
 ----
 ### xASL\_io\_MakeNifti4DICOM.m
 
@@ -2333,6 +2311,28 @@ Alternative to this function is robust fit (Camille Maumet).
 
 
 
+----
+### xASL\_io\_ReadDataPar.m
+
+#### Format
+
+```matlab
+[x] = xASL_io_ReadDataPar(pathDataPar)
+```
+
+#### Description
+This function reads the data-parameter file, which is a file containing settings specific to processing a certain dataset or study
+(abbreviated as DataPar) and creates the x-structure out of it. The file can be in .json or .m format.
+The input file name pathDataPar is given as a string or character array. The output is the x structure. It only loads the data, removes the x-prefixes,
+but keeps all the field names and units. It doesn't do any conversions to or from BIDS. The
+only added value to normal json-read is that it detects invalid entries (numbers in strings, and
+weird arrays), converts them correctly and reports this incorrect entries so that they can be manually
+fixed. Also, if an .m file is provided, it converts and saves it to a JSON file (doesn't overwrite)
+and reports that you should stop using .m files.
+
+
+
+
 ----
 ### xASL\_io\_ReadTheDicom.m
 
@@ -3008,29 +3008,6 @@ PWI stage)
 
 
 
-----
-### xASL\_quant\_SliceTiming.m
-
-#### Format
-
-```matlab
-SliceTiming = xASL_quant_SliceTiming(x, inputIm)
-```
-
-#### Description
-This function takes the x.SliceReadoutTime, which can be a vector (of start of readout per slices relative to the
-readout of the first slice) or scalar (with difference in readout times between two consecutives slices) and 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.
-It also checks the x.readout\_dim, and for 3D readouts it returns 0.
-It loads the image from inputIm and calculates the SliceTiming according to the number of slices in the third dimension
-If a path is given, it also checks if it can find a JSON sidecar, then it loads the JSON sidecar, and looks for SliceTiming inside it. If
-SliceTiming/SliceReadoutTime is found in the JSON sidecar, it prioritize it over the value in the x-struct
-
-0. Admin
-1. ShortestTR
-2. Assign the vector value
-
-
 ----
 ### xASL\_quant\_SliceTiming\_ShortestTR.m
 

diff --git a/docs/Tutorials.md b/docs/Tutorials.md
@@ -5,7 +5,91 @@
 ## Beginner Tutorials
 
 ----
-### How to set up an ASL-BIDS dataset
+### ExploreASL & ASL-BIDS
+
+----
+#### Background information
+
+Starting with version **v1.6.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**. In the following subsections we will explain how you can use the automated **ExploreASL** import workflow to convert your data structure to **ASL-BIDS** and how you can process it.
+
+The `ExploreASL_Master` script will have the following format:
+
+```matlab
+[x] = ExploreASL([DataParPath, ImportModules, ProcessModules, bPause, iWorker, nWorkers])
+```
+
+Parameter descriptions:
+
+- `DataParPath`: Path to data parameter file (`OPTIONAL`, `DEFAULT = ` prompting user input)
+- `ImportModules`: `[DCM2NII, NII2BIDS, ANONYMIZE, BIDS2LEGACY]`
+    - `DCM2NII`: Run the DICOM to NIFTI conversion (`OPTIONAL`, `BOOLEAN`, `DEFAULT = 0`)
+    - `NII2BIDS`: Run the NIFTI to BIDS conversion (`OPTIONAL`, `BOOLEAN`, `DEFAULT = 0`)
+    - `ANONYMIZE`: Run the defacing and full anonymization (`OPTIONAL`, `BOOLEAN`, `DEFAULT = 0`)
+    - `BIDS2LEGACY`: Run the BIDS to LEGACY conversion (`OPTIONAL`, `BOOLEAN`, `DEFAULT = 0`)
+- `ProcessModules`: `[STRUCTURAL, ASL, POPULATION]`
+    - `STRUCTURAL`: Run the Structural Module (`OPTIONAL`, `BOOLEAN`, `DEFAULT = 0`)
+    - `ASL`: Run the ASL Module (`OPTIONAL`, `BOOLEAN`, `DEFAULT = 0`)
+    - `POPULATION`: Run the Population Module (`OPTIONAL`, `BOOLEAN`, `DEFAULT = 0`)
+- `bPause`: Pause workflow before ExploreASL pipeline (`OPTIONAL`, `BOOLEAN`, `DEFAULT = 0`)
+- `iWorker`: Allows parallelization when called externally  (`OPTIONAL`, `BOOLEAN`, `DEFAULT = 1`)
+- `nWorkers`: Allows parallelization when called externally  (`OPTIONAL`, `BOOLEAN`, `DEFAULT = 1`)
+
+----
+#### DICOM source data
+
+(Description about how the DICOM source data has to look like, with regard to the corresponding sourceStructure.json file)
+
+(Explanation about the benefit of being able to use data which basically comes from the scanner directly)
+
+(Mention flavor library and state of development)
+
+(Description about the first import workflow step of converting DCM2NII using dcm2niix)
+
+```matlab
+[x] = ExploreASL('sourceStructure.json', [1 0 0 0], 0, 0, 1, 1);
+```
+
+
+----
+#### NIFTI source data
+
+(Description about how the DICOM source data has to look like, with regard to the corresponding sourceStructure.json file)
+
+(Description about the second import workflow step of converting NII2BIDS)
+
+```matlab
+[x] = ExploreASL('sourceStructure.json', [0 1 0 0], 0, 0, 1, 1);
+```
+
+
+----
+#### Data anonymization
+
+(Description about the anonymization step)
+
+```matlab
+[x] = ExploreASL('sourceStructure.json', [0 0 1 0], 0, 0, 1, 1);
+```
+
+
+----
+#### Data in ExploreASL legacy format
+
+(Description about BIDS2LEGACY)
+
+```matlab
+[x] = ExploreASL('sourceStructure.json', [0 0 0 1], 0, 0, 1, 1);
+```
+
+
+----
+#### Full pipeline
+
+(Minor example of how the full pipeline can be used)
+
+```matlab
+[x] = ExploreASL('sourceStructure.json', 1, 1, 0, 1, 1);
+```
 
 
 ----

diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,6 @@
 ![ExploreASL](./img/title.png "ExploreASL")
 
-# ExploreASL v1.5.0
+# ExploreASL v1.5.1
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 [![All Contributors](https://img.shields.io/badge/all_contributors-10-orange.svg?style=flat-square)](#contributors-) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3905262.svg)](https://doi.org/10.5281/zenodo.3905262) [![View ExploreASL on File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://nl.mathworks.com/matlabcentral/fileexchange/83203-exploreasl) ![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/ExploreASL/ExploreASL) [![GitHub last commit](https://img.shields.io/github/last-commit/ExploreASL/Documentation?label=mkdocs)](https://exploreasl.github.io/Documentation/)