Provide flexible support for multi-volume sequences

[yarikoptic]

Such as PD+T2w pairs, and possibly new fancy sequences from GE. See https://github.com/nipy/heudiconv/issues/144#issuecomment-492726073 for the initial discussion etc. ATM we do support multi-echo and hardcoded _PDT2 (added in #345) but we might as well allow for more flexible specification via _MOD1+MOD2[+...] syntax to be split and matched to the number of images produced

[nicholst]

Maximising the sense of "flexible", I propose that heudiconv be able to split up images with the same series UID, specificaly motivated by the use case of PDw and T2w image echo pairs.

After consultation with the BEP001 MultiEcho team, specifically https://github.com/bids-standard/bids-specification/issues/223#issuecomment-494022982, they report that PDT2 modality label will be depricated, and recommend replacing it with MESE (multiecho spin echo). Meaning that valid BIDS PD+T2 pairs will come out like:

• sub-000_echo-1_MESE
• sub-000_echo-2_MESE or possibly, slighly clearer as
• sub-000_echo-1_acq-PDw_MESE
• sub-000_echo-2_acq-T2w_MESE

Hence, I think it's crucial that heudiconv have the ability to apply heuristics that allow you to assign different modality labels to scans that share a series UID, so that you could, from a echo pair, create:

• sub-000_PDw
• sub-000_T2w ... but at present, as I understand, there is simply no way to do this.

(@Gilles86 please indicate if I've misrepresented BEP001's plans) (ping @satra)

[satra]

@nicholst - this is a fundamental problem about how to group dicom files. thus far, we have relied on simple groupings (e.g., series UID), but one can envision not just your use case, but say someone wanting to separate out a diffusion series into b0 scans and non b0 scans. this pattern does come up in many different use cases. also dicoms can be mosaiced, unmosaiced, and multiframe.

i can see a few solutions:

1. allow the heuristic file to receive a table of dicom info for any series, and allow splitting the table. (like a pandas group by).
2. extend the heuristic to control grouping in addition to mapping.

my personal preference would be to allow 2, and depend on pandas. but i am open to other suggestions (@yarikoptic any thoughts here ?)

[nicholst]

@satra - having never myself crafted a heuristic I don’t feel like I can weigh in - maybe @DanielDelbarre can? All I’d say is the option that minimizes effort when this series-splitting complexity is not needed would be preferable.

[satra]

@nicholst - indeed, it would default to the current form for series splitting if no special handling is needed. there will also be some capabilities at the command line level for groupby order to minimize extra code writing. people should only have to alter the grouping function if absolutely necessary.