ENH: Implement Jacobian weighting during unwarp

[effigies]

This turned out to be dead simple. The basic idea of a Jacobian is to map volumes in the target space to volumes in the source space. We have a particularly easy case, because there is a warp only in one dimension, so our Jacobian is trivially equal to $1 + dx/dP$ where $P$ is the phase-encoding axis.

It seems likely that we will need to adjust this when permitting other transformations. While affine transforms will scale all points uniformly (and can thus be ignored for unitless values like BOLD), warps to template will almost certainly produce additional changes worth accounting for, though the scale of those effects is probably small compared to SDC.

Closes #382.

[effigies]

Hmm. I wonder if I should be scaling the jacobian by the voxel volume, not from 0-1... (This was not even wrong.)

[effigies]

Continuing to work on this. I have attempted to create a Jacobian determinant in a couple ways, none of which significantly affected my use case. I believe that the mask used to fit the spline field is the more significant problem for phasediff fieldmaps. I think we need to mask the output field.

[effigies]

As discussed with @oesteban, the shortest path forward here is to pull the TOPUP-generated Jacobians to the application stage. Calculating our own Jacobians can wait.

Turns out trying to make use of TOPUPs Jacobians was more pain than finally wrapping my head around exactly what a Jacobian is in this context.

[codecov]

Codecov Report

All modified lines are covered by tests ✅

Comparison is base (50ace2a) 80.57% compared to head (c8a4f3d) 80.59%.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #391      +/-   ##
==========================================
+ Coverage   80.57%   80.59%   +0.01%     
==========================================
  Files          26       26              
  Lines        2291     2293       +2     
  Branches      287      287              
==========================================
+ Hits         1846     1848       +2     
  Misses        401      401              
  Partials       44       44              

Flag	Coverage Δ
unittests	∅ <ø> (∅)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
sdcflows/transform.py	77.90% <100.00%> (+0.24%)	⬆️

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[effigies]

applytopup-corrected

sdcflows @ master-corrected

With this PR

It is not 100% identical, and this may be a result of premature coercion to float32 of coordinates during resampling, or it could be our spline knots are very slightly differently defined.

[oesteban]

Excellent work 💯

…

On Sun, Oct 1, 2023, 07:00 Chris Markiewicz ***@***.***> wrote: applytopup-corrected [image: Screenshot from 2023-10-01 00-33-32] <https://user-images.githubusercontent.com/83442/271808812-894fce09-506b-41d3-84b3-85a21c9519ea.png> sdcflows @ master-corrected [image: Screenshot from 2023-10-01 00-33-58] <https://user-images.githubusercontent.com/83442/271808814-f72624be-f6d5-408c-aaea-b717426f199e.png> With this PR [image: Screenshot from 2023-10-01 00-34-08] <https://user-images.githubusercontent.com/83442/271808816-f4316295-c940-4e5a-b5f5-00e79d0037a1.png> It is not 100% identical, and this may be a result of premature coercion to float32 of coordinates during resampling, or it could be our spline knots are very slightly differently defined. — Reply to this email directly, view it on GitHub <#391 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAESDRU3P6324MSODWX3G23X5D2GHANCNFSM6AAAAAA3V2LARU> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[effigies]

@oesteban or @mgxd would you care to review? (Feel free to say you don't have time but I should/shouldn't go ahead and merge.)

[mgxd]

this is great and lgtm - let's get it into dev for further testing