rename auxiliary functions and improve docstring

quaternions/quaternion.py

@@ -3,7 +3,7 @@
 from collections import Iterable
 import numbers
 
-from quaternions.utils import (covariance_matrix_from_angles, sigma_lerner, orthogonal_matrix)
+from quaternions.utils import (covariance_matrix_from_angles, sigma_lerner, xi_matrix)
 from quaternions.general_quaternion import GeneralQuaternion, QuaternionError, DEFAULT_TOLERANCE, exp
 
 
@@ -226,6 +226,7 @@ def from_qmethod(source, target, probabilities=None):
         K[1:4, 0] = [i, j, k]
         K[1:4, 1:4] = S - sigma * np.identity(3)
         return Quaternion._first_eigenvector(K)
+
     @staticmethod
     def average_and_std_naive(*quaternions, weights=None):
         """
@@ -272,11 +273,11 @@ def average_and_covariance(*quaternions, R=np.eye(3)):
         R_inverse = np.linalg.inv(R)
         orthogonal_matrix_sum = np.zeros((4, 4))
         for q in quaternions:
-            orthogonal_matrix_sum += orthogonal_matrix(q).dot(
-                R_inverse.dot(orthogonal_matrix(q).T))
+            orthogonal_matrix_sum += xi_matrix(q).dot(
+                R_inverse.dot(xi_matrix(q).T))
 
-        cov_dev_matrix = np.linalg.inv(orthogonal_matrix(q_average).T.dot(
-            orthogonal_matrix_sum.dot(orthogonal_matrix(q_average))))
+        cov_dev_matrix = np.linalg.inv(xi_matrix(q_average).T.dot(
+            orthogonal_matrix_sum.dot(xi_matrix(q_average))))
 
         return q_average, cov_dev_matrix
 

quaternions/utils.py

@@ -19,20 +19,20 @@ def sigma_lerner(covariance_matrix):
     return 1.87 * np.sqrt(max(values))
 
 
-def rotation_matrix(quaternion):
+def cross_product_matrix(quaternion):
     """
-    Computes rotation matrix form quaternion.
-    Function related to average_and_std_theorical
+    Auxiliary matrix for average_and_std_theorical calculations.
+    equation (7) from Averaging Quaternions, by Markley, Cheng, Crassidis, Oschman
     """
     return np.array([[0, -quaternion.qk, quaternion.qj],
                      [quaternion.qk, 0, -quaternion.qi],
                      [-quaternion.qj, quaternion.qi, 0]])
 
 
-def orthogonal_matrix(quaternion):
+def xi_matrix(quaternion):
     """
-    Computes orthogonal matrix form quaternion.
-    Function related to average_and_std_theorical
+    Auxiliary matrix for average_and_std_theorical calculations.
+    equation (15) from Averaging Quaternions, by Markley, Cheng, Crassidis, Oschman
     """
-    return np.vstack((quaternion.qr * np.eye(3) + rotation_matrix(quaternion),
+    return np.vstack((quaternion.qr * np.eye(3) + cross_product_matrix(quaternion),
                       -np.array([quaternion.qi, quaternion.qj, quaternion.qk])))