docs: registration troubleshooting

[maxpietsch]

If linear registration fails, it can be quite tricky to find out why. I'd suggest to write a section about this in the docs. This is basically a brain dump but feel free to suggest additions!

general guidelines would be along the lines:

• large rotation? try -rigid_init_rotation search
• FOD data? use higher lmax in first iteration
• initial resolution too low / too high? change -rigid_scale
• intensities have different magnitude? normalise
• images shear? start with rigid then go to affine

It might also be worth giving users command line options to trouble shoot themselves:

The current state of debug functionality in mrregister (in the tag_0.3.16 branch) is that if you add the following to your .mrtrix.conf:

reg_gradient_descent_repeats: 1
reg_linreg_diagnostics_image_masked: 0
reg_linreg_diagnostics_image_prefix: /tmp/analyse_me

and run for instance: mrregister 3csd.mif 4csd.mif -mask1 3mask.mif -mask2 4mask.mif -type affine -affine_scale 0.3,0.3,1 -affine_lmax 2,2,2 -affine_niter 10,50,50

then this will generate RGB images /tmp/analyse_me_level-?_gdrep-?.mif that contain both input images re-gridded to the midway space after each registration level (at the current resolution). If one sets reg_linreg_diagnostics_image_masked to 1 then one sees the images masked.

Each resolution level is repeated reg_gradient_descent_repeats times. So the following

reg_gradient_descent_repeats: 10
reg_linreg_diagnostics_image_masked: 0
reg_linreg_diagnostics_image_prefix: /tmp/analyse_me

mrregister 3csd.mif 4csd.mif -mask1 3mask.mif -mask2 4mask.mif -type affine -affine_scale 0.3,0.3,1 -affine_lmax 2,2,2 -affine_niter 1,5,5

will give more fine-grained (but not identical) results:

mrregister 3csd.mif 4csd.mif -mask1 3mask.mif -mask2 4mask.mif -type affine -affine_scale 0.3,0.3,1 -affine_lmax 2,2,2 -affine_niter 1,5,5
mrregister: [100%] preloading data for "3csd.mif"
mrregister: [100%] preloading data for "4csd.mif"
mrregister: SH series detected, performing FOD registration
mrregister: running affine registration
mrregister: initialising translation and centre of rotation using centre of mass
mrregister: multi-resolution level 0, scale factor 0.29999999999999999, lmax 2
mrregister: creating diagnostics image:
mrregister: /tmp/analyse_me_level-0_gdrep-0.mif
mrregister: creating diagnostics image:
mrregister: /tmp/analyse_me_level-0_gdrep-1.mif
mrregister: creating diagnostics image:
mrregister: /tmp/analyse_me_level-0_gdrep-2.mif
mrregister: creating diagnostics image:
mrregister: /tmp/analyse_me_level-0_gdrep-3.mif
mrregister: creating diagnostics image:
mrregister: /tmp/analyse_me_level-0_gdrep-4.mif
mrregister: creating diagnostics image:
mrregister: /tmp/analyse_me_level-0_gdrep-5.mif
mrregister: creating diagnostics image:
mrregister: /tmp/analyse_me_level-0_gdrep-6.mif
mrregister: creating diagnostics image:
mrregister: /tmp/analyse_me_level-0_gdrep-7.mif
mrregister: creating diagnostics image:
mrregister: /tmp/analyse_me_level-0_gdrep-8.mif
mrregister: creating diagnostics image:
mrregister: /tmp/analyse_me_level-0_gdrep-9.mif
mrregister: multi-resolution level 1, scale factor 0.29999999999999999, lmax 2
mrregister: creating diagnostics image:
mrregister: /tmp/analyse_me_level-1_gdrep-0.mif
...

[thijsdhollander]

• large rotation? try -rigid_init_rotation search
• FOD data? use higher lmax in first iteration
• initial resolution too low / too high? change -rigid_scale
• intensities have different magnitude? normalise
• images shear? start with rigid then go to affine

I like the idea of some insightful and robust guidelines, especially for registration which -as we all know- is closer to an art than a science. :smile:

A couple of comments on the brain dump:

• I'm a bit confused by the FOD data one: wouldn't we recommend to go lower lmax at the start in case of issues? Typically if stuff gets stuck in a local optimum, it's because the multi-scale approach of it all may have failed somehow, and the registration should've been eased "more gently" towards the result. ...but maybe I'm misunderstanding what would be behind your recommendation for a higher lmax...?
• While all bullets describe a symptom that a user can diagnose (and next a solution is proposed), the third bullet on the resolution doesn't fit in that "style" currently: it rather describes just what you can do with the -rigid-scale option (but the documentation of this option of the command already does that too). To fix this, we'd need to identify some scenarios that could be diagnosed as, e.g., "your initial resolution was too low" --> "solution: raise initial resolution via -ridig_scale option". (or the equivalent thing for initial resolution = too high, etc..)

[maxpietsch]

I'm a bit confused by the FOD data one: wouldn't we recommend to go lower lmax at the start in case of issues? This is a case of
more art than a science...

Usually, the problem (for my data) is not getting stuck in local minima but

• not exploring the parameter space enough (that's at least partially solved with rotation search and Barzilai-Borwein Gradient Descent)
• or shearing or divergence because of poor masks or because the data has not enough structure to guide registration to overlap more. For the latter case using higher lmax seems to help in the initial low-resolution steps.

third bullet on the resolution doesn't fit in that "style" currently

Yes, that is what I was hoping to do with the diagnosis images. Lots of structure --> decrease resolution to avoid local minima. Two smooth blobs --> increase resolution to add structure that helps guide the non-translation components of the transformation. But that is quite subjective...

[thijsdhollander]

higher lmax seems to help in the initial low-resolution steps

Aha, yes, I can see how it would help given low spatial resolution of course. Makes sense, but we'd have to indeed mention that we're talking about that initial step. In general in cases of divergent behaviour (e.g. unwanted shearing), I reckon the "safe" advice would be to ease the transformation model more into the solution, i.e., start off with a rigid stage and "gently" progress through adding degrees of freedom. But as you're implying too, it also depends on the context.

Lots of structure --> decrease resolution to avoid local minima.

Indeed, in another way a case of being clever about the gentle multi-resolution approach.

Two smooth blobs --> increase resolution to add structure that helps guide the non-translation components of the transformation.

Eventually yes, but initially low resolution would still help to speed up and "robustify", I reckon. The difference with the former example would be that that (former) one you may want to stop at a lower resolution (or more regularization for the warp), depending on what your expectations are about those details in the structure; i.e., are they even expected to match, or could they vary between subjects (e.g., the cortex, that can at many occasions even be topologically different; a "sharper" match isn't always more "accurate").

But that is quite subjective...

That's ok, I reckon, but we have to be clear it's advise about something that many consider to be more an art (or let's say, engineering practice) rather than an exact science. Quite often, if you're doing registration between different human subjects, you expect variations even in topology of anatomy. The word "accuracy" in the context of such a registration outcome becomes close to meaningless, I'd argue. There is no ground truth or law of nature about how to peoples' brains "spatially match". It's "just a tool" (albeit a highly complicated one) that we happen to use to do stats across what we hope are similar-ish regions across a population.