bit of doctring and fix on test_center

package/lib/utils.py

@@ -4,6 +4,14 @@ import numpy as np
 def rot2D(ang):
     """
     Return the 2D rotation matrix of given angle in degrees
+    ----------
+    Inputs:
+    ang : float
+        Angle in degrees
+    ----------
+    Returns:
+    rot_mat : numpy.ndarray
+        2D matrix of shape (2,2) to perform vector rotation at angle "ang".
     """
     alpha = np.pi * ang / 180
     return np.array([[np.cos(alpha), np.sin(alpha)], [-np.sin(alpha), np.cos(alpha)]])
@@ -13,6 +21,14 @@ def princ_angle(ang):
     """
     Return the principal angle in the 0° to 180° quadrant as PA is always
     defined at p/m 180°.
+    ----------
+    Inputs:
+    ang : float, numpy.ndarray
+        Angle in degrees. Can be an array of angles.
+    ----------
+    Returns:
+    princ_ang : float, numpy.ndarray
+        Principal angle in the 0°-180° quadrant in the same shape as input.
     """
     if not isinstance(ang, np.ndarray):
         A = np.array([ang])
@@ -32,6 +48,21 @@ def PCconf(QN, UN, QN_ERR, UN_ERR):
     """
     Compute the confidence level for 2 parameters polarisation degree and
     polarisation angle from the PCUBE analysis.
+    ----------
+    Inputs:
+    QN : float, numpy.ndarray
+        Normalized Q Stokes flux.
+    UN : float, numpy.ndarray
+        Normalized U Stokes flux.
+    QN_ERR : float, numpy.ndarray
+        Normalized error on Q Stokes flux.
+    UN_ERR : float, numpy.ndarray
+        Normalized error on U Stokes flux.
+    ----------
+    Returns:
+    conf : numpy.ndarray
+        2D matrix of same shape as input containing the confidence on the polarization
+        computation between 0 and 1 for 2 parameters of interest (Q and U Stokes fluxes).
     """
     mask = np.logical_and(QN_ERR > 0.0, UN_ERR > 0.0)
     conf = np.full(QN.shape, -1.0)
@@ -43,6 +74,19 @@ def PCconf(QN, UN, QN_ERR, UN_ERR):
 def CenterConf(mask, PA, sPA):
     """
     Compute the confidence map for the position of the center of emission.
+    ----------
+    Inputs:
+    mask : bool, numpy.ndarray
+        Mask of the polarization vectors from which the center of emission should be drawn.
+    PA : float, numpy.ndarray
+        2D matrix containing the computed polarization angle.
+    sPA : float, numpy.ndarray
+        2D matrix containing the total uncertainties on the polarization angle.
+    ----------
+    Returns:
+    conf : numpy.ndarray
+        2D matrix of same shape as input containing the confidence on the polarization
+        computation between 0 and 1 for 2 parameters of interest (Q and U Stokes fluxes).
     """
     chi2 = np.full(PA.shape, np.nan)
     conf = np.full(PA.shape, -1.0)
@@ -64,17 +108,36 @@ def CenterConf(mask, PA, sPA):
     from scipy.special import gammainc
 
     conf[np.isfinite(PA)] = 1.0 - gammainc(0.5, 0.5 * chi2[np.isfinite(PA)])
-    result = minimize(chisq, np.array(PA.shape) / 2.0, bounds=[(0, PA.shape[1]), (0.0, PA.shape[0])])
+    c0 = np.unravel_index(np.argmax(conf), conf.shape)[::-1]
+    result = minimize(chisq, c0, bounds=[(0, PA.shape[1]), (0.0, PA.shape[0])])
     if result.success:
         print("Center of emission found")
     else:
-        print("Center of emission not found")
+        print("Center of emission not found", result)
     return conf, result.x
 
 
 def sci_not(v, err, rnd=1, out=str):
     """
-    Return the scientifque error notation as a string.
+    Return the scientific error notation as a string.
+    ----------
+    Inputs:
+    v : float
+        Value to be transformed into scientific notation.
+    err : float
+        Error on the value to be transformed into scientific notation.
+    rnd : int
+        Number of significant numbers for the scientific notation.
+        Default to 1.
+    out : str or other
+        Format in which the notation should be returned. "str" means the notation
+        is returned as a single string, "other" means it is returned as a list of "str".
+        Default to str.
+    ----------
+    Returns:
+    conf : numpy.ndarray
+        2D matrix of same shape as input containing the confidence on the polarization
+        computation between 0 and 1 for 2 parameters of interest (Q and U Stokes fluxes).
     """
     power = -int(("%E" % v)[-3:]) + 1
     output = [r"({0}".format(round(v * 10**power, rnd)), round(v * 10**power, rnd)]
@@ -95,6 +158,16 @@ def wcs_PA(PC21, PC22):
     """
     Return the position angle in degrees to the North direction of a wcs
     from the values of coefficient of its transformation matrix.
+    ----------
+    Inputs:
+    PC21 : float
+        Value of the WCS matric PC[1,0]
+    PC22 : float
+        Value of the WCS matric PC[1,1]
+    ----------
+    Returns:
+    orient : float
+        Angle in degrees between the North direction and the Up direction of the WCS.
     """
     if (abs(PC21) > abs(PC22)) and (PC21 >= 0):
         orient = -np.arccos(PC22) * 180.0 / np.pi