add user guide to doc (#487)

docs/source/index.rst

@@ -16,6 +16,7 @@ Getting Started
    :maxdepth: 1
 
    install
+   user_guide
    catalog
    tutorials
 

docs/source/user_guide.rst

@@ -0,0 +1,31 @@
+User Guide
+==============
+
+This document gives a detailed look into the workflow of *BlendingToolKit* (btk). For tutorials on running BTK, take a look at our `tutorials <https://lsstdesc.org/BlendingToolKit/tutorials.html>`_. This page is especially useful if you plan to use BTK with your own detection or deblending algorithm.
+
+The workflow is as follows:
+
+.. image:: images/diagram.png
+   :align: center
+
+1. *Set parameter values*: 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.
+
+2. *Load Catalog:* Reads the input catalog file. This must be done using a :class:`~btk.catalog.Catalog`-like object (e.g. :class:`~btk.catalog.CatsimCatalog`), either by providing directly the catalog or by using the :meth:`~btk.catalog.Catalog.from_file` method.
+
+3. *Specify the* :class:`~btk.sampling_functions.SamplingFunction`: A sampling function is a callable object, which takes into input a catalog and returns specific entries along with parameters for a given blend (such as object shifts in the stamp for instance).
+You may use the default class :class:`~btk.sampling_functions.DefaultSamplingFunction`, or define a new one if you want to have more control over how the galaxies are selected and the blends are defined. Please take a look at our `tutorials <https://lsstdesc.org/BlendingToolKit/tutorials.html>`_ page for more details.
+
+4. *Choose a survey:* BTK now relies on the `galcheat <https://github.com/aboucaud/galcheat>`_ package. This package contains informations on various survey, including LSST, HSC and HST COSMOS (among others). It provides this information as a :class:`~galcheat.survey.Survey` object, which can be easily imported in BTK using the survey name, via the `get_surveys` function. The user can also provide a custom PSF at this point, either as a `galsim` model or with a FITS file, or use the default (optical + atmospheric) PSF  provided by BTK.
+
+5. *Draw blends*: Simulates scene of overlapping objects, convolved by the PSF and with pixel noise. This step is done by creating a :class:`~btk.draw_blends.DrawBlendsGenerator`-like object (e.g. :class:`~btk.draw_blends.CatsimGenerator`), which takes as input the catalog, sampling function and survey created in step 2 to 4. It can then be called using ``next(draw_blends_generator)`` to get the results as a `:class:btk.blend_batch.BlendBatch`, which includes attributes containing the blend images with the key ``blend_images``, the isolated galaxy images ``isolated_images``, and the blend parameters with the key ``catalog_list``.
+Fluxes in BTK are calculated using `galcheat` based on the :func:`~galcheat.utilities.mag2counts` function and corresponding survey and filter parameters. Please see the `galcheat <https://aboucaud.github.io/galcheat/api/utilities.html>` documentation for more details.
+
+6. *Detection and Deblending*: Performs user-defined measurements (detection, segmentation, deblended images) on the generated blends. The user may create a subclass of  :class:`~btk.deblend.Deblender` to deblend the corresponding blends. We currently have 3 available 'deblenders':
+
+- SourceExtractor in Python (SEP)
+- Scarlet
+- Peak-finding algorithm (from `scikit-image`)
+
+ The user is also available to implement their own deblender and use it as part of BTK. See the `tutorials page <https://lsstdesc.org/BlendingToolKit/tutorials.html>`_ for details.
+
+7. *Matching and Evaluation*: Matches the predicted detections to the true galaxies' centroids and compute metrics that evaluate the quality of the detection, segmentation and deblended images.