Rename reorder_philips to reorder_table

scilpy/gradients/tests/test_gradients_utils.py

@@ -3,7 +3,7 @@
 
 from scilpy.gradients.bvec_bval_tools import is_normalized_bvecs
 from scilpy.gradients.utils import random_uniform_on_sphere, \
-    get_new_order_philips
+    get_new_order_table
 
 
 def test_random_uniform_on_sphere():
@@ -25,7 +25,7 @@ def test_random_uniform_on_sphere():
     assert np.all(np.asarray(smallests) > min_expected_angle)
 
 
-def test_get_new_order_philips():
+def test_get_new_order_table():
     # Using N=4 vectors
     philips_table = np.asarray([[1, 1, 1, 1],
                                 [2, 2, 2, 2],
@@ -38,7 +38,7 @@ def test_get_new_order_philips():
                         [1, 1, 1]])
     bvals = np.asarray([3, 4, 2, 1])
 
-    order = get_new_order_philips(philips_table, dwi, bvals, bvecs)
+    order = get_new_order_table(philips_table, dwi, bvals, bvecs)
 
     assert np.array_equal(bvecs[order, :], philips_table[:, 0:3])
     assert np.array_equal(bvals[order], philips_table[:, 3])

scilpy/gradients/utils.py

@@ -42,52 +42,54 @@ def random_uniform_on_sphere(nb_vectors):
     return bvecs
 
 
-def get_new_order_philips(philips_table, dwi, bvals, bvecs):
+def get_new_order_table(ref_gradients_table, dwi, bvals, bvecs):
     """
     Find the sorting order that could be applied to the bval and bvec files to
-    obtain the same order as in the philips table.
+    obtain the same order as in the reference gradient table.
+
+    This is mostly useful to reorder bval and bvec files in the order they were
+    acquired by the Philips scanner (before version 5.6).
 
     Parameters
     ----------
-    philips_table: nd.array
-        Philips gradient table, of shape (N, 4), coming from a Philips machine
-        with SoftwareVersions < 5.6.
+    ref_gradients_table: nd.array
+        Gradient table, of shape (N, 4). It will use as reference for the
+        ordering of b-vectors.
+        Ex: Could be the result of scil_gradients_generate_sampling.py
     dwi: nibabel image
         dwi of shape (x, y, z, N). Only used to confirm the dwi's shape.
     bvals : array, (N,)
-        bvals
+        bvals that need to be reordered.
     bvecs : array, (N, 3)
-        bvecs
+        bvecs that need to be reorered.
 
     Returns
     -------
     new_index: nd.array
         New index to reorder bvals/bvec
     """
-    # Check number of gradients, bvecs, bvals, dwi and oTable
-    if not (len(bvecs) == dwi.shape[3] == len(bvals) == len(philips_table)):
-        raise ValueError('bvec/bval/dwi and original table do not contain '
+    if not (len(bvecs) == dwi.shape[3] == len(bvals) ==
+            len(ref_gradients_table)):
+        raise ValueError('bvec/bval/dwi and reference table do not contain '
                          'the same number of gradients.')
 
-    # Check bvals
-    philips_bval = np.unique(philips_table[:, 3])
-
-    philips_dwi_shells = philips_bval[philips_bval > 1]
-    philips_b0s = philips_bval[philips_bval < 1]
+    ref_bval = np.unique(ref_gradients_table[:, 3])
+    ref_dwi_shells = ref_bval[ref_bval > 1]
+    ref_b0s = ref_bval[ref_bval < 1]
 
     dwi_shells = np.unique(bvals[bvals > 1])
     b0s = np.unique(bvals[bvals < 1])
 
-    if len(philips_dwi_shells) != len(dwi_shells) or \
-       len(philips_b0s) != len(b0s):
-        raise ValueError('bvec/bval/dwi and original table do not contain '
+    if len(ref_dwi_shells) != len(dwi_shells) or \
+       len(ref_b0s) != len(b0s):
+        raise ValueError('bvec/bval/dwi and reference table do not contain '
                          'the same shells.')
 
     new_index = np.zeros(bvals.shape)
 
-    for nbval in philips_bval:
+    for nbval in ref_bval:
         curr_bval = np.where(bvals == nbval)[0]
-        curr_bval_table = np.where(philips_table[:, 3] == nbval)[0]
+        curr_bval_table = np.where(ref_gradients_table[:, 3] == nbval)[0]
 
         if len(curr_bval) != len(curr_bval_table):
             raise ValueError('bval/bvec and orginal table do not contain '

scripts/scil_dwi_reorder_philips.py

@@ -18,7 +18,7 @@
 import nibabel as nib
 import numpy as np
 
-from scilpy.gradients.utils import get_new_order_philips
+from scilpy.gradients.utils import get_new_order_table
 from scilpy.io.utils import (add_overwrite_arg,
                              add_verbose_arg,
                              assert_inputs_exist,
@@ -90,7 +90,7 @@ def main():
     bvals, bvecs = read_bvals_bvecs(args.in_bval, args.in_bvec)
     dwi = nib.load(args.in_dwi)
 
-    new_index = get_new_order_philips(philips_table, dwi, bvals, bvecs)
+    new_index = get_new_order_table(philips_table, dwi, bvals, bvecs)
     bvecs = bvecs[new_index]
     bvals = bvals[new_index]