Skip to content

Sh2amp enhancements#1617

Merged
jdtournier merged 20 commits intodevfrom
sh2amp_enhancements
Jan 21, 2020
Merged

Sh2amp enhancements#1617
jdtournier merged 20 commits intodevfrom
sh2amp_enhancements

Conversation

@jdtournier
Copy link
Member

Adds multi-shell and multi-tissue capability to shconv and sh2amp.

Briefly, this extends SH storage to allow storing SH along the 5th dimension of an image, one per shell. shconv now allows multiple ODF/response pairs (much like dwi2fod and mtnormalise do), and allows multi-shell responses (in which case it'll produce a 5D output). sh2amp can now accepts directions files in spherical or Cartesian coordinates, full-blown DW encoding files, or an image with a DW encoding in its header (required to handle multi-shell inputs).

This allows forward-modelling of all our spherical deconvolution operations, e.g. for MSMT-CSD:

shconv wm.mif wm.txt gm.mif gm.txt csf.mif csf.txt - | sh2amp - dwi_orig.mif dwi_predicted.mif

Also in there are a few changes to docs handling, and minor updates to the tests.

@jdtournier jdtournier requested a review from a team May 3, 2019 18:12
@jdtournier jdtournier self-assigned this May 3, 2019
@jdtournier jdtournier added this to the 3.0_RC4 release milestone May 3, 2019
@jdtournier jdtournier changed the base branch from master to dev May 3, 2019 18:12
@jdtournier
Copy link
Member Author

OK, quite a few tweaks to the docs - triggered by how bad the description of the SH coefficients looked...
Preview on readthedocs, e.g. shconv and sh2amp.

@Lestropie
Copy link
Member

  • Might be worth adding a reduced-FoV multi-shell DW image to the main test data repo for functionalities like these.

  • Changes are substantial enough in both commands I think to throw in secondary authorship.

@jdtournier
Copy link
Member Author

jdtournier commented May 4, 2019

Tests are already in there - see d1ba865.

Hadn't noticed the authorship. I reckon I might have earned it here... 😁

@thijsdhollander
Copy link
Contributor

I love the overall idea (both the new functionality, as well as the "convention" for 5D multi-SH-shells). Won't have time soon (aka before ISMRM) to do any testing though, but I suppose you've done quite some testing to make sure it all works, right?
Let's maybe briefly chat/confirm on Tuesday during the meeting to make sure we're all good and understanding it all correctly; that'll be more efficient rather than typing up long texts here.

One thing, now that I think of it (and so I don't forget); I'm sure it's probably clear from the code (but again, sadly I don't have the time to look thoroughly into it), but: when you provide a full gradient table (b-values and all) to the new sh2amp:

  1. I suppose it writes that gradient table also to the output header, so it becomes a "stand-alone" and fully self-consistent "dMRI dataset", right? If not (yet), I think it should definitely do that; that'd be really handy.

  2. And while I typed up point one (and made it into points 1 and 2), just realised: there must be some definition then of how the SH "shells" from the 5D input are linked to b-values, correct? I'm really assuming stuff now all the way since point 1, but I'm guessing the "definition" here is then just via increasing b-values? I.e. if 4 "shells" in the SH file and 4 b-values in the gradient table, the first "SH shell" goes with the lowest b-value, and so on? Another definition I could imagine (not per se prefer or anything though) would be the order of first appearance in the gradient table, which could be different from increasing b-value order of course. And then finally, it has to be documented clearly enough of course (if it isn't already and I'm overlooking it right now). Well, just bringing this up since it's something to consider (not sure what my opinion would be here; will have to sleep over it for a night or two, I guess). Let's go over that on Tuesday or something; it's probably simpler than I'm imagining now.

(and the authorship thing is all good of course)

@thijsdhollander
Copy link
Contributor

Wrt the above, I've come round (rather quickly after posting the above) to preferring assuming ordering with respect to increasing b-value. Still haven't found time to look into the code, documentation, or anything really; but I'm more or less assuming you probably went with that as a convention as well... it's the most consistent with a few other tools (e.g. response function estimation and such).

jdtournier added 3 commits May 7, 2019 13:55
- if full DW gradient encoding provided, add to the header as the full
  dw_scheme entry. This allows the data to be used as-is for further
  processing as an original DWI series, and generally makes sense: this
  is DW encoding that was applied to generate the data...
- remove the -shell option, since that introduces quite a bit of
  confusion as to how it applies - notably whether number of shells in
  DW encoding should match input data before or after shell selection.
  Best to rely on users to disambiguate.
- add gradient import option (should allow users to provide bvecs/bvals
  if that's how they decided to store their data)
@thijsdhollander
Copy link
Contributor

Since this alters the documentation, and introduces a new sort of "convention" wrt how SH coefficients are stored (i.e. the addition of how the 5th dimension is used in this context), it might be worthwhile or more efficient to mash this up with #1635 (or somehow combine / coordinate / ... the effort).

@thijsdhollander
Copy link
Contributor

I just coincidentally also remembered http://community.mrtrix.org/t/csd-on-standard-dwi-data/2499/5 : a current mistake in the lmax bit of the dwi2fod docs (it's essentially "lagging behind": it used to be correct, but isn't anymore since a long while). Might be worthwhile to patch that up at the same time. Essentially, this sentence:

If omitted, the command will use the highest possible lmax given the diffusion gradient table, up to a maximum of 8.

...should become:

If omitted, the command will use the highest possible lmax given the lmax of the response function(s), up to a maximum of 8.

@jdtournier jdtournier merged commit 43f93bf into dev Jan 21, 2020
@jdtournier jdtournier deleted the sh2amp_enhancements branch January 21, 2020 09:54
Lestropie added a commit that referenced this pull request Jan 28, 2020
Conflicts:
	testing/binaries/data

Note: Manual merge commit generated on test_data repo (1aac22a) to resolve divergence between #1874 and #1617.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants