Merge pull request #198 from jhlegarreta/AddShellDetectionUtils

ENH: Add DWI shell detection utils

src/eddymotion/data/ds000114_singleshell.bval

@@ -0,0 +1 @@
+0 0 0 0 0 0 0 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000

src/eddymotion/data/ds000114_singleshell.bvec

@@ -0,0 +1,3 @@
+0 0 0 0 0 0 0 -1 -0.002 0.026 -0.591 0.236 0.893 -0.796 -0.234 -0.936 -0.506 -0.346 -0.457 0.487 0.618 0.577 0.827 -0.894 -0.29 -0.116 0.8 -0.514 0.789 -0.949 -0.233 0.021 -0.217 -0.774 0.161 0.147 -0.888 0.562 0.381 0.306 0.332 0.963 0.959 -0.453 0.773 -0.709 0.693 -0.682 0.142 0.74 0.103 -0.584 0.088 0.552 -0.838 -0.363 0.184 0.721 -0.433 -0.502 0.171 -0.463 -0.385 0.713 -0.26 -0.001 -0.037 -0.57 0.282 -0.721 -0.267
+0 0 0 0 0 0 0 0 1 0.649 -0.766 -0.524 -0.259 0.129 0.93 0.14 -0.845 -0.847 -0.631 -0.389 0.673 -0.105 -0.521 -0.04 -0.541 -0.963 0.403 0.84 0.153 -0.233 0.783 -0.188 -0.956 -0.604 0.356 0.731 0.417 0.232 0.143 -0.199 -0.13 -0.265 0.205 -0.889 0.628 0.408 0.024 0.529 -0.725 0.388 0.822 -0.596 -0.335 -0.792 -0.458 -0.561 0.392 -0.693 0.682 0.69 -0.509 0.423 -0.809 -0.247 0.885 0.077 -0.902 -0.303 0.145 0.608 0.96
+0 0 0 0 0 0 0 0 0 0.76 0.252 0.818 0.368 0.591 0.284 0.324 -0.175 -0.402 -0.627 0.782 0.407 -0.81 0.213 -0.447 -0.789 -0.245 -0.444 0.174 -0.596 0.211 0.577 -0.982 0.199 0.19 0.921 -0.666 0.193 -0.794 0.914 -0.931 0.934 0.044 0.193 0.068 0.088 0.575 0.721 -0.506 0.674 0.549 0.56 0.551 0.938 0.259 -0.296 0.744 -0.901 0.009 -0.589 0.521 -0.844 0.779 0.444 0.656 -0.387 -0.997 0.43 -0.763 -0.948 0.332 -0.085

src/eddymotion/data/ds004737_dsi.bval

@@ -0,0 +1 @@
+5 5 4195 3590 4790 4990 3790 2590 1800 4195 995 4990 2595 2795 5 5000 3395 1795 3595 2790 2190 4390 5000 1195 1195 2795 4990 5 1795 995 2195 4795 4985 5000 2795 1790 1595 4795 1995 800 5 2790 2190 3790 5000 1595 4990 2795 1195 2195 1800 2000 3595 5 4395 2000 2600 4990 2000 2195 4390 800 2795 1595 2790 4790 5 3395 1195 1795 2195 5000 4990 2395 4795 4795 1000 1195 995 5 2190 1990 4990 2795 3395 995 5000 2595 3400 1990 795 995 1795 1990 1195 1795 1795 2600 2395 4990 1000 1600 1995 5

src/eddymotion/data/ds004737_dsi.bvec

@@ -0,0 +1,3 @@
+-0.5 -0.5 -0.873381 0.707894 0.408703 0 0.229712 0 0 -0.436552 0.895769 -0.800629 0 0.802493 -0.5 -0.599999 -0.970507 0.333952 -0.943136 -0.267753 -0.302149 0.426759 0.999999 -0.408871 0.817403 0.534767 0 -0.5 0.333952 0 0.301735 0.408432 0 -0.799999 -0.802199 0 -0.708215 0.408432 0 0 -0.5 -0.53522 -0.302149 -0.229712 0 0 -0.600667 -0.534767 0.817403 -0.301735 0.999998 -0.948681 -0.943136 -0.5 -0.639981 0.948681 0.832049 0.600667 0.316227 -0.301735 -0.426759 0.999993 0.802199 0.708215 0.267753 0.408703 -0.5 0.485415 -0.409158 -0.667533 -0.905069 0.799999 0 -0.577993 -0.408432 -0.81695 0.894423 0.408871 0.448471 -0.5 0.302149 0 0.800629 0.534767 0.970507 -0.895769 0.599999 0 0.242535 -0.31699 0 0 0.667533 0 -0.409158 -0.667533 -0.333952 -0.554699 -0.577993 0 -0.894423 -0.707104 0.94933 -0.5
+-0.5 -0.5 0.218371 0 0.408703 -0.600667 -0.688954 0.555515 -0.999998 -0.873155 1e-08 0 -0.832872 0.267561 -0.5 -0.799999 0 0.667533 -0.2358 0.53522 0.302149 -0.640211 0 0.817403 -0.408871 -0.802199 -0.800629 -0.5 -0.667533 0.448471 0.905069 0.81695 0 -0.6 0.534767 0 0 -0.81695 0.94933 -0.999993 -0.5 -0.267753 -0.302149 -0.688954 -0.999999 -0.708215 0 -0.802199 0.408871 -0.905069 0 -0.316227 0.2358 -0.5 0.639981 -0.316227 -0.554699 0 -0.948681 0.905069 0.640211 0 0.534767 0 0.53522 -0.408703 -0.5 -0.728195 0.409158 0.333952 0.301735 -0.6 0.800629 0.577993 0.81695 -0.408433 -0.44721 -0.817403 0 -0.5 -0.302149 0.31699 0 0.802199 0 -1e-08 -0.799999 0.832872 -0.970142 0 0 -0.895769 0.333952 -0.31699 -0.409158 -0.333952 -0.667533 -0.832049 -0.577993 0.600667 -0.44721 -0.707104 0 -0.5
+0.707107 0.707107 -0.435338 -0.706319 -0.816042 -0.799499 -0.687441 -0.831507 0.00222221 -0.216846 -0.44452 -0.59916 -0.553466 -0.533306 0.707107 0.00128 -0.241074 -0.665489 -0.234294 -0.801154 -0.904109 -0.638754 0.0014 -0.405803 -0.405803 -0.265521 -0.59916 0.707107 -0.665489 -0.893797 -0.299677 -0.407155 -1 0.00128 -0.265521 -1 -0.705997 -0.407155 -0.31428 0.00374992 0.707107 -0.801154 -0.904109 -0.687441 0.0014 -0.705997 -0.799499 -0.265521 -0.405803 -0.299677 0.00222221 0.00205547 -0.234294 0.707107 -0.425263 0.00205547 0.00192011 -0.799499 0.00205547 -0.299677 -0.638754 0.00374992 -0.265521 -0.705997 -0.801154 -0.816042 0.707107 -0.483843 -0.815585 -0.665489 -0.299677 0.00128 -0.59916 -0.576063 -0.407155 -0.407155 0.00313045 -0.405803 -0.893797 0.707107 -0.904109 -0.948429 -0.59916 -0.265521 -0.241074 -0.44452 0.00128 -0.553466 0.00149801 -0.948429 -1 -0.44452 -0.665489 -0.948429 -0.815585 -0.665489 -0.665489 0.00192011 -0.576063 -0.799499 0.00313045 0.00265162 -0.31428 0.707107

src/eddymotion/data/hcph_multishell.bval

@@ -0,0 +1 @@
+0 3000 3000 3000 2000 2000 700 3000 2000 1000 1000 2000 3000 3000 1000 1000 3000 3000 3000 3000 2000 3000 2000 2000 3000 2000 2000 2000 1000 3000 3000 3000 3000 3000 3000 2000 3000 2000 2000 2000 3000 2000 3000 2000 1000 3000 2000 0 3000 1000 3000 3000 2000 2000 700 3000 3000 2000 3000 700 3000 2000 2000 3000 2000 2000 3000 2000 3000 3000 2000 3000 2000 3000 1000 1000 3000 1000 2000 700 2000 1000 2000 3000 3000 700 3000 2000 3000 1000 3000 2000 1000 2000 0 3000 1000 1000 3000 3000 3000 1000 3000 2000 2000 2000 3000 3000 2000 2000 3000 700 3000 3000 2000 1000 2000 3000 3000 3000 2000 3000 3000 3000 1000 3000 2000 1000 2000 2000 2000 3000 3000 3000 1000 3000 3000 3000 3000 3000 0 3000 3000 3000 2000 2000 700 3000 2000 1000 1000 2000 3000 3000 1000 1000 3000 3000 3000 3000 2000 3000 2000 2000 3000 2000 2000 2000 1000 3000 3000 3000 3000 3000 3000 2000 3000 2000 2000 2000 3000 2000 3000 2000 1000 3000 2000 0 3000 1000 3000 3000 2000 2000 700 3000 3000 2000 3000 700 3000 2000 2000 3000 2000 2000 3000 2000 3000 3000 2000 3000 2000 3000 1000 1000 3000 1000 2000 700 2000 1000 2000 3000 3000 700 3000 2000 3000 1000 3000 2000 1000 2000 0 3000 1000 1000 3000 3000 3000 1000 3000 2000 2000 2000 3000 3000 2000 2000 3000 700 3000 3000 2000 1000 2000 3000 3000 3000 2000 3000 3000 3000 1000 3000 2000 1000 2000 2000 2000 3000 3000 3000 1000 3000 3000 3000 3000 3000

src/eddymotion/data/hcph_multishell.bvec

@@ -0,0 +1,3 @@
+0 -0.431427 -0.777829 0.817684 -0.733626 -0.725871 0.500357 -0.348823 0.790982 0.462643 0.830112 -0.793024 -0.770191 -0.796056 0.524394 -0.377388 -0.1541 -0.432124 -0.0227465 -0.404595 -0.964759 0.811432 -0.387961 -0.183432 0.352117 0.562912 0.327186 -0.312644 0.310175 0.555496 -0.181488 0.0366116 0.550501 -0.967624 -0.566167 -0.260057 0.236983 0.0159473 -0.656836 0.686091 -0.661405 0.868317 -0.947228 -0.984373 -0.529497 0.141169 -0.384427 0 -0.375458 -0.479656 -0.661357 -0.651741 0.95434 0.409035 -0.905405 -0.993953 0.136116 -0.174534 0.782861 -0.768233 0.293511 -0.889283 0.587158 -0.877346 -0.0196863 0.212573 0.360426 -0.643135 0.66263 0.126129 0.771551 0.84567 -0.502549 -0.260374 -0.874138 -0.142399 0.314416 -0.996741 -0.289206 0.077071 -0.903828 -0.226346 -0.916842 0.0489337 -0.334019 -0.536482 0.496928 -0.44644 0.1715 0.772233 0.426812 -0.521929 0.736977 -0.346427 0 -0.91955 0.880525 0.196827 0.877612 -0.634666 0.428904 0.163557 -0.214394 -0.235799 0.614832 -0.107899 0.0429176 0.665558 0.417142 0.501095 -0.716501 -0.100707 -0.0234835 0.167525 0.69476 0.308228 -0.332848 -0.435819 -0.961102 0.417856 0.162924 -0.716055 -0.604956 0.947321 -0.0217008 0.619147 -0.0419929 -0.782928 0.085662 0.796198 0.0136493 -0.123114 -0.628069 -0.133774 0.589758 0.852626 -0.577165 -0.910148 0.562002 0.239299 0 0.432181 0.78074 -0.820699 0.736695 0.721423 -0.493625 0.351234 -0.78814 -0.462758 -0.833852 0.790378 0.767283 0.799744 -0.530215 0.373653 0.152921 0.42939 0.0224025 0.403143 0.96512 -0.812486 0.390215 0.182026 -0.354129 -0.561657 -0.324678 0.312958 -0.307316 -0.55234 0.18236 -0.0364422 -0.553256 0.965855 0.568811 0.261118 -0.238731 -0.0159745 0.661189 -0.687955 0.663342 -0.867796 0.946101 0.983311 0.527368 -0.140127 0.387543 0 0.377426 0.485227 0.65946 0.654582 -0.952295 -0.411823 0.905133 0.994563 -0.137112 0.175738 -0.783648 0.769365 -0.294938 0.885975 -0.585802 0.878998 0.0198078 -0.213856 -0.359872 0.642171 -0.666244 -0.126538 -0.767283 -0.842847 0.499985 0.26032 0.878726 0.143537 -0.312294 0.99639 0.288058 -0.0763895 0.907159 0.223486 0.914037 -0.0487249 0.336271 0.530339 -0.498623 0.442878 -0.171518 -0.769954 -0.425088 0.52456 -0.731168 0.343039 0 0.922161 -0.882143 -0.195114 -0.876499 0.631117 -0.431857 -0.162437 0.213369 0.236862 -0.618525 0.107167 -0.043416 -0.665169 -0.418174 -0.497479 0.717862 0.100896 0.0234955 -0.166994 -0.698588 -0.310068 0.333111 0.435272 0.962584 -0.416365 -0.161655 0.713686 0.605092 -0.947413 0.0212877 -0.615662 0.0419711 0.776773 -0.0858871 -0.796065 -0.0138097 0.123918 0.631451 0.134368 -0.586789 -0.855885 0.57652 0.908208 -0.564762 -0.240063
+0 -0.874634 0.358741 0.273046 0.517025 -0.0489007 0.0370236 -0.155773 0.464164 0.885615 0.439312 0.495822 0.366764 -0.0479591 0.363031 0.532812 0.378144 0.338146 -0.548434 0.805356 -0.257782 0.560139 0.668326 -0.448383 0.460491 -0.791828 -0.0448395 0.949168 0.707746 0.290287 0.74955 -0.287116 0.523256 -0.0081493 0.568615 -0.862813 0.237802 0.257507 -0.13824 0.659808 -0.639559 -0.492768 -0.279944 0.137121 0.801499 0.439767 -0.350537 0 -0.542496 0.198997 0.649003 -0.461302 -0.196091 0.648838 -0.423866 0.0666411 -0.11905 0.410168 -0.607957 0.634166 -0.685519 0.158631 0.76821 0.408567 -0.995069 -0.52238 -0.909792 0.753873 -0.141052 -0.884727 -0.17146 0.300382 0.673639 -0.960685 0.245213 0.59588 -0.245851 -0.0773828 0.905123 0.884651 -0.122335 -0.0370792 -0.220811 -0.902475 0.517323 0.117255 0.74236 -0.210288 -0.974946 0.59427 0.765861 -0.598847 0.269321 0.176367 0 0.0713276 -0.448025 0.272712 0.450292 -0.201561 0.019856 -0.96069 -0.697994 0.875882 -0.342947 0.79012 -0.631579 0.742867 0.861529 -0.389142 0.64023 -0.825399 0.993765 0.957419 0.398529 0.788178 -0.939682 0.890978 -0.175857 -0.790437 0.616579 -0.543886 0.794123 -0.320023 0.954863 -0.055031 -0.108061 0.165741 0.953512 0.604953 0.724883 -0.0165835 0.303738 -0.778982 -0.695381 0.0128555 -0.799162 0.297478 -0.520108 0.891726 0 0.875992 -0.360131 -0.274103 -0.519261 0.0483437 -0.0356367 0.156622 -0.462642 -0.886071 -0.441108 -0.494259 -0.36508 0.0482516 -0.366439 -0.527696 -0.37551 -0.33611 0.545034 -0.802745 0.258091 -0.560718 -0.672093 0.44505 -0.463246 0.790137 0.0447117 -0.94937 -0.702132 -0.288434 -0.752947 0.285193 -0.525664 0.00787 -0.57123 0.86609 -0.239281 -0.255318 0.139311 -0.661572 0.641447 0.492602 0.279645 -0.137148 -0.798931 -0.436785 0.353035 0 0.545421 -0.20048 -0.647267 0.463458 0.195761 -0.652546 0.423229 -0.0668755 0.119657 -0.413504 0.608456 -0.634699 0.688888 -0.158071 -0.766436 -0.40925 0.995881 0.526227 0.908427 -0.753044 0.141731 0.887612 0.170479 -0.29941 -0.670313 0.959947 -0.246016 -0.602073 0.244384 0.0773728 -0.902692 -0.878445 0.122806 0.0371374 0.220235 0.899617 -0.52025 -0.115388 -0.744848 0.208683 0.975977 -0.592275 -0.763218 0.602453 -0.266871 -0.174552 0 -0.0713703 0.448801 -0.268804 -0.449796 0.200574 -0.0202691 0.957861 0.69445 -0.879253 0.34496 -0.785795 0.63511 -0.742455 -0.863778 0.386496 -0.641596 0.818823 -0.994536 -0.95578 -0.400829 -0.793914 0.940282 -0.890179 0.176245 0.787896 -0.61224 0.542135 -0.794528 0.319964 -0.951215 0.0547723 0.107149 -0.164253 -0.955974 -0.604898 -0.729354 0.0166774 -0.305433 0.782478 0.691626 -0.0127356 0.798087 -0.296942 0.522437 -0.89414
+0 -0.221102 -0.516031 -0.506793 -0.440996 0.686091 0.865027 -0.924152 0.398622 -0.0406028 -0.343395 0.35394 0.521814 -0.603319 -0.770207 0.757423 0.912831 0.836018 0.835885 0.433249 -0.0528156 -0.166801 -0.634686 0.874817 -0.814838 0.236934 0.943895 -0.0365274 0.634734 0.779203 -0.636583 0.957196 -0.650501 0.252266 -0.596768 -0.433501 -0.94196 0.966145 -0.741253 -0.306484 -0.391801 0.0566204 0.156176 0.110486 0.277906 0.886948 -0.854014 0 -0.751485 -0.854594 0.376035 -0.602025 0.225351 -0.641638 0.0240817 -0.0872675 -0.983514 -0.895154 -0.132348 -0.0874726 -0.666269 0.428967 0.255145 -0.25167 -0.0972135 -0.825792 0.205842 0.134363 -0.735545 -0.448719 0.612626 0.44115 0.5419 0.0963817 -0.419228 -0.790348 0.916897 0.0227934 0.311629 0.45984 -0.410036 0.973341 0.332631 0.427953 -0.787914 0.835726 -0.449405 0.869753 -0.141663 0.22472 0.480925 -0.607431 0.619944 0.921349 0 -0.386447 -0.154754 0.941747 0.164421 0.746038 -0.903132 0.224331 0.683257 -0.420986 -0.710189 0.603381 -0.774123 0.0719813 -0.289414 0.772963 -0.277004 0.555495 -0.108996 0.235125 -0.598734 -0.532702 -0.0787995 0.127357 -0.212972 0.447891 0.77025 0.437554 -0.0582803 -0.0129877 0.296252 0.783345 0.993257 0.599628 -0.288924 0.0100272 -0.688737 -0.992254 -0.71643 -0.612611 0.410648 -0.522364 0.167987 0.288335 -0.64315 -0.384136 0 0.214146 0.510637 0.501319 0.433185 -0.690805 -0.868945 0.923095 -0.405953 0.0270774 0.331835 -0.361953 -0.52725 0.5984 0.764588 -0.762837 -0.914116 -0.838245 -0.838114 -0.439404 0.043952 0.159568 0.629304 -0.876811 0.812402 -0.245409 -0.944767 0.0274551 -0.642314 -0.78213 0.632309 -0.957777 0.646208 -0.258964 0.591736 0.426269 0.941144 -0.966725 0.737171 0.298398 0.385387 -0.0653722 -0.163377 -0.119541 -0.289124 -0.888585 0.851573 0 0.748375 0.851095 -0.382306 0.597268 -0.23412 0.63607 -0.0401361 0.0798253 0.983302 0.893382 0.125204 0.0723542 0.662152 -0.435961 -0.263462 0.244697 0.0884741 0.823013 -0.212726 -0.143322 0.732142 0.442868 -0.618234 -0.447172 -0.548357 -0.103612 0.409043 0.785433 -0.918013 -0.0349231 -0.31964 -0.471698 0.402469 -0.973999 -0.340637 -0.433953 0.785023 -0.839897 0.44337 -0.871958 0.134351 -0.237448 -0.486619 0.601571 -0.627832 -0.92296 0 0.380164 0.142832 -0.943226 -0.171558 -0.749307 0.901714 -0.236889 -0.687178 0.413292 0.705996 -0.609132 0.7712 -0.0794455 0.281102 -0.776618 0.270237 -0.56511 0.101721 -0.242068 0.592716 0.523027 0.070047 -0.134611 0.205839 -0.453718 -0.77397 -0.443555 0.0508823 0.00558113 -0.307793 -0.786104 -0.993357 -0.607984 0.280602 -0.0194886 0.683997 0.992152 0.712727 0.608007 -0.421108 0.51701 -0.175164 -0.294931 0.63883 0.378

src/eddymotion/model/dmri_utils.py

@@ -0,0 +1,94 @@
+# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
+# vi: set ft=python sts=4 ts=4 sw=4 et:
+#
+# Copyright 2024 The NiPreps Developers <[email protected]>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY kIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# We support and encourage derived works from this project, please read
+# about our expectations at
+#
+#     https://www.nipreps.org/community/licensing/
+#
+import numpy as np
+
+DEFAULT_NUM_BINS = 15
+"""Number of bins to classify b-values."""
+
+DEFAULT_MULTISHELL_BIN_COUNT_THR = 7
+"""Default bin count to consider a multishell scheme."""
+
+DEFAULT_MAX_BVAL = 8000
+"""Maximum b-value cap."""
+
+
+def find_shelling_scheme(
+    bvals,
+    num_bins=DEFAULT_NUM_BINS,
+    multishell_nonempty_bin_count_thr=DEFAULT_MULTISHELL_BIN_COUNT_THR,
+    bval_cap=DEFAULT_MAX_BVAL,
+):
+    """
+    Find the shelling scheme on the given b-values.
+
+    Computes the histogram of the b-values according to ``num_bins``
+    and depending on the nonempty bin count, classify the shelling scheme
+    as single-shell if they are 2 (low-b and a shell); multi-shell if they are
+    below the ``multishell_nonempty_bin_count_thr`` value; and DSI otherwise.
+
+    Parameters
+    ----------
+    bvals : :obj:`list` or :obj:`~numpy.ndarray`
+         List or array of b-values.
+    num_bins : :obj:`int`, optional
+        Number of bins.
+    multishell_nonempty_bin_count_thr : :obj:`int`, optional
+        Bin count to consider a multi-shell scheme.
+
+    Returns
+    -------
+    scheme : :obj:`str`
+        Shelling scheme.
+    bval_groups : :obj:`list`
+        List of grouped b-values.
+    bval_estimated : :obj:`list`
+        List of 'estimated' b-values as the median value of each b-value group.
+
+    """
+
+    # Bin the b-values: use -1 as the lower bound to be able to appropriately
+    # include b0 values
+    hist, bin_edges = np.histogram(bvals, bins=num_bins, range=(-1, min(max(bvals), bval_cap)))
+
+    # Collect values in each bin
+    bval_groups = []
+    bval_estimated = []
+    for lower, upper in zip(bin_edges[:-1], bin_edges[1:], strict=False):
+        # Add only if a nonempty b-values mask
+        if (mask := (bvals > lower) & (bvals <= upper)).sum():
+            bval_groups.append(bvals[mask])
+            bval_estimated.append(np.median(bvals[mask]))
+
+    nonempty_bins = len(bval_groups)
+
+    if nonempty_bins < 2:
+        raise ValueError("DWI must have at least one high-b shell")
+
+    if nonempty_bins == 2:
+        scheme = "single-shell"
+    elif nonempty_bins < multishell_nonempty_bin_count_thr:
+        scheme = "multi-shell"
+    else:
+        scheme = "DSI"
+
+    return scheme, bval_groups, bval_estimated