Readme fixes (#434)

* fix badges

* bug tracker points to correct place now

* add version flag to prevent confusion for now

* update diagram

* add very short example in REAMDE

* small modification

README.md

@@ -1,8 +1,8 @@
 # BlendingToolKit
 
-![tests](https://github.com/LSSTDESC/BlendingToolKit/workflows/tests/badge.svg)
-![tests](https://github.com/LSSTDESC/BlendingToolKit/workflows/docs/badge.svg)
+[![tests](https://github.com/LSSTDESC/BlendingToolKit/actions/workflows/pytest.yml/badge.svg?branch=main)](https://github.com/LSSTDESC/BlendingToolKit/actions/workflows/pytest.yml)
 [![notebooks](https://github.com/LSSTDESC/BlendingToolKit/actions/workflows/notebooks.yml/badge.svg?branch=main)](https://github.com/LSSTDESC/BlendingToolKit/actions/workflows/notebooks.yml)
+[![docs](https://github.com/LSSTDESC/BlendingToolKit/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/LSSTDESC/BlendingToolKit/actions/workflows/docs.yml)
 [![codecov](https://codecov.io/gh/LSSTDESC/BlendingToolKit/branch/main/graph/badge.svg)](https://codecov.io/gh/LSSTDESC/BlendingToolKit)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
@@ -24,14 +24,72 @@ To get started with BTK check at our quickstart notebook at: `notebooks/00-quick
 
 <img src="docs/source/images/diagram.png" alt="btk workflow" width="550"/>
 
-- In red are the BTK objects that can be customized in various ways by BTK users.
+In red are components of the BTK pipeline that are intended to be easily customized by users to meet their
+science needs.
+
+## Code example
+
+In what follows we illustrate how to use BTK to generate blended images, run a deblended on them, and
+evaluate the performance of the deblender using metrics. For more details on this example see our
+quick-start notebook at: `notebooks/00-quickstart.ipynb`
+
+```python
+import btk
+
+# setup CATSIM catalog
+catalog_name = "../data/input_catalog.fits"
+catalog = btk.catalog.CatsimCatalog.from_file(catalog_name)
+
+# setup survey parameters
+survey = btk.survey.get_surveys("LSST")
+
+# setup sampling function
+# this function determines how to organize galaxies in catalogs into blends
+stamp_size = 24.0
+sampling_function = btk.sampling_functions.DefaultSampling(
+    catalog=catalog, max_number=5, max_mag=25.3, stamp_size=stamp_size
+)
+
+# setup generator to create batches of blends
+batch_size = 100
+
+draw_generator = btk.draw_blends.CatsimGenerator(
+    catalog, sampling_function, survey, batch_size, stamp_size
+)
+
+# get bacth of blends
+blend_batch = next(draw_generator)
+
+# setup deblender (we use SEP in this case)
+deblender = SepSingleBand(max_n_sources=5, # same as above
+                          use_band=2 # measure on 'r' band
+                          )
+
+# run deblender on generated blends
+deblend_batch = deblender(blend_batch)
+
+# setup matcher
+matcher = PixelHungarianMatcher(pixel_max_sep=5.0 # maximum separation in pixels for matching
+)
+
+# match true and predicted catalogs
+truth_catalogs = blend_batch.catalog_list
+pred_catalogs = deblend_batch.catalog_list
+matching = matcher(true_catalog_list, pred_catalog_list) # matching object
+
+# compute detection performance on this batch
+recall = btk.metrics.detection.Recall(batch_size)
+precision = btk.metrics.detection.Precision(batch_size)
+print("Recall: ", recall(matching.detected, matching.matched))
+print("Precision: ", precision(matching.detected, matching.matched))
+```
 
 ## Installation
 
 BTK is pip installable, with the following command:
 
 ```bash
-pip install blending_toolkit
+pip install blending-toolkit==1.0.0b1
 ```
 
 In case of any issues and for details of required packages, please see the more detailed installation instructions [here](https://lsstdesc.org/BlendingToolKit/install.html).

docs/source/install.rst

@@ -37,9 +37,9 @@ Once you installed ``galsim``, you can install the latest released version of ``
 
 .. code-block::
 
-    pip install blending_toolkit
+    pip install blending-toolkit==1.0.0b1
 
-This should install all other missing dependencies if necessary. You can then import the package as follows:
+The version flag is necessary as the latest version is a pre-release. This command should install all other missing dependencies if necessary. You can then import the package as follows:
 
 .. code-block:: python
 
@@ -48,8 +48,7 @@ This should install all other missing dependencies if necessary. You can then im
 
 Scarlet
 ------------------------------
-BTK includes the Scarlet deblender as one of its ``Deblender`` classes. This means that you
-can easily run the scarlet deblender on BTK blends.
+BTK includes the Scarlet deblender as one of its ``Deblender`` classes. This means that you can easily run the scarlet deblender on BTK blends.
 
 First you need to install scarlet, this is not by default installed with BTK as scarlet
 is not in pypi. You can install scarlet by following the instructions here: `<https://pmelchior.github.io/scarlet/install.html>`_.

pyproject.toml

@@ -29,7 +29,7 @@ repository = "https://github.com/LSSTDESC/BlendingToolKit"
 homepage = "https://lsstdesc.org/BlendingToolKit/index.html"
 
 [tool.poetry.urls]
-"Bug Tracker" = "https://github.com/python-poetry/poetry/issues"
+"Bug Tracker" = "https://github.com/LSSTDESC/BlendingToolKit/issues"
 
 [tool.poetry.dependencies]
 numpy = ">=1.22"