Description

More complicated datasets often contain scanner switches or related alterations. At baseline they might have been acquired on, say, a Siemens scanner without an M0 with a control-label sequence and at a followup visit they might have been scanned on a GE scanner with a deltam + M0 output. At the current time, ExploreASL's Import module can't handle this scenario: a user would have to split up subjects/visits to different sourcedata directories, run the Import module separately for each, and then try to join them back together.

Key things we agreed upon (I am just trying to summarize, please correct me if I'm wrong)

1. Single studyPar.json in root directory that defines everything
2. studyPar.json will be created manually or in a GUI, but it will be 'applied' inside ExploreASL. The GUI will help to create it, but it won't be using or interpreting it. Reason: We keep comfort for user, but we allow editing it and have this option available for all users.
3. Because of 2, this studyPar.json will be used in the NII2BIDS phase (not in DICOM2NII phase).
4. Because of 3, we won't have the original folder and filenames available to assist in this multi-study process. Instead, we will have to work with the aliases assigned by sourceStructure.json.
5. Because of 4, we will be able to work with 'subject name', 'session (a.k.a. visit)', 'run (a.k.a. session) name'
6. We will have either a normal and plain studyPar.json - then everything is applied to all sessions.
7. We have ImportContexts keyword with an array of nested lists.
8. We go through the list starting from the top and going to the bottom.
9. Top-most entry is the most general one applied to all (it doesn't need to have, but it could have conditions).
10. All entries below need to have conditions, if conditions are fulfilled, then the previous entries are overwritten - i.e. the last entry in the list has the highest priority.
11. Conditions contain SubjectList, SessionList, VisitList (just ideas, the names can change). At least one of these has to be provided for each but the first entry. These three conditions are connected by AND - i.e. all provided conditions for an entry have to be fulfilled. However, within each list, they are connected by OR.
12. SubjectList - an array of strings of subject names - could be full names or regexp.
13. SessionList, VisitList - array of numbers - corresponding to the aliases given in sourcestructure.json (I know that the sourcestructure.json is really an archaic stuff and we have to get rid of it - but we can't do everything at once ;)).

I think that this is a comprehensive definition of how to do things.
So with your example:

I would use the following sourceStructure.json:
"folderHierarchy": ["^(sub088Siemens3DwithM0|sub128Philips2DnoM0)$", "^(Baseline|Followup)$", "^(ASL|M0|T1)$"],
"tokenOrdering":[1,2,0,3],
"tokenVisitAliases":"Baseline","1","Followup","2"],
"tokenSessionAliases":["",""],
"tokenScanAliases":["^ASL$","ASL4D","^T1w$","T1w","^M0$","M0"],

Then, taking your example from above, lets go for the following studyPar.json. Note that I included some stuff in the general definition, just so that we have it ;) Also - lets say that most subjects on baseline were Siemens PASL with PLD 1.8 with M0. But there was one subject without M0. And all followups were PCASLs done on GE. This should be applicable also to the example you give above, but I have used something that would work with the provided file-structure screenshot. The studyPar.json would look like (note that I deleted some tags just to make it a bit shorter and easier to read):
"ImportContexts": [
{
"ASLContext": "label, control",
"M0": true,
"Manufacturer": "Siemens",
"LabelingType": "PASL",
"PostLabelingDelay": 1.8,
},
{
"SubjectList": ["sub128Philips2DnoM0","^sub.*withoutM0$"]
"M0": false,
},
{
"VisitList": [2]
"ASLContext": "deltam",
"M0": true,
"Manufacturer": "GE",
"LabelingType": "PCASL",
"PostLabelingDelay": 1.525,
},
{
"SubjectList": ["subWithPhilipsFollowup"]
"VisitList": [2]
"ASLContext": "control,label",
"M0": true,
"Manufacturer": "Philips",
"LabelingType": "PCASL",
"PostLabelingDelay": 1.800,
},
]
}`

Few things to note on this scheme, which will make it easy to use:

1. regexp in lists.
2. we have inheritance, so we can easily redefine just a single parameter when needed.
3. If played smartly with a correct priority, we don't have to list all cases, but we just rewrite entire group of subjects or sessions, or both.
4. The last one is an exceptional subject that was scanned normally on session 1, but on session 2, he received Philips. So we have to redefine all tags again - and it has to be the last in the list.

To implement it on ExploreASL side (not the GUI side), we will only need to do the following:

1. In NII2BIDS, we will not read studyPar.json normally (that checks for backwards compatability - but with a normal json_read).
2. Then when processing every subject (at each run), we will not use the studyPar.json, but we will run a function that goes through this studyPar.json and selects the correct subset. Then we run the backwards compatability function.
3. The resulting specific studyPar will be passed upon a subfunction.
4. When going to a following subject, we go to step 2.

Tasks

• Read enhanced study par and correctly check all subsets. Fix in xASL_io_ReadDataPar.
• Function that takes subject/visit/session and solves the priority to construct the correct specific studyPar.
• fix xASL_wrp_NII2BIDS_Subject for new studyPar version
• fix xASL_wrp_NII2BIDS for new StudyPar version
• Use the specific studyPar - inside xASL_imp_NII2BIDS_Run, because here it should be already fixed xASL_imp_NII2BIDS_RunPerf.m
• Make sure that it works as well here - xASL_imp_DCM2NII_Subject_SortASLVolumes.m - no worries, we don't distinguish between anything else than TimeEncoded and TimeEncodedFME, so we should make it a single param only. We have to use ImportContext instead of a simple studyPar. Can we extract aliases in this case? We can from here x.overview.subject_001.visit_001. We should run the priority function anyway.
• And here - xASL_imp_BasicParameterChecks.m
• Update Documentation and explain.
• Write UT function for the prioritization.
• Test with flavor Siemens_PCASL_3DGRASE_VD13A_DEBBIE - merged HAD4 and HAD8
• Merge flavors Siemens_PCASL_2DEPI_VE11C_MB_1 and 2 and their respective 3DGraSE counterparts.
• verify: ExploreASL_Import.m
• verify: xASL_bids_MergeStudyPar.m
• verify: xASL_imp_NII2BIDS_Subject_DefineM0Type.m
• verify: xASL_imp_DCM2NII_Subject_SortASLVolumes.m
• verify: xASL_imp_BasicParameterChecks.m
• Rename ImportContexts to StudyPars
• Rename AliasHierarchy to SubjectRegexp, VisitRegexp, SessionRegexp.
• Fix Documentation
• Fix issue with RegExp field deleting.

Release notes

StudyPar supports multi-parameter definitions for import of multi-sequence datasets.