Support complex-valued dwidenoising

[tsalo]

Closes #677.

We can probably use ds004666 for testing/validation, though we'll need to add sidecar files with some metadata (PhaseEncodingDirection and TotalReadoutTime).

Changes proposed in this pull request

• In collect_data, select "part-mag" or no part entity for "dwi" data.
  • This will ensure that regular DWI processing doesn't accidentally collect phase files.
• Add steps to perform complex-valued dwidenoise when possible.
  • Limited to when (1) --denoise-method is set to dwidenoise, (2) --ignore doesn't include phase, (3) --denoise-after-combining is not enabled, and (4) phase data are available.
• Add phase option to --ignore to explicitly disable complex-valued denoising when phase data are available.
• In init_merge_and_denoise_wf, use layout.get_metadata() to get each DWI file's metadata.

[tsalo]

It seems like the "combining" step (not denoise_before_combining) involves processing (b0_threshold and not no_b0_harmonization) that would mess up the relationship between the magnitude and phase data, so we might need to limit complex dwidenoise to workflows with denoising before combining.

I also don't know what merging_distortion_groups really does. Does it just create a cross-run template, or does it do some initial processing to the DWI data before the denoising workflow?

EDIT: I just noticed that, in ds004666, not all runs and directions have phase data, so we can't take that for granted. Perhaps I should grab the phase data right before denoising, instead of within collect_data?

[tsalo]

So what I ended up doing is passing along the BIDSLayout to init_merge_and_denoise_wf. Now it will try to find a phase file for each individual DWI file as it loops through the DWI files. Complex-valued denoising will only be allowed if denoise_before_combining is True, since I'm not sure if the extra steps from combining (e.g., the B0 harmonization) would mess up the relationship between the magnitude and phase data. Also not sure that we can assume that complementary magnitude runs will all have phase data.

[tsalo]

Tests are now passing, so at least I didn't break the original workflows.

[tsalo]

Tested on the 0p9mm session of ds004666, and it failed on MergeDWIs:

ValueError: MergeDWIs requires a value for input 'bval_files'. For a list of required inputs, see MergeDWIs.help()

EDIT: Ah, I see that this happened because ds004666 uses inheritance for the bval and bvec files.

[mattcieslak]

this is a great idea - it doesn't require a new commandline flag and is easy to understand

[mattcieslak]

Do you remember where you found the mrcalc commands? Was it on the mrtrix forum?

[tsalo]

I got it from the docstring of mrcalc: https://mrtrix.readthedocs.io/en/latest/reference/commands/mrcalc.html#complex-numbers