docs

dmipy/core/acquisition_scheme.py

@@ -323,6 +323,20 @@ def visualise_acquisition_G_Delta_rainbow(
 
 
 class RotationalHarmonicsAcquisitionScheme:
+    """
+    AcquisitionScheme instance that contains the information necessary to
+    calculate the rotational harmonics for a model for every acquisition shell.
+    It is instantiated using a regular DmipyAcquisitionScheme and
+    N_angular_samples determines how many samples are taken between mu=[0., 0.]
+    and mu=[np.pi/2, 0.].
+
+    Parameters
+    ----------
+    dmipy_acquisition_scheme: DmipyAcquisitionScheme instance
+        An acquisition scheme that has been instantiated using dMipy.
+    N_angular_samples: int
+        Integer representing the number of angular samples per shell.
+    """
     def __init__(self, dmipy_acquisition_scheme, N_angular_samples=10):
         self.Nsamples = N_angular_samples
         scheme = dmipy_acquisition_scheme

dmipy/distributions/distribute_models.py

@@ -673,29 +673,26 @@ def rotational_harmonics_representation(
             self, acquisition_scheme, **kwargs):
         r""" The rotational harmonics of the model, such that Y_lm = Yl0.
         Axis aligned with z-axis to be used as kernel for spherical
-        convolution.
+        convolution. Returns an array with rotational harmonics for each shell.
 
         Parameters
         ----------
-        bvalue : float,
-            b-value in s/m^2.
-        qvalue : float,
-            diffusion sensitization in 1/m.
-        Delta: float,
-            Delta parameter in seconds.
-        sh_order : int,
-            maximum spherical harmonics order to be used in the approximation.
+        acquisition_scheme : DmipyAcquisitionScheme instance,
+            An acquisition scheme that has been instantiated using dMipy.
+        kwargs: keyword arguments to the model parameter values,
+            Is internally given as **parameter_dictionary.
 
         Returns
         -------
-        rh : array,
-            rotational harmonics of stick model aligned with z-axis.
+        rh_array : array, shape(Nshells, N_rh_coef),
+            Rotational harmonics coefficients for each shell.
         """
         rh_scheme = acquisition_scheme.rotational_harmonics_scheme
         kwargs.update({self.mu_param: [0., 0.]})
         E_kernel_sf = self(rh_scheme, **kwargs)
         E_reshaped = E_kernel_sf.reshape([-1, rh_scheme.Nsamples])
-        rh_array = np.zeros((len(E_reshaped), rh_scheme.Nsamples))
+        rh_array = np.zeros((len(E_reshaped),
+                             rh_scheme.shell_sh_orders.max() // 2 + 1))
 
         for i, sh_order in enumerate(rh_scheme.shell_sh_orders):
             rh_array[i, :sh_order // 2 + 1] = (

dmipy/signal_models/cylinder_models.py

@@ -92,29 +92,26 @@ def rotational_harmonics_representation(
             self, acquisition_scheme, **kwargs):
         r""" The rotational harmonics of the model, such that Y_lm = Yl0.
         Axis aligned with z-axis to be used as kernel for spherical
-        convolution.
+        convolution. Returns an array with rotational harmonics for each shell.
 
         Parameters
         ----------
-        bvalue : float,
-            b-value in s/m^2.
-        qvalue : float,
-            diffusion sensitization in 1/m.
-        Delta: float,
-            Delta parameter in seconds.
-        sh_order : int,
-            maximum spherical harmonics order to be used in the approximation.
+        acquisition_scheme : DmipyAcquisitionScheme instance,
+            An acquisition scheme that has been instantiated using dMipy.
+        kwargs: keyword arguments to the model parameter values,
+            Is internally given as **parameter_dictionary.
 
         Returns
         -------
-        rh : array,
-            rotational harmonics of stick model aligned with z-axis.
+        rh_array : array, shape(Nshells, N_rh_coef),
+            Rotational harmonics coefficients for each shell.
         """
         rh_scheme = acquisition_scheme.rotational_harmonics_scheme
         kwargs.update({'mu': [0., 0.]})
         E_kernel_sf = self(rh_scheme, **kwargs)
         E_reshaped = E_kernel_sf.reshape([-1, rh_scheme.Nsamples])
-        rh_array = np.zeros((len(E_reshaped), rh_scheme.Nsamples))
+        rh_array = np.zeros((len(E_reshaped),
+                             rh_scheme.shell_sh_orders.max() // 2 + 1))
 
         for i, sh_order in enumerate(rh_scheme.shell_sh_orders):
             rh_array[i, :sh_order // 2 + 1] = (
@@ -262,29 +259,26 @@ def rotational_harmonics_representation(
             self, acquisition_scheme, **kwargs):
         r""" The rotational harmonics of the model, such that Y_lm = Yl0.
         Axis aligned with z-axis to be used as kernel for spherical
-        convolution.
+        convolution. Returns an array with rotational harmonics for each shell.
 
         Parameters
         ----------
-        bvalue : float,
-            b-value in s/m^2.
-        qvalue : float,
-            diffusion sensitization in 1/m.
-        Delta: float,
-            Delta parameter in seconds.
-        sh_order : int,
-            maximum spherical harmonics order to be used in the approximation.
+        acquisition_scheme : DmipyAcquisitionScheme instance,
+            An acquisition scheme that has been instantiated using dMipy.
+        kwargs: keyword arguments to the model parameter values,
+            Is internally given as **parameter_dictionary.
 
         Returns
         -------
-        rh : array,
-            rotational harmonics of stick model aligned with z-axis.
+        rh_array : array, shape(Nshells, N_rh_coef),
+            Rotational harmonics coefficients for each shell.
         """
         rh_scheme = acquisition_scheme.rotational_harmonics_scheme
         kwargs.update({'mu': [0., 0.]})
         E_kernel_sf = self(rh_scheme, **kwargs)
         E_reshaped = E_kernel_sf.reshape([-1, rh_scheme.Nsamples])
-        rh_array = np.zeros((len(E_reshaped), rh_scheme.Nsamples))
+        rh_array = np.zeros((len(E_reshaped),
+                             rh_scheme.shell_sh_orders.max() // 2 + 1))
 
         for i, sh_order in enumerate(rh_scheme.shell_sh_orders):
             rh_array[i, :sh_order // 2 + 1] = (
@@ -468,29 +462,26 @@ def rotational_harmonics_representation(
             self, acquisition_scheme, **kwargs):
         r""" The rotational harmonics of the model, such that Y_lm = Yl0.
         Axis aligned with z-axis to be used as kernel for spherical
-        convolution.
+        convolution. Returns an array with rotational harmonics for each shell.
 
         Parameters
         ----------
-        bvalue : float,
-            b-value in s/m^2.
-        qvalue : float,
-            diffusion sensitization in 1/m.
-        Delta: float,
-            Delta parameter in seconds.
-        sh_order : int,
-            maximum spherical harmonics order to be used in the approximation.
+        acquisition_scheme : DmipyAcquisitionScheme instance,
+            An acquisition scheme that has been instantiated using dMipy.
+        kwargs: keyword arguments to the model parameter values,
+            Is internally given as **parameter_dictionary.
 
         Returns
         -------
-        rh : array,
-            rotational harmonics of stick model aligned with z-axis.
+        rh_array : array, shape(Nshells, N_rh_coef),
+            Rotational harmonics coefficients for each shell.
         """
         rh_scheme = acquisition_scheme.rotational_harmonics_scheme
         kwargs.update({'mu': [0., 0.]})
         E_kernel_sf = self(rh_scheme, **kwargs)
         E_reshaped = E_kernel_sf.reshape([-1, rh_scheme.Nsamples])
-        rh_array = np.zeros((len(E_reshaped), rh_scheme.Nsamples))
+        rh_array = np.zeros((len(E_reshaped),
+                             rh_scheme.shell_sh_orders.max() // 2 + 1))
 
         for i, sh_order in enumerate(rh_scheme.shell_sh_orders):
             rh_array[i, :sh_order // 2 + 1] = (
@@ -638,33 +629,28 @@ def __call__(self, acquisition_scheme, **kwargs):
 
     def rotational_harmonics_representation(
             self, acquisition_scheme, **kwargs):
-        r""" The rotational harmonics of the mode, such that Y_lm = Yl0.
-        Axis aligned with z-axis to be used as kernelfor spherical
-        convolution.
+        r""" The rotational harmonics of the model, such that Y_lm = Yl0.
+        Axis aligned with z-axis to be used as kernel for spherical
+        convolution. Returns an array with rotational harmonics for each shell.
 
         Parameters
         ----------
-        bval : float,
-            b-value in s/m^2.
-        gradient_strength : float,
-            gradient strength in T/m.
-        delta: float,
-            delta parameter in seconds.
-        Delta: float,
-            Delta parameter in seconds.
-        sh_order : int,
-            maximum spherical harmonics order to be used in the approximation.
+        acquisition_scheme : DmipyAcquisitionScheme instance,
+            An acquisition scheme that has been instantiated using dMipy.
+        kwargs: keyword arguments to the model parameter values,
+            Is internally given as **parameter_dictionary.
 
         Returns
         -------
-        rh : array,
-            rotational harmonics of stick model aligned with z-axis.
+        rh_array : array, shape(Nshells, N_rh_coef),
+            Rotational harmonics coefficients for each shell.
         """
         rh_scheme = acquisition_scheme.rotational_harmonics_scheme
         kwargs.update({'mu': [0., 0.]})
         E_kernel_sf = self(rh_scheme, **kwargs)
         E_reshaped = E_kernel_sf.reshape([-1, rh_scheme.Nsamples])
-        rh_array = np.zeros((len(E_reshaped), rh_scheme.Nsamples))
+        rh_array = np.zeros((len(E_reshaped),
+                             rh_scheme.shell_sh_orders.max() // 2 + 1))
 
         for i, sh_order in enumerate(rh_scheme.shell_sh_orders):
             rh_array[i, :sh_order // 2 + 1] = (

dmipy/signal_models/gaussian_models.py

@@ -78,31 +78,28 @@ def rotational_harmonics_representation(
             self, acquisition_scheme, **kwargs):
         r""" The rotational harmonics of the model, such that Y_lm = Yl0.
         Axis aligned with z-axis to be used as kernel for spherical
-        convolution.
+        convolution. Returns an array with rotational harmonics for each shell.
 
         Parameters
         ----------
-        bvalue : float,
-            b-value in s/m^2.
-        qvalue : float,
-            diffusion sensitization in 1/m.
-        Delta: float,
-            Delta parameter in seconds.
-        sh_order : int,
-            maximum spherical harmonics order to be used in the approximation.
+        acquisition_scheme : DmipyAcquisitionScheme instance,
+            An acquisition scheme that has been instantiated using dMipy.
+        kwargs: keyword arguments to the model parameter values,
+            Is internally given as **parameter_dictionary.
 
         Returns
         -------
-        rh : array,
-            rotational harmonics of stick model aligned with z-axis.
+        rh_array : array, shape(Nshells, N_rh_coef),
+            Rotational harmonics coefficients for each shell.
         """
         rh_scheme = acquisition_scheme.rotational_harmonics_scheme
+        kwargs.update({'mu': [0., 0.]})
         E_kernel_sf = self(rh_scheme, **kwargs)
         E_reshaped = E_kernel_sf.reshape([-1, rh_scheme.Nsamples])
-        rh_array = np.zeros((len(E_reshaped), rh_scheme.Nsamples))
+        rh_array = np.zeros((len(E_reshaped), 1))
 
         for i, sh_order in enumerate(rh_scheme.shell_sh_orders):
-            rh_array[i, :1] = (
+            rh_array[i, :sh_order // 2 + 1] = (
                 np.dot(
                     rh_scheme.inverse_rh_matrix[0],
                     E_reshaped[i])
@@ -207,29 +204,26 @@ def rotational_harmonics_representation(
             self, acquisition_scheme, **kwargs):
         r""" The rotational harmonics of the model, such that Y_lm = Yl0.
         Axis aligned with z-axis to be used as kernel for spherical
-        convolution.
+        convolution. Returns an array with rotational harmonics for each shell.
 
         Parameters
         ----------
-        bvalue : float,
-            b-value in s/m^2.
-        qvalue : float,
-            diffusion sensitization in 1/m.
-        Delta: float,
-            Delta parameter in seconds.
-        sh_order : int,
-            maximum spherical harmonics order to be used in the approximation.
+        acquisition_scheme : DmipyAcquisitionScheme instance,
+            An acquisition scheme that has been instantiated using dMipy.
+        kwargs: keyword arguments to the model parameter values,
+            Is internally given as **parameter_dictionary.
 
         Returns
         -------
-        rh : array,
-            rotational harmonics of stick model aligned with z-axis.
+        rh_array : array, shape(Nshells, N_rh_coef),
+            Rotational harmonics coefficients for each shell.
         """
         rh_scheme = acquisition_scheme.rotational_harmonics_scheme
         kwargs.update({'mu': [0., 0.]})
         E_kernel_sf = self(rh_scheme, **kwargs)
         E_reshaped = E_kernel_sf.reshape([-1, rh_scheme.Nsamples])
-        rh_array = np.zeros((len(E_reshaped), rh_scheme.Nsamples))
+        rh_array = np.zeros((len(E_reshaped),
+                             rh_scheme.shell_sh_orders.max() // 2 + 1))
 
         for i, sh_order in enumerate(rh_scheme.shell_sh_orders):
             rh_array[i, :sh_order // 2 + 1] = (
@@ -383,29 +377,26 @@ def rotational_harmonics_representation(
             self, acquisition_scheme, **kwargs):
         r""" The rotational harmonics of the model, such that Y_lm = Yl0.
         Axis aligned with z-axis to be used as kernel for spherical
-        convolution.
+        convolution. Returns an array with rotational harmonics for each shell.
 
         Parameters
         ----------
-        bvalue : float,
-            b-value in s/m^2.
-        qvalue : float,
-            diffusion sensitization in 1/m.
-        Delta: float,
-            Delta parameter in seconds.
-        sh_order : int,
-            maximum spherical harmonics order to be used in the approximation.
+        acquisition_scheme : DmipyAcquisitionScheme instance,
+            An acquisition scheme that has been instantiated using dMipy.
+        kwargs: keyword arguments to the model parameter values,
+            Is internally given as **parameter_dictionary.
 
         Returns
         -------
-        rh : array,
-            rotational harmonics of stick model aligned with z-axis.
+        rh_array : array, shape(Nshells, N_rh_coef),
+            Rotational harmonics coefficients for each shell.
         """
         rh_scheme = acquisition_scheme.rotational_harmonics_scheme
         kwargs.update({'mu': [0., 0.]})
         E_kernel_sf = self(rh_scheme, **kwargs)
         E_reshaped = E_kernel_sf.reshape([-1, rh_scheme.Nsamples])
-        rh_array = np.zeros((len(E_reshaped), rh_scheme.Nsamples))
+        rh_array = np.zeros((len(E_reshaped),
+                             rh_scheme.shell_sh_orders.max() // 2 + 1))
 
         for i, sh_order in enumerate(rh_scheme.shell_sh_orders):
             rh_array[i, :sh_order // 2 + 1] = (