Merge pull request #179 from transientskp/Fix_176

Fix 176

Author: HannoSpreeuw

docs/source/cli.rst

@@ -0,0 +1,7 @@
+Command-line interface
+======================
+
+.. argparse::
+   :module: sourcefinder.utility.cli
+   :func: construct_argument_parser
+   :prog: pyse

docs/source/conf.py

@@ -39,6 +39,7 @@
     "numpydoc",
     "autoapi.extension",
     "enum_tools.autoenum",
+    "sphinxarg.ext",
 ]
 
 autodoc_typehints = "both"

docs/source/index.rst

@@ -6,6 +6,7 @@ Welcome to PySE's documentation!
 
    README
    sourceparams
+   cli
 
 
 Indices and tables

pyproject.toml

@@ -35,6 +35,7 @@ docs = [
     "pydata-sphinx-theme",
     "sphinx",
     "sphinx-autoapi",
+    "sphinx-argparse",
 ]
 
 [project.urls]

sourcefinder/deconv.py

@@ -123,6 +123,7 @@ def covariance_matrix(sigma_maj, sigma_min, theta):  # pragma: no cover
     -------
     Sigma : (2,2) ndarray
         Covariance matrix.
+
     """
     c, s = np.cos(theta), np.sin(theta)
     R = np.array([[-s, -c], [c, -s]])
@@ -142,20 +143,26 @@ def covariance_matrix(sigma_maj, sigma_min, theta):  # pragma: no cover
 @njit
 def J_S_from_stddevs_and_pa(sigma_maj, sigma_min, theta):  # pragma: no cover
     """
-    Jacobian d(sxx, syy, sxy)/d(sigma_maj, sigma_min, theta).
+    Jacobian ``d(sxx, syy, sxy) / d(sigma_maj, sigma_min, theta)``.
 
-    Parameters:
+    Parameters
     ----------
-      sigma_maj, sigma_min : float
-          standard-deviations along the elliptical axes
-      theta : float
-          angle in radians, CCW from +Y axis
-
-    Returns:
-      J : (3,3) ndarray
-          rows [dsxx/d*, dsyy/d*, dsxy/d*] and columns corresponding to [
-          sigma_maj, sigma_min, theta].
+    sigma_maj : float
+        Standard deviation along the major axis of the ellipse.
+    sigma_min : float
+        Standard deviation along the minor axis of the ellipse.
+    theta : float
+        Major axis position angle in radians, counter-clockwise from the +Y
+        axis.
+
+    Returns
+    -------
+    J : ndarray of shape (3, 3)
+        Jacobian matrix. Rows correspond to ``[dsxx/d*, dsyy/d*, dsxy/d*]`` and
+        columns to ``[sigma_maj, sigma_min, theta]``.
+
     """
+
     phi = theta + np.pi / 2.0  # convert to math convention (CCW from +x)
 
     c = np.cos(phi)
@@ -205,13 +212,14 @@ def cov_p_to_cov_S(C_p, sigma_maj, sigma_min, theta):  # pragma: no cover
 
     Parameters
     ----------
-      C_p : (3,3) ndarray  (covariance in order [sigma_maj, sigma_min, theta])
-      sigma_maj, sigma_min: float
-      theta: float (radians)
+    C_p : (3,3) ndarray  (covariance in order [sigma_maj, sigma_min, theta])
+    sigma_maj, sigma_min: float
+    theta: float (radians)
 
     Returns
     -------
-      C_S : (3,3) ndarray (covariance on [sxx, syy, sxy])
+    C_S : (3,3) ndarray (covariance on [sxx, syy, sxy])
+
     """
     J = J_S_from_stddevs_and_pa(sigma_maj, sigma_min, theta)
     C_S = np.empty((3, 3))
@@ -243,15 +251,19 @@ def sigma_to_stddevs_pa_and_jacobian(sxx, syy, sxy):  # pragma: no cover
     sxx, syy, sxy : float
         Covariance matrix elements: if sigma_maj is major axis stddev,
         sigma_min is minor axis stddev, and theta the position angle (CCW
-        from +Y), then
+        from +Y), then::
+
             S = [[sxx, sxy],
                  [sxy, syy]] = R @ [[sigma_maj^2, 0],
                                     [0, sigma_min^2]] @ R.T
-        where R = [[-sin(theta), -cos(theta)],
-                   [ cos(theta), -sin(theta)]]
-        i.e. sxx = sigma_maj^2 sin^2(theta) + sigma_min^2 cos^2(theta)
-             syy = sigma_maj^2 cos^2(theta) + sigma_min^2 sin^2(theta)
-             sxy = -(sigma_maj^2 - sigma_min^2) sin(theta) cos(theta)
+
+            where R = [[-sin(theta), -cos(theta)],
+                       [ cos(theta), -sin(theta)]]
+
+            i.e. sxx = sigma_maj^2 sin^2(theta) + sigma_min^2 cos^2(theta)
+                 syy = sigma_maj^2 cos^2(theta) + sigma_min^2 sin^2(theta)
+                 sxy = -(sigma_maj^2 - sigma_min^2) sin(theta) cos(theta)
+
     Returns
     -------
     sigma_maj : float
@@ -264,6 +276,7 @@ def sigma_to_stddevs_pa_and_jacobian(sxx, syy, sxy):  # pragma: no cover
         Jacobian d[a,b,phi]/d[sxx,syy,sxy]
     ok : bool
         True if conversion succeeded (Sigma positive definite), else False.
+
     """
     # helpers
     m = 0.5 * (sxx + syy)
@@ -363,6 +376,7 @@ def cov_S_to_cov_r(S_dec, C_S_dec):  # pragma: no cover
         Covariance matrix on (a_dec, b_dec, phi_dec)
     ok : bool
         True if conversion succeeded (Sigma_dec positive definite), else False.
+
     """
     sxx, syy, sxy = S_dec
     a_dec, b_dec, phi_dec, J, ok = sigma_to_stddevs_pa_and_jacobian(

sourcefinder/image.py

@@ -825,8 +825,8 @@ def fit_fixed_positions(
             List of identifiers. If not None, must match the length and order of
             the requested fits.
 
-        Note
-        ----
+        Notes
+        -----
         boxsize is in pixel coordinates, not in sky coordinates.
 
         Returns

sourcefinder/testutil/convolve.py

@@ -11,7 +11,7 @@ def gaussian_from_Sigma_matrix(x, y, I0, mu, Sigma):
     """
     Evaluate a 2D anisotropic Gaussian defined by its covariance matrix.
 
-    The Gaussian is given by
+    The Gaussian is given by::
 
         G(x, y) = I₀ * exp[-½ (r - μ)ᵀ Σ⁻¹ (r - μ)],
 
@@ -59,6 +59,7 @@ def gaussian_from_Sigma_matrix(x, y, I0, mu, Sigma):
     >>> G = gaussian_from_Sigma_matrix(x, y, I0=1.0, mu=mu, Sigma=Sigma)
     >>> G.shape
     (101, 101)
+
     """
     pos = np.stack((x - mu[0], y - mu[1]), axis=0)
     invSigma = np.linalg.inv(Sigma)
@@ -77,11 +78,13 @@ def convolve_gaussians(I1, mu1, Sigma1, I2, mu2, Sigma2):
     """
     Analytically convolve two 2D anisotropic Gaussian profiles.
 
-    The convolution of two Gaussians
-    G₁(r) = I₁ exp[-½ (r − μ₁)ᵀ Σ₁⁻¹ (r − μ₁)]
-    and
-    G₂(r) = I₂ exp[-½ (r − μ₂)ᵀ Σ₂⁻¹ (r − μ₂)]
-    yields another Gaussian with parameters:
+    The convolution of two Gaussians::
+
+        G₁(r) = I₁ exp[-½ (r − μ₁)ᵀ Σ₁⁻¹ (r − μ₁)]
+        and
+        G₂(r) = I₂ exp[-½ (r − μ₂)ᵀ Σ₂⁻¹ (r − μ₂)]
+
+    yields another Gaussian with parameters::
 
         Σ_H = Σ₁ + Σ₂
         μ_H = μ₁ + μ₂
@@ -125,8 +128,9 @@ def convolve_gaussians(I1, mu1, Sigma1, I2, mu2, Sigma2):
     >>> I2, mu2, Sigma2 = 1.0, np.array([0.3, -0.2]), np.diag([1.5, 0.5])
     >>> I_H, mu_H, Sigma_H = convolve_gaussians(I1, mu1, Sigma1, I2, mu2, Sigma2)
     >>> I_H, mu_H, Sigma_H
-    (0.707..., array([ 0.3, -0.2]), array([[3.5, 0. ],
-                                           [0. , 1.5]]))
+    (0.707..., array([ 0.3, -0.2]), array([[3.5, 0.],
+                                           [0., 1.5]]))
+
     """
     Sigma_H = Sigma1 + Sigma2
     mu_H = mu1 + mu2
@@ -148,8 +152,7 @@ def convolve_gaussians(I1, mu1, Sigma1, I2, mu2, Sigma2):
 def params_from_sigma(Sigma):
     """
     From covariance matrix Sigma (2x2) return (sigma_maj, sigma_min,
-    theta) with
-    sigma_maj>=sigma_min>=0.
+    theta) with sigma_maj>=sigma_min>=0.
 
     Parameters
     ----------
@@ -158,15 +161,19 @@ def params_from_sigma(Sigma):
         ellipse. Must be symmetric.
         Covariance matrix elements: if sigma_maj is major axis stddev,
         sigma_min is minor axis stddev, and theta the position angle (CCW
-        from +Y), then
+        from +Y), then::
+
             S = [[sxx, sxy],
                  [sxy, syy]] = R @ [[sigma_maj^2, 0],
                                     [0, sigma_min^2]] @ R.T
-        where R = [[-sin(theta), -cos(theta)],
-                   [ cos(theta), -sin(theta)]]
-        i.e. sxx = sigma_maj^2 sin^2(theta) + sigma_min^2 cos^2(theta)
-             syy = sigma_maj^2 cos^2(theta) + sigma_min^2 sin^2(theta)
-             sxy = -(sigma_maj^2 - sigma_min^2) sin(theta) cos(theta)
+
+            where R = [[-sin(theta), -cos(theta)],
+                       [ cos(theta), -sin(theta)]]
+
+            i.e. sxx = sigma_maj^2 sin^2(theta) + sigma_min^2 cos^2(theta)
+                 syy = sigma_maj^2 cos^2(theta) + sigma_min^2 sin^2(theta)
+                 sxy = -(sigma_maj^2 - sigma_min^2) sin(theta) cos(theta)
+
     Returns
     -------
     sigma_maj : float
@@ -176,6 +183,7 @@ def params_from_sigma(Sigma):
     theta : float
         Position angle of the major axis in radians, in [0, pi).
         Measured from the positive y-axis toward the negative-axis.
+
     Notes
     -----
     - The covariance matrix Sigma is related to the ellipse parameters
@@ -184,6 +192,7 @@ def params_from_sigma(Sigma):
       eigenvalues of Sigma.
     - The position angle theta is derived from the eigenvector
       corresponding to the largest eigenvalue.
+
     """
     # Symmetrize for numerical safety
     S = 0.5 * (Sigma + Sigma.T)

sourcefinder/utility/cli.py

@@ -160,15 +160,19 @@ def construct_argument_parser():
         "--structuring-element",
         type=ast.literal_eval,
         help="""
-        Structuring element for morphological operations, provided as a Python-style nested list (e.g. '[[1,1,1],[1,1,1],[1,1,1]]').
-        This is used for defining the connectivity in source detection.
+        Structuring element for morphological operations, provided as a 
+        Python-style nested list, e.g. '[[1,1,1], [1,1,1], [1,1,1]]' for 
+        8-connectivity and '[[0,1,0], [1,1,1], [0,1,0]]' for 4-connectivity.
+        This is used for defining the connectivity in connected-component 
+        labelling.
         """,
     )
 
     image_group.add_argument(
         "--vectorized",
         action="store_true",
-        help="Use vectorized operations where applicable.",
+        help="Measure sources vectorized, this implies using 'tweaked "
+        "moments' instead of Gaussian fits.",
     )
 
     image_group.add_argument(

sourcefinder/utils.py

@@ -722,8 +722,8 @@ def complement_gaussian_args(initial_params, fixed_params, fit_params):
         either a fixed value or an initial value from `initial_params`.
         len(gaussian_args) == 6.
 
-    Example
-    -------
+    Examples
+    --------
     >>> initial_parms = np.array([1.0, 4.0, 5.0, 6.0])
     >>> fixed_parms = {'center_x': 2.5, 'center_y': 3.5}
     >>> fit_parms = ('peak', 'center_x', 'center_y', 'semi-major axis',