Metadata-Version: 2.1
Name: blending_toolkit
Version: 1.0.0b9
Summary: Blending ToolKit
Home-page: https://lsstdesc.org/BlendingToolKit/index.html
License: MIT
Keywords: cosmology,galaxies,blending,lsst,simulation
Author: Ismael Mendoza
Author-email: imendoza@umich.edu
Requires-Python: >=3.8.1,<3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.8
Requires-Dist: astropy (>=5.1)
Requires-Dist: fast3tree (>=0.4.1,<0.5.0)
Requires-Dist: galsim (>=2.4.9)
Requires-Dist: h5py (>=3.9.0,<4.0.0)
Requires-Dist: matplotlib (>=3.7.1)
Requires-Dist: numpy (>=1.22)
Requires-Dist: scikit-image (>=0.20.0)
Requires-Dist: scipy (>=1.9.1)
Requires-Dist: sep (>=1.2.1)
Requires-Dist: surveycodex (>=1.2.0,<2.0.0)
Requires-Dist: tqdm (>=4.65.0)
Project-URL: Bug Tracker, https://github.com/LSSTDESC/BlendingToolKit/issues
Project-URL: Repository, https://github.com/LSSTDESC/BlendingToolKit
Description-Content-Type: text/markdown

# BlendingToolKit

[![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)
[![PyPI][pypi-badge]][pypi]

[pypi-badge]: <https://img.shields.io/pypi/pyversions/blending-toolkit?color=yellow&logo=pypi>
[pypi]: <https://pypi.org/project/blending-toolkit/>

## Summary

Framework for fast generation and analysis of galaxy blends catalogs. This toolkit is a convenient way of
producing multi-band postage stamp images of blend scenes and evaluate the performance of deblending algorithms.

Documentation can be found at <https://lsstdesc.org/BlendingToolKit/index.html>.

## Workflow

<img src="docs/source/images/diagram.png" alt="btk workflow" width="550"/>

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 deblender 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 catalog 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
)

# get batch of blends
blend_batch = next(draw_generator)

# setup deblender (we use SEP in this case)
deblender = btk.deblend.SepSingleBand(max_n_sources=5,
                          use_band=2 # measure on 'r' band
                          )

# run deblender on generated blend images (all batches)
deblend_batch = deblender(blend_batch)

# setup matcher
matcher = btk.match.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(truth_catalogs, pred_catalogs) # object with matching information

# compute detection performance on this batch
recall = btk.metrics.detection.Recall(batch_size)
precision = btk.metrics.detection.Precision(batch_size)
print("Recall: ", recall(matching.tp, matching.t, matching.p))
print("Precision: ", precision(matching.tp, matching.t, matching.p))
```

## Installation

BTK is pip installable, with the following command:

```bash
pip install --pre blending-toolkit
```

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).

## Contributing

Everyone can contribute to this project, please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) document for details.

In short, to interact with the project you can:

- Ask or Answer questions on the [Discussions Q&A page](https://github.com/LSSTDESC/BlendingToolKit/discussions).
- Report a bug by opening a [GitHub issue](https://github.com/LSSTDESC/BlendingToolKit/issues).
- Open a [GitHub issue](https://github.com/LSSTDESC/BlendingToolKit/issue) or [Discussions](https://github.com/LSSTDESC/BlendingToolKit/discussions) to ask for feedback on a planned contribution.
- Submit a [Pull Request](https://github.com/LSSTDESC/BlendingToolKit/pulls) to contribute to the code.

Issues marked with `contributions welcome` or `good first issue` are particularly good places to start. These are great ways to learn more about the inner workings of BTK.

