sourcefinder.deconv
===================

.. py:module:: sourcefinder.deconv

.. autoapi-nested-parse::

   Gaussian deconvolution.

   ..
       !! processed by numpydoc !!


Functions
---------

.. autoapisummary::

   sourcefinder.deconv.J_S_from_stddevs_and_pa
   sourcefinder.deconv.cov_S_to_cov_r
   sourcefinder.deconv.cov_p_to_cov_S
   sourcefinder.deconv.covariance_matrix
   sourcefinder.deconv.deconv
   sourcefinder.deconv.sigma_to_stddevs_pa_and_jacobian


Module Contents
---------------

.. py:function:: J_S_from_stddevs_and_pa(sigma_maj, sigma_min, theta)

   
   Jacobian ``d(sxx, syy, sxy) / d(sigma_maj, sigma_min, theta)``.


   :Parameters:

       **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]``.











   ..
       !! processed by numpydoc !!

.. py:function:: cov_S_to_cov_r(S_dec, C_S_dec)

   
   Convert covariance on S = [sxx, syy, sxy] to covariance on
   r = [a_dec, b_dec, phi_dec] using analytic Jacobian.


   :Parameters:

       **S_dec** : array_like, shape (3,)
           [sxx, syy, sxy] of the deconvolved covariance matrix (pixels^2)

       **C_S_dec** : ndarray, shape (3,3)
           Covariance matrix of S_dec (units pixels^4)



   :Returns:

       **r** : ndarray shape (3,)
           (a_dec, b_dec, phi_dec) where phi_dec is radians (CCW from +x)

       **C_r** : ndarray shape (3,3)
           Covariance matrix on (a_dec, b_dec, phi_dec)

       **ok** : bool
           True if conversion succeeded (Sigma_dec positive definite), else False.











   ..
       !! processed by numpydoc !!

.. py:function:: cov_p_to_cov_S(C_p, sigma_maj, sigma_min, theta)

   
   Propagate covariance C_p (3x3) on parameters p=(sigma_maj, sigma_min,
   theta)
   to covariance on S = (sxx, syy, sxy) using analytic Jacobian.


   :Parameters:

       **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])
           ..











   ..
       !! processed by numpydoc !!

.. py:function:: covariance_matrix(sigma_maj, sigma_min, theta)

   
   Build covariance matrix for an anisotropic Gaussian.


   :Parameters:

       **sigma_maj, sigma_min** : float
           Standard deviations along major and minor axes (same units as x,
           y grid).

       **theta** : float
           Position angle in radians, measured CCW from +Y toward -X (north
           through east).



   :Returns:

       **Sigma** : (2,2) ndarray
           Covariance matrix.











   ..
       !! processed by numpydoc !!

.. py:function:: deconv(fmaj, fmin, fpa, cmaj, cmin, cpa)

   
   Deconvolve a Gaussian "beam" from a Gaussian component.

   When we fit an elliptical Gaussian to a point in our image, we are
   actually fitting to a convolution of the physical shape of the source with
   the beam pattern of our instrument. This results in the fmaj/fmin/fpa
   arguments to this function.

   Since the shape of the (clean) beam (arguments cmaj/cmin/cpa) is known, we
   can deconvolve it from the fitted parameters to get the "real" underlying
   physical source shape, which is what this function returns.

   :Parameters:

       **fmaj** : float
           Fitted major axis (pixels).

       **fmin** : float
           Fitted minor axis (pixels).

       **fpa** : float
           Fitted position angle of the major axis (degrees).

       **cmaj** : float
           Clean beam major axis (pixels).

       **cmin** : float
           Clean beam minor axis (pixels).

       **cpa** : float
           Clean beam position angle of the major axis (degrees).



   :Returns:

       **rmaj** : float
           real major axis in pixels

       **rmin** : float
           real minor axis in pixels

       **rpa** : float
           real position angle of the major axis in degress

       **ierr** : int
           number of components which failed to deconvolve








   .. rubric:: Notes

   Instead of fmaj, fmin, cmaj and cmin all in pixels, one could use any
   arbitrary unit of sky angular distance, such as arcseconds or radians.
   The first two elements of the returned tuple would then have that same
   unit, while the third element (the position angle) would still be in
   degrees.



   ..
       !! processed by numpydoc !!

.. py:function:: sigma_to_stddevs_pa_and_jacobian(sxx, syy, sxy)

   
   From covariance elements sxx, syy, sxy return (sigma_maj, sigma_min, theta,
   J, ok)
   where sigma_maj>=sigma_min are stddevs along the elliptical axes and
   theta is angle (radians) CCW from +y.
   J is the 3x3 Jacobian d[a,b,theta]/d[sxx,syy,sxy] (rows outputs,
   cols inputs).


   :Parameters:

       **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::
           
               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)



   :Returns:

       **sigma_maj** : float
           Major axis standard deviation (pixels)

       **sigma_min** : float
           Minor axis standard deviation (pixels)

       **theta** : float
           Position angle in radians, CCW from +Y axis

       **J** : ndarray, shape (3,3)
           Jacobian d[a,b,phi]/d[sxx,syy,sxy]

       **ok** : bool
           True if conversion succeeded (Sigma positive definite), else False.











   ..
       !! processed by numpydoc !!