Merge branch '#16' of https://github.com/LSSTDESC/BlendingToolKit into …

…#16

README.md

@@ -2,7 +2,7 @@
 [![Documentation Status](https://readthedocs.org/projects/blendingtoolkit/badge/?version=latest)](https://blendingtoolkit.readthedocs.io/en/latest/?badge=latest)
 
 # BlendingToolKit
-Tools to create blend catalogs, produce training samples and implement blending metrics
+Tools to create blend catalogs, produce training samples and implement blending metrics.
 
 Documentation can be found at https://blendingtoolkit.readthedocs.io/en/latest/
 
@@ -12,8 +12,8 @@ Documentation can be found at https://blendingtoolkit.readthedocs.io/en/latest/
 
 ## Running BlendingToolKit
 - BlendingToolKit (btk) requires an input catalog that contains information required to simulate galaxies and blends.
-This repository includes sample input catalogs with small number of galaxies that can be used to draw blend images with btk. See [tutorials](https://github.com/LSSTDESC/BlendingToolKit/tree/master/notebooks) to learn how to run btk with these catalogs.
-- Catalog corresponding to one square degree sky and pre-processed WeakLensingDeblending catalogs can be downloaded from [here](https://stanford.app.box.com/s/s1nzjlinejpqandudjyykjejyxtgylbk).
+This repository includes sample input catalogs with a small number of galaxies that can be used to draw blend images with btk. See [tutorials](https://github.com/LSSTDESC/BlendingToolKit/tree/master/notebooks) to learn how to run btk with these catalogs.
+- Catalog corresponding to one square degree of sky and pre-processed WeakLensingDeblending catalogs can be downloaded from [here](https://stanford.app.box.com/s/s1nzjlinejpqandudjyykjejyxtgylbk).
 
 ## Requirements
 The code is intended to run in python >=3.6.
@@ -26,10 +26,10 @@ To run btk you need to install
 - scipy
 - lmfit
 
-More detailed installation instructions can be found [here](https://blendingtoolkit.readthedocs.io/en/latest/install.html)
+More detailed installation instructions can be found [here](https://blendingtoolkit.readthedocs.io/en/latest/install.html).
 
 ### Optional
-The tutorials include examples of using btk with some packages like
+The tutorials include examples of using btk with some detection, deblending or measurement packages including
 - [scarlet](https://github.com/fred3m/scarlet/) (multi-band deblender)
-- [sep](https://sep.readthedocs.io/en/v1.0.x/index.html)(Source Extraction and Photometry)
-- [lsst](https://pipelines.lsst.io) science pipeline
+- [sep](https://sep.readthedocs.io/en/v1.0.x/index.html) (Source Extraction and Photometry)
+- [lsst](https://pipelines.lsst.io) (LSST science pipeline)

btk/config.py

@@ -1,5 +1,5 @@
 class Simulation_params(object):
-    """Parameters to create blends.
+    """Parameter values to create blends.
 
     Attributes:
         catalog_name: Name of input catalog from which to draw objects.
@@ -14,7 +14,7 @@ class Simulation_params(object):
             S/N threshold, where the signal N is calculated for the full
             exposure time and the noise N is set by the expected fluctuations
             in the sky background during a full exposure.
-        verbose: If true prints returns description at multiple steps.
+        verbose: If true, prints description at multiple steps.
     """
     def __init__(self, catalog_name, max_number=2,
                  batch_size=8, stamp_size=24,

docs/source/index.rst

@@ -14,13 +14,13 @@
 *BlendingToolKit* (btk) is a framework to generate images of blended objects and
 evaluate performance metrics for different algorithms.
 
-Detecting and separating overlapping sources, or "deblending", is primarily a research problem with several potential algorithmic solutions, including machine learning approaches. Computation of performance metrics on identical datasets will enable comparison between different algorithms. BTK provides a framework to easily and quickly generate datasets of blended objects for testing different algorithms, along with training samples for machine learning algorithms.
+Detecting and separating overlapping sources, or "deblending", is primarily a research problem with several potential algorithmic solutions, including machine learning approaches. Computation of performance metrics on identical datasets will enable comparison between different algorithms. The goals of the btk framework are to allow the user to easily and quickly generate datasets of blended objects for testing different algorithms, as well as training samples for machine learning algorithms.
 
-Key features of the framework are:
+Key features or functionalities of the framework include:
 
-* It can generate training/validation/test sets for developing and testing detection, deblending and measurement algorithms.
-* It includes data augmentation and independent (but reproducible) noise realizations.
-* It is easily customizable with options to include user defined functions for blend generation, observing conditions, etc,. produces images on the fly.
+* generation of training/validation/test sets for developing and testing detection, deblending and measurement algorithms.
+* data augmentation and independent (but reproducible) noise realizations.
+* customization options for including user-defined functions for blend generation, observing conditions, etc., and for producing images on the fly.
 
 Getting Started
 ==================

docs/source/install.rst

@@ -2,9 +2,9 @@ Installation
 ===============
 
 *BlendingToolKit* (btk) is essentially a wrapper around the
-`WealLensingDeblending <https://weaklensingdeblending.readthedocs.io/en/latest/>`_
-which uses `GalSim <https://github.com/GalSim-developers/GalSim>`_ to simulate
-the galaxy images. So these packages along with
+`WeakLensingDeblending <https://weaklensingdeblending.readthedocs.io/en/latest/>`_
+package, which uses `GalSim <https://github.com/GalSim-developers/GalSim>`_ to simulate galaxy images. 
+These packages along with
 their dependencies need to be installed first.
 
 The following dependencies are pip installable:
@@ -15,17 +15,17 @@ The following dependencies are pip installable:
 * scipy
 * lmfit
 
-Install Galsim
+Install GalSim
 -------------------------------
 
 GalSim is a python module that has much of its implementation in C++ for
 improved computational efficiency. It can be installed with
 ::
     pip install galsim
 
-However you may have to install FFTW and Eigen manually. Refer
+However you may have to install FFTW and Eigen manually. Refer to 
 `this <https://github.com/GalSim-developers/GalSim/blob/releases/2.1/INSTALL.md>`_
-for mre details.
+for more details.
 
 Install WeakLensingDeblending package
 ---------------------------------------
@@ -47,7 +47,7 @@ First download the repo:
 ::
     git clone https://github.com/LSSTDESC/BlendingToolKit.git
 
-then install using
+Then install using
 ::
     cd BlendingToolKit
     python setup.py install
@@ -56,15 +56,14 @@ Optional Packages
 -------------------------------
 
 *BlendingToolKit* is meant to perform detection/deblending/measurement with any
-user input algorithm. Thus, as such no algorithm is hard coded into the basic
-framework. However, the tutorial notebooks do include examples of how these can
-be performed with btk.
-
-The tutorial notebooks require:
+user input algorithm; therefore, no algorithm is hard-coded into the basic
+framework. However, the tutorial notebooks include several examples of detection/deblending/measurement 
+algoritms that can be performed with btk.
+These tutorial notebooks require:
 
 #. scarlet_ (multi-band deblender)
 #. sep_ (Python library for Source Extraction and Photometry)
-#. lsst_ science pipeline
+#. lsst_ (LSST science pipeline)
 
 
 .. _scarlet: https://scarlet.readthedocs.io/en/latest/index.html

docs/source/tutorials.rst

@@ -3,31 +3,31 @@ Tutorials
 
 The following jupyter notebooks are included in the `notebooks/` directory:
 
-Run basic btk (*run_basic.ipynb*)
+Run basic btk (*run_basic.ipynb*).
 -----------------------------------
 
-This `notebook <https://github.com/LSSTDESC/BlendingToolKit/blob/%2315/notebooks/run_basic.ipynb>`_ shows the how btk can generate multi-band blend image scenes along with isolated object images. PSF convolved object images are drawn in isolation and in the blend for each band.
+This `notebook <https://github.com/LSSTDESC/BlendingToolKit/blob/%2315/notebooks/run_basic.ipynb>`_ shows how btk can be used to generate images of multi-band blend scenes, along with isolated object images -- i.e., PSF-convolved object images are drawn both in isolation and in the blend scene for each band.
 
 The notebook shows examples of performing:
 
-* detection with `SEP <https://sep.readthedocs.io/en/v1.0.x/index.html>`_ , `lsst science pipeline <https://pipelines.lsst.io>`
-* deblending with `scarlet <https://scarlet.readthedocs.io/en/latest/index.html>`_
+* detection with `SEP <https://sep.readthedocs.io/en/v1.0.x/index.html>`_, `lsst science pipeline <https://pipelines.lsst.io>`_,
+* deblending with `scarlet <https://scarlet.readthedocs.io/en/latest/index.html>`_,
 * segmentation with SEP.
 
 The notebook also includes functions helpful for plotting multi-band images.
 
-Run with user input custom functions (*custom_sampling_function.ipynb*)
+Run with user-input custom functions (*custom_sampling_function.ipynb*).
 --------------------------------------------------------------------------
 
 This `notebook <https://github.com/LSSTDESC/BlendingToolKit/blob/%2315/notebooks/custom_sampling_function.ipynb>`_ demonstrates how users can define their own sampling functions to draw blend image scenes.
 
-Also shown is how a user defined custom function can generate different observing conditions. This would enable on the fly generation of blend scene images with different noise levels and observing PSFs.
+Also shown is an example of how a user-defined custom function can be used to generate different observing conditions. This enables on-the-fly generation of blend scene images with different noise levels and observing PSFs.
 
 
-Evaluate Metrics with btk (*evaluate_metrics.ipynb*)
-----------------------------------------------------
-This `notebook <https://github.com/LSSTDESC/BlendingToolKit/blob/%2315/notebooks/evaluate_metrics.ipynb>`_ shows how to test performance of different detection/deblending/measurement algorithms. At present this only assesses detection performance by returning the number of objects correctly detected, number undetected and number of spurious detections.
+Evaluate metrics with btk (*evaluate_metrics.ipynb*).
+------------------------------------------------------
+This `notebook <https://github.com/LSSTDESC/BlendingToolKit/blob/%2315/notebooks/evaluate_metrics.ipynb>`_ shows how to test the performance of different detection/deblending/measurement algorithms. At present this only assesses detection performance by returning the number of objects correctly detected, the number of undetected objects and the number of spurious detections.
 
-Draw blends (*create_blend_generator*): Simulates scene of overlapping objects, convolved by PSF and with pixel noise (option set in *config*). Scene image is generated in each observing band. Isolated image of each object is also drawn without pixel contributions from other objects, in each band.
+Draw blends (*create_blend_generator*): Simulates a scene of overlapping objects, convolved by a PSF, with pixel noise (option set in *config*). The scene image is generated in each observing band. An isolated image of each object is also drawn in each band, with no pixel contributions from other objects.
 
 

docs/source/user_guide.rst

@@ -1,24 +1,24 @@
 User Guide
 ==============
 
-This document gives a detailed look into the work-flow of *BlendingToolKit* (btk). For a quick tutorial on how to run btk, see the JuPyter notebook tutorials :doc:`here </tutorials>`. This page is especially useful if you plan on using btk with your own detection/deblending/measurement algorithm.
+This document gives a detailed look into the work-flow of *BlendingToolKit* (btk). For a quick tutorial on how to run btk, see the JuPyter notebook tutorials `here <tutorials.html>`_. This page is especially useful if you plan to use btk with your own detection/deblending/measurement algorithm.
 
 
-The workflow of btk is shown below
+The workflow of btk is shown here:
 
 .. image:: images/flow_chart.png
    :align: center
 
 
-1. Set parameters (*config*): define parameters to create postage stamps, including size of stamp, number of objects per blend, and how many stamps are to be drawn in one batch, i.e yielded at once by btk. The observing survey name (e.g. LSST. DES) is set here along with name of the input catalog and names of observing bands.
-2. Load Catalog (*load_catalog*): Reads the input catalog file. This step includes an option to input a selection criteria.
-3. Make blend catalog (*create_blend_generator*): Samples objects from the input catalog based on a user defined sampling function to create a catalog with parameters of each blend.  This step output a generator that yields a new set of catalogs each time run with *next()*. This `notebook <https://github.com/LSSTDESC/BlendingToolKit/blob/%2315/notebooks/custom_sampling_function.ipynb>`_ shows different examples of user input sampling functions to create different blend catalogs.
-4. Make observing conditions (*create_observing_generator*): Creates a class that contains information about the observing conditions like PSF, noise level, etc. The default is to use the full depth values corresponding to the survey named in config. However a user can define a function to generate this. This `notebook <https://github.com/LSSTDESC/BlendingToolKit/blob/%2315/notebooks/custom_sampling_function.ipynb>`_ shows an example of a user input function to generate observing conditions.
-5. Draw blends (*create_blend_generator*): Simulates scene of overlapping objects, convolved by PSF and with pixel noise (option set in *config*). Scene image is generated in each observing band. Isolated image of each object is also drawn without pixel contributions from other objects, in each band.
-6. Detection/Deblending/Measure (*measure*): A user defined class to perform detection/deblending/measurement goes here. *btk* does not include any algorithm as default but only provides a a framework for the user to run their algorithm for the images generated in *create_blend_generator*. This `notebook <https://github.com/LSSTDESC/BlendingToolKit/blob/%2315/notebooks/run_basic.ipynb>`_ contains examples of running btk with `SEP <https://sep.readthedocs.io/en/v1.0.x/index.html>`_ (SExtractor with python) , `lsst science pipeline <https://pipelines.lsst.io>`_ and `scarlet <https://scarlet.readthedocs.io/en/latest/index.html>`_.
-7. Compute metrics (*metrics*): compares the true centroids, shapes, flux values to those predicted by the user algorithm. At present this only assesses detection performance by returning the number of objects correctly detected, number undetected and number of spurious detections. This `notebook <https://github.com/LSSTDESC/BlendingToolKit/blob/%2315/notebooks/evaluate_metrics.ipynb>`_ shows how this can be done.
+1. Set parameter values (*config*): define parameter values to create postage stamps, including size of stamp, number of objects per blend, and how many stamps are to be drawn in one batch -- i.e., the number of stamps btk will produce together in a singe batch. The observing survey name (e.g., LSST, DES), the name of the input catalog to draw objects from, and the names of the observing bands are also specified here. See `here <src/btk.config.html>`_ for more details.
+2. Load Catalog (*load_catalog*): Reads the input catalog file. This step includes an option to input user-defined selection criteria.
+3. Make blend catalog (*create_blend_generator*): Samples objects from the input catalog based on a user defined sampling function to create a catalog with parameters of each blend. This step outputs a generator that yields a new set of catalogs each time it is run with *next()*. This `notebook <https://github.com/LSSTDESC/BlendingToolKit/blob/%2315/notebooks/custom_sampling_function.ipynb>`_ shows several examples of user input sampling functions to create different blend catalogs.
+4. Make observing conditions (*create_observing_generator*): Creates a class that contains information about the observing conditions such as PSF definition, noise level, etc. The default is to use the full-depth values corresponding to the survey named in *config*. However, a user can define a function to generate class with observing conditions of their choice. The user function can be such that it varies the observing conditions every time it's called. This `notebook <https://github.com/LSSTDESC/BlendingToolKit/blob/%2315/notebooks/custom_sampling_function.ipynb>`_ shows an example of a such a user input function that generates different observing conditions. Note that all blends drawn in a batch will be generated with the same observing conditions.
+5. Draw blends (*create_blend_generator*): Simulates scene of overlapping objects, convolved by the PSF and with pixel noise (option set in *config*). Scene image is generated in each observing band. An "isolated" image of each object is also drawn without pixel contributions from other objects, in each band.
+6. Detection/Deblending/Measure (*measure*): A user defined class to perform detection/deblending/measurement goes here. *btk* does not include any default algorithm; rather, it provides a framework for the user to run their choice of algorithm for the images generated in *create_blend_generator*. This `notebook <https://github.com/LSSTDESC/BlendingToolKit/blob/%2315/notebooks/run_basic.ipynb>`_ contains examples of running btk with `SEP <https://sep.readthedocs.io/en/v1.0.x/index.html>`_ (SExtractor with python) , `LSST science pipeline <https://pipelines.lsst.io>`_ and `SCARLET <https://scarlet.readthedocs.io/en/latest/index.html>`_.
+7. Compute metrics (*metrics*): compares the true centroids, shapes, and flux values to those predicted by the user-provided *measure* algorithm. Currently, *metrics* assesses only detection performance by returning the number of objects correctly detected, the number that are undetected and the number of spurious detections. This `notebook <https://github.com/LSSTDESC/BlendingToolKit/blob/%2315/notebooks/evaluate_metrics.ipynb>`_ shows how this can be done.
 
 
 Utils
 -------
-*btk/utils.py* contains functions that the user may find useful in creating functions to perform detection/deblending/measurement in *measure*. It shows how a class derived from *measure.Measurement_params* can be defined by the user for use with SEP, lsst science pipeline or stand-alone scarlet.
+*btk/utils.py* contains functions that the user may find useful in creating functions to perform detection/deblending/measurement in *measure*. It shows how a class derived from *measure.Measurement_params* can be defined by the user for use with SEP, the LSST science pipeline or stand-alone SCARLET; see point 6 above.