More flexible multi-echo support

[kimsin98]

Summary

I am trying to convert fieldmap data with a phase sequence with 2 echo times and a magnitude sequence with 2 echo times. The latest release claims to support multi-echo conversion, so I looked into how to build a heuristic that takes advantage of this. But looking at #293, it looks like convert.py tries to take care of converting multi-echo sequences into BIDS format.

So I just ran heudiconv on my data, but the result is slightly wrong. The correct BIDS format should be ...magnitude1, ...magnitude2, ...phase1, ...phase2, but heudiconv gives ...magnitude-1, ...phase-1, etc.

Looking at the multi-echo handling in #293 closely, it seems incredibly hacky to try supporting every possible multi-echo image types then fall back to an inflexible way of just appending the suffix. This seems even more problematic if you consider that BIDS is an evolving format that may add more variations in the future.

Keeping with the point of heuristics-based conversion, multi-echo handling should also use templates to let the user decide how to format the output files.

Platform details:

Choose one:

• Local environment

• Container (master)

• Heudiconv version: 0.6.0.dev1

[mgxd]

There is already an open issue about this #346. I had messed around with a branch earlier this year that adds a flag to split all echoes, allowing template style naming per each echo. When I get some time, I'll try to get it in working shape.

What does your heuristic / series info look like? There may be a way to work around this.

[kimsin98]

fmap_mag = create_key('sub-{subject}/fmap/sub-{subject}_magnitude')
fmap_phase = create_key('sub-{subject}/fmap/sub-{subject}_phase')

for s in seqinfo:
    elif 'B0map' in s.protocol_name:
        if 'M' in s.image_type:
            info[fmap_mag].append(s.series_id)
        elif 'P' in s.image_type:
            info[fmap_phase].append(s.series_id)

This is what I tried. seqinfo only recognizes 1 echo time even though the sequence has 2 echo times, so using it to distinguish was not an option.

For now, I am just using a shell script to convert.

EDIT: Using --bids option resulted in different outputs! Magnitudes are BIDS compliant, but phase files use _echo-{index}_phase format due to #373. I think heudiconv needs more consistency and better documentation in general.

[pvelasco]

@Aksoo,

Until a more permanent solution is found to support for echo naming in the heuristic file, something you can do is modify convert.py.

Where it says:

                supported_multiecho = ['_bold', '_phase', '_epi', '_sbref', '_T1w', '_PDT2']
                # Now, decide where to insert it.
                # Insert it **before** the following string(s), whichever appears first.
                for imgtype in supported_multiecho:
                    if (imgtype in this_prefix_basename):
                        this_prefix_basename = this_prefix_basename.replace(
                            imgtype, "_echo-%d%s" % (echo_number, imgtype)
                        )
                        break

Replace it with:

                if ('fmap' in prefix_dirname):
                    this_prefix_basename += echo_number
                else:
                    supported_multiecho = ['_bold', '_phase', '_epi', '_sbref', '_T1w', '_PDT2']
                    # Now, decide where to insert it.
                    # Insert it **before** the following string(s), whichever appears first.
                    for imgtype in supported_multiecho:
                        if (imgtype in this_prefix_basename):
                            this_prefix_basename = this_prefix_basename.replace(
                                imgtype, "_echo-%d%s" % (echo_number, imgtype)
                            )
                            break

I think it will do what you want, without breaking anything else, but I haven't tested it...

[kimsin98]

I am using a docker image, and I don't know how to edit that file in the image.

Until proper multi-volume support, I will just use a post-processing shell script, since it's a minor name change.