Fixing docstyle

pierfra-rocci · Nov 20, 2020 · daf2270 · daf2270
1 parent b2cd200
commit daf2270
Show file tree

Hide file tree

Showing 5 changed files with 168 additions and 39 deletions.
diff --git a/README.md b/README.md
@@ -1,12 +1,12 @@
 # Proper image treatments
 
+[![QuatroPe](https://img.shields.io/badge/QuatroPe-Applications-1c5896)](https://quatrope.github.io/)
 [![Build Status](https://travis-ci.com/quatrope/ProperImage.svg?branch=master)](https://travis-ci.com/quatrope/ProperImage)
 [![codecov](https://codecov.io/gh/quatrope/ProperImage/branch/master/graph/badge.svg)](https://codecov.io/gh/quatrope/ProperImage)
 [![Documentation Status](https://readthedocs.org/projects/properimage/badge/?version=latest)](http://properimage.readthedocs.io/en/latest/?badge=latest)
 [![License](https://img.shields.io/pypi/l/properimage?color=blue)](https://tldrlegal.com/license/bsd-3-clause-license-(revised))
 [![Python 3.8](https://img.shields.io/badge/python-3.8-blue.svg)](https://badge.fury.io/py/properimage)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
-[![QuatroPe](https://img.shields.io/badge/QuatroPe-Applications-1c5896)](https://quatrope.github.io/)
 
 This code is inspired on [Zackay & Ofek 2017](http://arxiv.org/abs/1512.06872)  papers *How to coadd images?* (see References below).
 

diff --git a/properimage/operations.py b/properimage/operations.py
@@ -64,8 +64,7 @@ def subtract(
     fitted_psf=True,
 ):
     """
-    Function that takes a list of SingleImage instances
-    and performs a stacking using properimage R estimator
+    Subtract a pair of SingleImage instances.
 
     Parameters:
     -----------
@@ -436,6 +435,10 @@ def cost(vec):
 
 
 def diff(*args, **kwargs):
+    """Subtract images.
+
+    Wrapper of `subtract`.
+    """
     warnings.warn(
         "This is being deprecated in favour of `subtract`", DeprecationWarning
     )
@@ -444,6 +447,7 @@ def diff(*args, **kwargs):
 
 class StackCombinator(Process):
     """Combination engine.
+
     An engine for image combination in parallel, using multiprocessing.Process
     class.
     Uses an ensemble of images and a queue to calculate the propercoadd of
@@ -511,6 +515,7 @@ def __init__(
         *args,
         **kwargs,
     ):
+        """Create instance of combination engine."""
         super(StackCombinator, self).__init__(*args, **kwargs)
         self.list_to_combine = img_list
         self.queue = queue
@@ -519,6 +524,7 @@ def __init__(
         # self.zps = ensemble.transparencies
 
     def run(self):
+        """Run workers of combination engine."""
         S_hat = np.zeros(self.global_shape).astype(np.complex128)
         psf_hat_sum = np.zeros(self.global_shape).astype(np.complex128)
         mix_mask = self.list_to_combine[0].data.mask
@@ -539,9 +545,27 @@ def run(self):
 
 
 def coadd(si_list, align=True, inf_loss=0.2, n_procs=2):
-    """Function that takes a list of SingleImage instances
-    and performs a stacking using properimage R estimator
+    """Coadd a list of SingleImage instances using R estimator.
+
+    Parameters:
+    -----------
+    align : bool
+        Whether to align the images before subtracting, default to False
+    inf_loss : float
+        Value of information loss in PSF estimation, lower limit is 0,
+        upper is 1. Only valid if fitted_psf=False. Default is 0.25
+    n_procs : int
+        Number of processes to use. If value is one then no multiprocessing
+        is being used. Default 2.
 
+    Returns:
+    --------
+    R : np.ndarray(n, m) of float
+        Coadd image, Zackay's decorrelated R.
+    P : np.ndarray(n, m) of float
+        Coadd image PSF. This is a full PSF image, with a size equal to R
+    mix_mask : np.ndarray of bool
+        Mask of bad pixels for subtracion image, with True marking bad pixels
     """
     logger = logging.getLogger()
     for i_img, animg in enumerate(si_list):
@@ -629,6 +653,10 @@ def coadd(si_list, align=True, inf_loss=0.2, n_procs=2):
 
 
 def stack_R(*args, **kwargs):
+    """Subtract images.
+
+    Wrapper of `subtract`.
+    """
     warnings.warn(
         "This is being deprecated in favour of `coadd`", DeprecationWarning
     )

diff --git a/properimage/plot.py b/properimage/plot.py
@@ -51,15 +51,17 @@
 
 
 class NoDataToPlot(ValueError):
+    """Exception for empty data."""
+
     pass
 
 
 # =============================================================================
 # FUNCTIONS
 # =============================================================================
 
-
 def primes(n):
+    """Get maximum prime number factor."""
     divisors = [d for d in range(2, n // 2 + 1) if n % d == 0]
     prims = [
         d for d in divisors if all(d % od != 0 for od in divisors if od != d)
@@ -73,6 +75,21 @@ def primes(n):
 
 
 def plot_S(S, path=None, nbook=False):
+    """Plot an S-type image subtraction.
+
+    Parameters
+    ----------
+    S : array_like
+        Image to plot
+    path : str, optional
+        Path to store the plot
+    nbook : bool, optional
+        Whether we are plotting in a notebook
+
+    Returns
+    -------
+    ax : matplotlib axes
+    """
     if isinstance(S, np.ma.masked_array):
         S = S.filled()
     mean, med, std = sigma_clipped_stats(S)
@@ -91,10 +108,25 @@ def plot_S(S, path=None, nbook=False):
         plt.show()
     if not nbook:
         plt.close()
-    return
+    return plt.gca()
 
 
 def plot_R(R, path=None, nbook=False):
+    """Plot an D-type image subtraction.
+
+    Parameters
+    ----------
+    R : array_like
+        Image to plot
+    path : str, optional
+        Path to store the plot
+    nbook : bool, optional
+        Whether we are plotting in a notebook
+
+    Returns
+    -------
+    ax : matplotlib axes
+    """
     if isinstance(R[0, 0], np.complex):
         R = R.real
     if isinstance(R, np.ma.masked_array):
@@ -118,12 +150,14 @@ def plot_R(R, path=None, nbook=False):
 
 @attr.s(frozen=True, repr=False, eq=False, order=False)
 class Plot:
+    """Plotting plug-in object for SingleImage class."""
 
     DEFAULT_PLOT = "imshow"
 
     si = attr.ib()
 
     def __call__(self, plot=None, **kwargs):
+        """Execute plot."""
         if plot is not None and (
             plot.startswith("_") or not hasattr(self, plot)
         ):
@@ -134,6 +168,7 @@ def __call__(self, plot=None, **kwargs):
         return method(**kwargs)
 
     def imshow(self, ax=None, **kwargs):
+        """Plot 2d image."""
         if ax is None:
             fig = plt.gcf()
             ax = plt.gca()
@@ -156,6 +191,7 @@ def autopsf(
         iso_kw=None,
         **kwargs,
     ):
+        """Plot autopsf basis components."""
         _, psf_basis = self.si.get_variable_psf(inf_loss=inf_loss, shape=shape)
 
         # here we plot
@@ -217,6 +253,7 @@ def autopsf(
     def autopsf_coef(
         self, axs=None, inf_loss=None, shape=None, cmap_kw=None, **kwargs
     ):
+        """Plot autopsf basis component coefficients."""
         a_fields, _ = self.si.get_variable_psf(inf_loss=inf_loss, shape=shape)
         if a_fields == [None]:
             raise NoDataToPlot("No coeficients for this PSF")