Fixed some docstring errors. Started proper work on RTD webpage.

lewisfish · Apr 15, 2020 · eb1824d · eb1824d
1 parent 3d7f211
commit eb1824d
Show file tree

Hide file tree

Showing 13 changed files with 118 additions and 34 deletions.
diff --git a/docs/casgm.rst b/docs/casgm.rst
@@ -0,0 +1,3 @@
+*****
+CASgm
+*****
diff --git a/docs/diagnostic.rst b/docs/diagnostic.rst
@@ -0,0 +1,3 @@
+***********
+Diagnostics
+***********
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -0,0 +1,3 @@
+***************
+Getting Started
+***************
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,22 +3,38 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to pawlikMorph-LSST's documentation!
+PawlikMorph-LSST's documentation!
 ============================================
 
-.. automodule:: pawlikMorphLSST.main
+PawlikMorph-LSST is a python package for calculating various non-parametric morphological measures of galaxies.
+The code in this package is based upon/translation of `pawlikMorph <https://github.com/SEDMORPH/PawlikMorph>`_ in IDL.
+
+.. automodule pawlikMorphLSST.main
     :members:
     :undoc-members:
 
+
+Getting Started
+===============
+
+.. toctree::
+    :maxdepth: 1
+
+    install.rst
+    overview.rst
+    getting_started.rst
+
+User Documentation
+==================
+
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+    :maxdepth: 1
 
+    casgm.rst
+    diagnostic.rst
 
 
-Indices and tables
+Modules (API) 
 ==================
 
-* :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
diff --git a/docs/install.rst b/docs/install.rst
@@ -0,0 +1,45 @@
+************
+Installation
+************
+
+Requirements
+============
+
+PawlikMorph-LSST depends on several other packages for some features:
+
+* Python 3.7+
+* Numpy 1.15.4+
+* Numba 0.38.1+
+* Astropy 3.0.3+
+* Scikit-image 0.14.0+
+* Pandas 0.25.3+
+* photutils 0.7.1+
+* scipy 1.3.2+
+* parsl 0.9.0+
+
+If diagnostic.py is used:
+
+* matplotlib
+
+Installing the latest version
+=============================
+
+First clone the GitHub repository:
+
+* Via commandline::
+
+    git clone https://github.com/lewisfish/PawlikMorph-LSST.git
+
+* Or via webpage:
+
+    * https://github.com/lewisfish/PawlikMorph-LSST/archive/master.zip
+
+Then install the dependancies:
+
+* Via conda::
+
+    conda env create -f environment.yml
+
+* Or via pip::
+
+    pip install --user --requirement requirements.txt
diff --git a/docs/overview.rst b/docs/overview.rst
@@ -0,0 +1,3 @@
+********
+Overview
+********
diff --git a/pawlikMorphLSST/apertures.py b/pawlikMorphLSST/apertures.py
@@ -41,18 +41,25 @@ def makeaperpixmaps(npix: int, folderpath=None) -> None:
 
 @nb.njit
 def aperpixmap(npix: int, rad: float,  nsubpix: int, frac: float) -> np.ndarray:
-    '''Calculates the aperture binary mask through pixel sampling knowing
-       aperture radius and number of subpixels. Near direct translation of
-       IDL code.
+    '''Calculate aperture binary mask.
+
+    Calculates the aperture binary mask through pixel sampling knowing
+    the aperture radius and number of subpixels.
+
+   Near direct translation of IDL code.
 
     Parameters
     ----------
+
     npix : int
         Width of aperture image.
+
     rad : float
         Radius of the aperture.
+
     nsubpix : int
         Number of subpixels
+
     frac : float
         Fraction of something... Maybe due to Petrosian magnitude?
 
@@ -157,7 +164,8 @@ def distarr(npixx: int, npixy: int, cenpix: np.ndarray) -> np.ndarray:
 @nb.njit(nb.float64[:, :](nb.int64, nb.int64, nb.int64[:]))
 def subdistarr(npix: int, nsubpix: int, cenpix: List[int]) -> np.ndarray:
     '''Writes the aperture binary masks out after calculation.
-       Near direct translation of IDL code.
+
+    Near direct translation of IDL code.
 
     Parameters
     ----------

diff --git a/pawlikMorphLSST/asymmetry.py b/pawlikMorphLSST/asymmetry.py
@@ -11,8 +11,8 @@
 
 def minapix(image: np.ndarray, mask: np.ndarray, apermask: np.ndarray,
             starMask=None) -> List[int]:
-    """Function that finds the minimum asymmetry central pixel within the
-       objects pixels of a given image.
+    """Find the pixel that minimises the asymmetry parameter, A
+
        Selects a range of candidate centroids within the brightest region that
        compromises of 20% of the total flux within object.
        Then measures the asymmetry of the image under rotation around that
@@ -95,8 +95,9 @@ def minapix(image: np.ndarray, mask: np.ndarray, apermask: np.ndarray,
 def calcA(img: np.ndarray, pixmap: np.ndarray, apermask: np.ndarray,
           centroid: List[int], angle: float, starMask=None,
           noisecorrect=False) -> List[float]:
-    """Function to calculate A, the asymmetry parameter. Near direct
-       translation of IDL code.
+    """Function to calculate A, the asymmetry parameter.
+
+    Near direct translation of IDL code.
 
     Parameters
     ----------

diff --git a/pawlikMorphLSST/casgm.py b/pawlikMorphLSST/casgm.py
@@ -118,7 +118,7 @@ def _fractionTotalFLuxCircle(radius: float, image: np.ndarray,
 
 def calcR20_R80(image: np.ndarray, centroid: List[float],
                 radius: float) -> Tuple[float, float]:
-    r'''Calculation of :math: r_{20}, and :math: r_{80}
+    r'''Calculation of :math:`r_{20}`, and :math:`r_{80}`
 
 
     Parameters
@@ -178,9 +178,9 @@ def gini(image: np.ndarray, mask: np.ndarray) -> float:
 
     .. math:: g = \frac{1}{2 \bar{X} n(n-1)} \sum (2i - n - 1) \left|X_i\right|
 
-    Where :math: \bar{X} is the mean over all intensities
+    Where :math:`\bar{X}` is the mean over all intensities
     n is the total number of pixels
-    :math:X_i are the pixel intensities in increasing order
+    :math:`X_i` are the pixel intensities in increasing order
 
     see Lotz et al. 2004 https://doi.org/10.1086/421849
 
@@ -269,8 +269,8 @@ def smoothness(image: np.ndarray, mask: np.ndarray, centroid: List[float],
     .. math:: S = \frac{\sum \left|I - I_s\right| - B_s} {\sum \left|I\right|}
 
     Where I is the image
-    :math: I_s is the smoothed image
-    :math: B_s is the background smoothness
+    :math:`I_s` is the smoothed image
+    :math:`B_s` is the background smoothness
 
     see Lotz et al. 2004 https://doi.org/10.1086/421849
 

diff --git a/pawlikMorphLSST/diagnostic.py b/pawlikMorphLSST/diagnostic.py
@@ -270,7 +270,9 @@ def make_twotwo(ax, img, modelImage, listofStarstoPlot, result):
 
 
 def make_figure(result, folder, save=False, show=False):
-    '''Function plots results from image analysis. Plots two or four images.
+    '''Function plots results from image analysis.
+
+        Plots two or four images.
        Top row: original image  and object map with stars overplotted if any.
        bottom row: Sersic fit and residual with stars overplotted if any.
 

diff --git a/pawlikMorphLSST/helpers.py b/pawlikMorphLSST/helpers.py
@@ -105,8 +105,7 @@ def getFiles(imgSource, file=None, folder=None):
 
 
 def getLocation(file=None, folder=None):
-    '''Function to determine the outfolder, and current folder of file/set
-       of files provided via command line
+    '''Determines the output folder and current folder of files.
 
     Parameters
     ----------

diff --git a/pawlikMorphLSST/imageutils.py b/pawlikMorphLSST/imageutils.py
@@ -40,8 +40,7 @@ def _inBbox(extent: List[float], point: List[float]) -> bool:
 
 
 def maskstarsSEG(image: np.ndarray) -> np.ndarray:
-    '''Function that cleans image of external sources. Uses segmentation map
-       to achieve this.
+    '''"Cleans" image of external sources.
 
     Parameters
     ----------
@@ -157,8 +156,7 @@ def _calculateRadius(y, A, sigma):
 
 def maskstarsPSF(image: np.ndarray, objs: List, header, skyCount: float,
                  numSigmas=5., adaptive=True, sky_err=0.0) -> np.ndarray:
-    '''Function that uses the PSF to estimate stars radius and then masks them
-       from the image mask stars.
+    '''Use the PSF to estimate stars radius, then masks them out.
 
     Parameters
     ----------

diff --git a/pawlikMorphLSST/pixmap.py b/pawlikMorphLSST/pixmap.py
@@ -23,12 +23,15 @@ def __init__(self, value):
         raise AttributeError
 
 
-def calcRmax(image, mask):
+def calcRmax(image: np.ndarray, mask: np.ndarray) -> float:
     '''Function to calculate the maximum extent of a binary pixel map
 
     Parameters
     ----------
 
+    image : float, 2d np.ndarray
+        Image of galaxy.
+
     mask : np.ndarray
         Binary pixel mask
 
@@ -52,8 +55,7 @@ def calcRmax(image, mask):
 
 def calcMaskedFraction(oldMask: np.ndarray, starMask: np.ndarray,
                        cenpix: List[float]) -> float:
-    '''Function that calculates the fraction of object pixels that are masked
-       due to presence of a star
+    '''Calculates the fraction of pixels that are masked.
 
     Parameters
     ----------
@@ -85,8 +87,7 @@ def calcMaskedFraction(oldMask: np.ndarray, starMask: np.ndarray,
 
 
 def checkPixelmapEdges(mask: np.ndarray) -> bool:
-    '''Function to check if the pixelmap hits the edge of the image,
-       and flags if it does
+    '''Flag image if galaxy pixels are on edge of image.
 
     Parameters
     -------
@@ -126,8 +127,10 @@ def checkPixelmapEdges(mask: np.ndarray) -> bool:
 
 def pixelmap(image: np.ndarray, threshold: float, filterSize: int,
              starMask=None) -> np.ndarray:
-    ''' Calculates an object binary mask using a mean filter and 8 connected
-        pixels and a given threshold.
+    ''' Calculates an object binary mask.
+
+        This is acheived using a mean filter, 8 connected
+        pixels, and a given threshold.
 
     Parameters
     ----------