Merge SHARDRecon into main MRtrix3 codebase #2994

dchristiaens · 2024-09-12T14:51:36Z

This PR aims to merge the SHARDRecon module into the main MRtrix3 repository. The recent changes to the build system and python interface make it challenging to maintain external projects that are not linked to one particular version of MRtrix3. Merging SHARDRecon into dev will ensure that the code remains compatible.

Key tasks:

…niformly stored as yaw-pitch-roll Euler angles.

…ding.

…tion. The q-space basis is now evaluated per excitation, rather than per slice. This reduces the overall computational cost by effectively the multiband factor. Note that volume-to-volume reconstruction is treated as a special case where MB = Nslices, i.e., Nexcitations = 1.

This implementation uses the Lie-algebra se(3) of the rigid transformation group SE(3), coupled with a Levenberg-Marquardt solver for optimizing the asymmetric rigid registration problem.

cmd/msshsvd.cpp

src/dwi/svr/mapping.h

Lestropie · 2024-09-13T13:45:37Z

cmd/dwirecon.cpp

+    // -----------------------  // TODO: Eddy uses a reverse LR axis for storing
+    PE.col(0) *= -1;            // the PE table, akin to the gradient table.
+    // -----------------------  // Fix in the eddy import/export functions in core.


Need to determine whether this is an artifact of bad metadata handling in MRtrix3 (#2917), or whether it is in fact the case that the FSL text file formats for indicating the phase encoding table are expected to be based on a negative determinant image. My expectation was that it would be the former. If the comment is true and the issue is the latter, then there will need to be an explicit distinction between storage of the phase encoding table w.r.t. image axes and the import/export of that information from/to FSL.

I've removed all of these on the version we're using at KCL now. You can see these changes on my fork: dchristiaens/shard-recon@master...jdtournier:shard-recon:master

@jdtournier Good point. I forgot to merge your PR before creating this one. Your last update is that you were going to confirm if the PE direction had been fixed in the main repo. Is this the case? If so, I don't understand why the test I did last week didn't flag a change in PE.

Well, all I can say is that the code we're currently running has these lines removed - but I did also have to modify the corresponding acqp.txt for it to work correctly... So that would suggest that it isn't fixed after all...

It terms of testing, I guess what's required is to first run eddy to verify the correctness of the acqp.txt file, and then run shardrecon with same acqp.txt, right? Must admit I haven't done that, and given the above, I suspect that will show that the problem persists...

Is the derivation of your acqp.txt file going through MRtrix3 processing at all? I'm presuming it's not being loaded from DICOM headers, but are you loading it into an image header and then doing an export to text file? If so then the issues rectified in DWI metadata handling fixes #2917 could be playing a role.

A useful test to do, with this line removed, would be to find the acqp.txt that results in topup doing the right thing, then convert the NIfTI between LAS and RAS and re-run with the same acqp.txt. If it then produces the wrong result, then the FSL interpretation of the phase encoding table is with respect to the image axes, as has always been my understanding. If it produces the correct result, then FSL expects the phase encoding table to be defined with respect to its internal left-handed coordinate system, and our command-line interface for phase encoding data handling has to be changed.

Lestropie · 2024-09-16T01:00:01Z

python/mrtrix3/commands/dwimotioncorrect.py

+        pe_import_option = ['-import_pe_table', app.ARGS.pe_table]
+    elif app.ARGS.pe_eddy:
+        pe_import_option = ['-import_pe_eddy', app.ARGS.pe_eddy[0], app.ARGS.pe_eddy[1]]
+    # check output path - code no longer works; now done internally??


Correct: arguments of type (Directory|File|Image)Out are now automatically checked, so devs are no longer responsible for adding these function calls.

mrtrix3/python/mrtrix3/app.py

Lines 181 to 192 in 1f9d3b4

# Now that FORCE_OVERWRITE has been set,

# check any user-specified output paths

try:

for key in vars(ARGS):

value = getattr(ARGS, key)

if isinstance(value, Parser._UserOutPathExtras): # pylint: disable=protected-access

value.check_output()

except FileExistsError as exception:

sys.stderr.write('\n')

sys.stderr.write(f'{EXEC_NAME}: {ANSI.error}[ERROR] {exception}{ANSI.clear}\n')

sys.stderr.flush()

sys.exit(1)

Lestropie · 2024-09-16T01:02:09Z

python/mrtrix3/commands/dwimotioncorrect.py

+        if not image.match(header, 'mask.mif', up_to_dim=3):
+            raise MRtrixError('Provided mask image does not match input DWI')
+    else:
+        run.command('dwi2mask in.mif mask.mif')


Needs to be updated to new dwi2mask interface

Lestropie · 2024-09-16T01:06:11Z

python/mrtrix3/commands/dwimotioncorrect.py

+
+    #   __________ Copy outputs __________
+
+    run.command(['mrconvert', f'recon-{nepochs}.mif', app.ARGS.output], mrconvert_keyval=f'recon-{nepochs}.mif', force=app.FORCE_OVERWRITE)


Suggested change

run.command(['mrconvert', f'recon-{nepochs}.mif', app.ARGS.output], mrconvert_keyval=f'recon-{nepochs}.mif', force=app.FORCE_OVERWRITE)

run.command(['mrconvert', f'recon-{nepochs}.mif', app.ARGS.output],

mrconvert_keyval=app.ARGS.input,

force=app.FORCE_OVERWRITE)

Purpose here is to have command_history in the output image reflect the invocation of dwimotioncorrect, rather than listing all of its internal steps.

Lestropie · 2024-09-16T01:07:50Z

python/mrtrix3/commands/dwimotioncorrect.py

+    if app.ARGS.export_motion:
+        run.command(f'cp motion.txt {app.ARGS.export_motion}')
+    if app.ARGS.export_weights:
+        run.command(f'cp sliceweights.txt {app.ARGS.export_weights}')


In addition to using Python functions rather than Unix cp, this could potentially be improved by adding command_history to the header comments of these files.

Lestropie · 2024-09-16T01:14:47Z

I'm going to generate a list here of things that come to mind; nothing major, just thoughts that I think are worth contemplating. Don't want to block progress by demanding massive pieces of work, just starting dialogues. Some I can help out with.

dwirecon command (New command: dwirecon #2915 relevant):
At the moment this is hard-coded to yield multi-shell spherical harmonics data, however from the command name one would intuitively expect DWI data. There's a few different options here, and it might need a combination of things to get fully resolved with New command: dwirecon #2915:
- Change name of this command to msshrecon. Completely unblocks New command: dwirecon #2915.
- Make dwirecon an operation-based command. Essentially take what's in New command: dwirecon #2915 and make what is contained within cmd/dwirecon.cpp in this PR another operation within that command, with a set of command-line options that are applicable only to that operation.
- Have a toggle that changes the output of this code between multi-shell spherical harmonics and reconstructed DWI data.
  (I would possibly lean towards a toggle here, rather than having a default output and then a command-line option that outputs the data in the other form, since it's large data and users are likely to want one or the other)
Data type for command naming:
Currently here "mssh" is used for multi-shell spherical harmonics. I am however reminded that dwi2fod msmt_csd started its life as msdwi2fod. Here there is a stronger argument for a different datatype indicator: mssh and sh are less interchangeable from a data description perspective that single-shell vs. multi-shell DWI data. It may however be the case that many operations intended for SH data can be extended to multi-shell SH data.
- Possibility of just using sh from a command name perspective, and anything that expects multi-shell SH but receives a single SH, or vice versa, throws an Exception? Whether this might be reasonable would require looking across the package for SH interfaces.
- Is mssh the best indicator? Would "multi-spherical-harmonics (msh)" work? Are there any contexts in which one may have multiple spherical harmonics functions, where the groups of coefficients do not correspond to shells? Multiple ODFs within a single 5D image comes to mind. I suppose shard isn't correct from a data description perspective?
dwirecon needs a more comprehensive Description.
I'd like for there to be more explanation of how the slice profile is derived / interfaced so that I can try to make proper use of it for my own data.
I know that for my own data, having the ability to correct for eddy current distortions is going to be important. I tried to read up on the Lie algebra used for the motion modeling, but it's well outside my current expertise to know how it might be extended from rigid-body to an affine model, or what the consequences of doing so on other code might be. @dchristiaens Do you have an intuition of how involved such a change might be? I'm happy to help on this one where I can from a code perspective , I'm moreso doubtful on my capacity to derive / follow the math.
Some commands involve specification of multi-band factors to influence slice-to-volume registration. This could be streamlined by instead making use of SliceTiming.
With mrfieldunwarp, I'm wondering if this could be handled differently. If one has a susceptibility field in Hz, then that can be converted to a deformation field based on phase encoding direction & readout time. That's just a non-linear warp field that can be composed with any other transformation, whether it be rigid-body motion (as `mrfieldunwarp currently handles on a per-slice-stack basis) or anything else (eg. I'm imagining composing this with the gradient non-linearity geometric distortion field). Therefore, is this something that could be adequately handled by:
- Giving warpconvert the ability to convert inhomogeneity field to deformation field based on phase encoding information
- Having some other way to compose this deformation with per-slice-stack motion parameters
  ? It's not immediately clicking what the best form of the second point would be. Explicitly composing transforms and then subsequently applying those transforms would be the most modular, but highly inefficient. Maybe if mrtransform could accept both the deformation field and the rigid-body motion parameters and would then be responsible for the composition?
@dchristiaens Are you able to share some exemplar data for which you know the reconstruction pipeline behaves properly and yields an acceptable result, whether privately or publicly? Just if I'm going to muck around with the code I'd like to know that I'm not breaking anything.
(If I do come up with any changes, I won't commit directly to this branch, I'll make a PR)
Some Python commands need to have their typed arguments updated.
Python commands using 4 spaces for indentation, whereas the internal convention is 2.
Some Python code could make better use of F-strings, which are now used throughout the Python code base.
File copyright headers currently differ from the main code base.

github-actions

clang-tidy made some suggestions

There were too many comments to post at once. Showing the first 25 out of 342. Check the log or trigger a new build to see more.

cmd/dwirecon.cpp

cmd/dwisliceoutliergmm.cpp

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

github-actions

clang-tidy made some suggestions

There were too many comments to post at once. Showing the first 25 out of 321. Check the log or trigger a new build to see more.

github-actions · 2024-09-18T16:27:25Z

cmd/dwirecon.cpp

+  y.setZero();
+  ssize_t j = 0;
+  for (auto lv = Loop("loading image data", {0, 1, 2, 3})(dwisub); lv; lv++, j++) {
+    float const w = Wsub(dwisub.index(2), dwisub.index(3)) * Wvox[j];


warning: no viable conversion from 'const CwiseBinaryOp<internal::scalar_product_op<typename internal::traits<IndexedView<Matrix<float, -1, -1, 0, -1, -1>, Index<Extract1D<Image>>, Index<Extract1D<Image>>>>::Scalar, typename internal::promote_scalar_arg<Scalar, float, (Eigen::internal::has_ReturnType<Eigen::ScalarBinaryOpTraits<Scalar, float, Eigen::internal::scalar_product_op<Scalar, float>>>::value)>::type>, const IndexedView<Matrix<float, -1, -1, 0, -1, -1>, Index<Extract1D<Image>>, Index<Extract1D<Image>>>, const typename internal::plain_constant_type<IndexedView<Matrix<float, -1, -1, 0, -1, -1>, Index<Extract1D<Image>>, Index<Extract1D<Image>>>, typename internal::promote_scalar_arg<Scalar, float, (Eigen::internal::has_ReturnType<Eigen::ScalarBinaryOpTraits<Scalar, float, Eigen::internal::scalar_product_op<Scalar, float>>>::value)>::type>::type>' (aka 'const CwiseBinaryOp<scalar_product_op<float, float>, const Eigen::IndexedView<Eigen::Matrix<float, -1, -1, 0, -1, -1>, MR::Helper::Index<MR::Adapter::Extract1D<MR::Image>>, MR::Helper::Index<MR::Adapter::Extract1D<MR::Image>>>, const CwiseNullaryOp<scalar_constant_op, const Eigen::Matrix<float, -1, -1, 0, -1, -1>>>') to 'const float' [clang-diagnostic-error]

float const w = Wsub(dwisub.index(2), dwisub.index(3)) * Wvox[j]; ^

github-actions · 2024-09-18T16:27:25Z

cmd/dwisliceoutliergmm.cpp

+  }
+
+private:
+  const ssize_t nv, nz, ne;


warning: member 'nv' of type 'const ssize_t' (aka 'const long') is const qualified [cppcoreguidelines-avoid-const-or-ref-data-members]

const ssize_t nv, nz, ne; ^

github-actions · 2024-09-18T16:27:25Z

cmd/dwisliceoutliergmm.cpp

+  }
+
+private:
+  const ssize_t nv, nz, ne;


warning: member 'nz' of type 'const ssize_t' (aka 'const long') is const qualified [cppcoreguidelines-avoid-const-or-ref-data-members]

const ssize_t nv, nz, ne; ^

github-actions · 2024-09-18T16:27:25Z

cmd/dwisliceoutliergmm.cpp

+  }
+
+private:
+  const ssize_t nv, nz, ne;


warning: member 'ne' of type 'const ssize_t' (aka 'const long') is const qualified [cppcoreguidelines-avoid-const-or-ref-data-members]

const ssize_t nv, nz, ne; ^

github-actions · 2024-09-18T16:27:25Z

cmd/dwisliceoutliergmm.cpp

+  VecType posterior() const { return Rin.array().exp(); }
+
+private:
+  const int niter;


warning: member 'niter' of type 'const int' is const qualified [cppcoreguidelines-avoid-const-or-ref-data-members]

const int niter; ^

github-actions · 2024-09-18T16:27:26Z

cmd/dwisliceoutliergmm.cpp

+    // Log-residuals
+    int k = 0;
+    Eigen::VectorXf res(E.rows() * shells[s].count());
+    for (size_t v : shells[s].get_volumes())


warning: variable 'v' of type 'size_t' (aka 'unsigned long') can be declared 'const' [misc-const-correctness]

Suggested change

for (size_t v : shells[s].get_volumes())

for (size_t const v : shells[s].get_volumes())

github-actions · 2024-09-18T16:27:26Z

cmd/dwisliceoutliergmm.cpp

+    int k = 0;
+    Eigen::VectorXf res(E.rows() * shells[s].count());
+    for (size_t v : shells[s].get_volumes())
+      res.segment(E.rows() * (k++), E.rows()) = E.col(v);


warning: narrowing conversion from 'size_t' (aka 'unsigned long') to signed type 'Index' (aka 'long') is implementation-defined [bugprone-narrowing-conversions]

res.segment(E.rows() * (k++), E.rows()) = E.col(v); ^

github-actions · 2024-09-18T16:27:26Z

cmd/dwisliceoutliergmm.cpp

+    for (size_t v : shells[s].get_volumes())
+      res.segment(E.rows() * (k++), E.rows()) = E.col(v);
+    // clip at non-zero minimum
+    value_type nzmin = res.redux([](value_type a, value_type b) {


warning: variable 'nzmin' of type 'value_type' (aka 'float') can be declared 'const' [misc-const-correctness]

Suggested change

value_type nzmin = res.redux([](value_type a, value_type b) {

value_type const nzmin = res.redux([](value_type a, value_type b) {

github-actions · 2024-09-18T16:27:27Z

cmd/dwisliceoutliergmm.cpp

+      else
+        return (b > 0) ? b : std::numeric_limits<value_type>::infinity();


warning: do not use 'else' after 'return' [readability-else-after-return]

Suggested change

else

return (b > 0) ? b : std::numeric_limits<value_type>::infinity();

return (b > 0) ? b : std::numeric_limits<value_type>::infinity();

github-actions · 2024-09-18T16:27:27Z

cmd/dwisliceoutliergmm.cpp

+      else
+        return (b > 0) ? b : std::numeric_limits<value_type>::infinity();
+    });
+    Eigen::VectorXf logres = res.array().max(nzmin).log();


warning: variable 'logres' of type 'Eigen::VectorXf' (aka 'Matrix<float, Dynamic, 1>') can be declared 'const' [misc-const-correctness]

Suggested change

Eigen::VectorXf logres = res.array().max(nzmin).log();

Eigen::VectorXf const logres = res.array().max(nzmin).log();

dchristiaens added 30 commits November 20, 2017 15:23

Merge branch 'master' into tvreg2

38795b9

motionfilter: revert to median filtering.

52dc716

motionfilter: support volume-level transformations.

cbecd53

Integrate motion filter in motion correction script. Parameters now u…

1e6ec97

…niformly stored as yaw-pitch-roll Euler angles.

mssh2amp: fix output gradient table at 4 columns.

1ef3bd9

dwimotioncorrect: increment SVR progress bar less often.

917be84

motionfilter: add unused options to support mrtrix script multi-threa…

9f248d5

…ding.

Fix cubic interpolation kernel.

21c4ea0

dwimotioncorrect: blur recon for registration.

79f8021

motionfilter: catch numeric errors in matrix logarithm.

824c23c

dwimotioncorrect: add optional intensity matching.

9343d3d

dwirecon: small bug fix in jacobian modulation.

f23c947

dwirecon: bug fix in motion lookup and symbol renaming

467f538

motionfilter: adapt to new motion file format.

e45b6b4

dwirecon: bug fix in MB loop indexing.

f170a81

mrfieldunwarp: support motion tables of any multiband dimension.

a4ce2a8

dwirecon: print progress at info level.

0b3ff55

dwirecon: code cleanup.

27e5f55

Working first prototype for Lie-algebra rigid registration.

75e67fc

This implementation uses the Lie-algebra se(3) of the rigid transformation group SE(3), coupled with a Levenberg-Marquardt solver for optimizing the asymmetric rigid registration problem.

mrreg_asym: Fix Jacobian scaling.

9e9709b

mrreg_asym: add mask.

6b9a2f5

mrreg_asym: code organization.

1a36b3d

mrreg_asym: interface improvements.

489ab4b

mrreg_asym: add user option for starting point.

07ff722

Framework for new slice-to-volume registrtaion command.

ffbee9a

dwislicealign: set up inrastructure for s2v registration.

8eb1506

dwislicealign: implement registration.

7b4b4c2

dwislicealign: bug fixes

4f835de

dwislicealign: add progress bar.

c33dc18

dchristiaens added 3 commits September 12, 2024 13:57

Remove command dwirecon_proj

8e4bd40

Update C++ code for recent changes on dev.

f1f9770

Update Python code for recent changes on dev.

3d8f36f

This comment was marked as outdated.

Sign in to view

daljit46 reviewed Sep 13, 2024

View reviewed changes

cmd/msshsvd.cpp Show resolved Hide resolved

daljit46 reviewed Sep 13, 2024

View reviewed changes

src/dwi/svr/mapping.h Outdated Show resolved Hide resolved

dchristiaens added 2 commits September 13, 2024 14:30

Fix runtime errors.

b80bb5d

motionstats: output mean rotation in degrees

2cf67ed

Lestropie reviewed Sep 13, 2024

View reviewed changes

This comment was marked as outdated.

Sign in to view

dchristiaens added 5 commits September 13, 2024 16:00

shard: use constexpressions

72b736a

shard: use pragma once

3659512

shard: use nested namespaces

6f45946

dwirecon: remove deprecated -field option

6f011e4

shard: apply formatting rules

ee8ffb9

This comment was marked as outdated.

Sign in to view

Lestropie reviewed Sep 16, 2024

View reviewed changes

MRtrix3 deleted a comment from github-actions bot Sep 18, 2024

Apply first batch of clang-tidy suggestions

e7e0f61

github-actions bot reviewed Sep 18, 2024

View reviewed changes

dchristiaens commented Sep 18, 2024

View reviewed changes

cmd/dwisliceoutliergmm.cpp Outdated Show resolved Hide resolved

dchristiaens commented Sep 18, 2024

View reviewed changes

cmd/dwisliceoutliergmm.cpp Outdated Show resolved Hide resolved

Apply second batch of clang-tidy suggestions

cc51416

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

github-actions bot reviewed Sep 18, 2024

View reviewed changes

Replace C-style casts with C++ casts in dwirecon

2172535

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Merge SHARDRecon into main MRtrix3 codebase #2994

Merge SHARDRecon into main MRtrix3 codebase #2994

dchristiaens commented Sep 12, 2024 •

edited

Loading

This comment was marked as outdated.

Lestropie Sep 13, 2024

jdtournier Sep 13, 2024 •

edited

Loading

dchristiaens Sep 17, 2024

jdtournier Sep 17, 2024

Lestropie Sep 18, 2024

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

Lestropie Sep 16, 2024

Lestropie Sep 16, 2024

Lestropie Sep 16, 2024

Lestropie Sep 16, 2024

Lestropie commented Sep 16, 2024

github-actions bot left a comment

github-actions bot left a comment

github-actions bot Sep 18, 2024

github-actions bot Sep 18, 2024

github-actions bot Sep 18, 2024

github-actions bot Sep 18, 2024

github-actions bot Sep 18, 2024

github-actions bot Sep 18, 2024

github-actions bot Sep 18, 2024

github-actions bot Sep 18, 2024

github-actions bot Sep 18, 2024

github-actions bot Sep 18, 2024

	# Now that FORCE_OVERWRITE has been set,
	# check any user-specified output paths
	try:
	for key in vars(ARGS):
	value = getattr(ARGS, key)
	if isinstance(value, Parser._UserOutPathExtras): # pylint: disable=protected-access
	value.check_output()
	except FileExistsError as exception:
	sys.stderr.write('\n')
	sys.stderr.write(f'{EXEC_NAME}: {ANSI.error}[ERROR] {exception}{ANSI.clear}\n')
	sys.stderr.flush()
	sys.exit(1)


		# __________ Copy outputs __________

		run.command(['mrconvert', f'recon-{nepochs}.mif', app.ARGS.output], mrconvert_keyval=f'recon-{nepochs}.mif', force=app.FORCE_OVERWRITE)

	for (size_t v : shells[s].get_volumes())
	for (size_t const v : shells[s].get_volumes())

	value_type nzmin = res.redux([](value_type a, value_type b) {
	value_type const nzmin = res.redux([](value_type a, value_type b) {

		else
		return (b > 0) ? b : std::numeric_limits<value_type>::infinity();

	Eigen::VectorXf logres = res.array().max(nzmin).log();
	Eigen::VectorXf const logres = res.array().max(nzmin).log();

Merge SHARDRecon into main MRtrix3 codebase #2994

Are you sure you want to change the base?

Merge SHARDRecon into main MRtrix3 codebase #2994

Conversation

dchristiaens commented Sep 12, 2024 • edited Loading

This comment was marked as outdated.

Choose a reason for hiding this comment

jdtournier Sep 13, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Lestropie commented Sep 16, 2024

github-actions bot left a comment

Choose a reason for hiding this comment

github-actions bot left a comment

Choose a reason for hiding this comment

github-actions bot Sep 18, 2024

Choose a reason for hiding this comment

github-actions bot Sep 18, 2024

Choose a reason for hiding this comment

github-actions bot Sep 18, 2024

Choose a reason for hiding this comment

github-actions bot Sep 18, 2024

Choose a reason for hiding this comment

github-actions bot Sep 18, 2024

Choose a reason for hiding this comment

github-actions bot Sep 18, 2024

Choose a reason for hiding this comment

github-actions bot Sep 18, 2024

Choose a reason for hiding this comment

github-actions bot Sep 18, 2024

Choose a reason for hiding this comment

github-actions bot Sep 18, 2024

Choose a reason for hiding this comment

github-actions bot Sep 18, 2024

Choose a reason for hiding this comment

dchristiaens commented Sep 12, 2024 •

edited

Loading

jdtournier Sep 13, 2024 •

edited

Loading