Through years of coding generic heuristics one of the challenging aspect is that one need to specify some entities only when two series need to be disambiguated, eg:
- one need to specify
rec- because the reconstruction settings output 2 series from the same sequence with 2 recon option (eg distortion-corrected and raw).
- one need to specify
dir because there are 2 series acquired with opposite phase-encoding dir (not in standard DICOM tags BTW).
- .... same thing for a number of other entities.
But if there is no need to disambiguate, it is preferable to keep the file names short rather than sub-xx_ses-yy_task-none_acq-normal_ce-none_rec-raw_run-1_echo-1_part-mag_chunk-1_T1w.nii.gz in a dataset where there is a single T1w series and zero ambiguity, though it would be BIDS-valid.
That dynamic aspect of naming is difficult to encode in a static config, which is why heudiconv allows code that has access to the full session at-once to determine the naming.
The way it can be implemented in heudiconv heuristics is to collect required and extra optional entities for each series, and then "deduplicate" series that have the same path using the optional entities, until there is no duplicates.
See here for the logic:
https://gitlab.unf-montreal.ca/ni-dataops/ci-pipelines/-/blob/main/src/pipelines/mri/heuristics_cpip.py?ref_type=heads#L735-807
Through years of coding generic heuristics one of the challenging aspect is that one need to specify some entities only when two series need to be disambiguated, eg:
rec-because the reconstruction settings output 2 series from the same sequence with 2 recon option (eg distortion-corrected and raw).dirbecause there are 2 series acquired with opposite phase-encoding dir (not in standard DICOM tags BTW).But if there is no need to disambiguate, it is preferable to keep the file names short rather than
sub-xx_ses-yy_task-none_acq-normal_ce-none_rec-raw_run-1_echo-1_part-mag_chunk-1_T1w.nii.gzin a dataset where there is a single T1w series and zero ambiguity, though it would be BIDS-valid.That dynamic aspect of naming is difficult to encode in a static config, which is why heudiconv allows code that has access to the full session at-once to determine the naming.
The way it can be implemented in heudiconv heuristics is to collect required and extra optional entities for each series, and then "deduplicate" series that have the same path using the optional entities, until there is no duplicates.
See here for the logic:
https://gitlab.unf-montreal.ca/ni-dataops/ci-pipelines/-/blob/main/src/pipelines/mri/heuristics_cpip.py?ref_type=heads#L735-807