https://github.com/lsstdesc/blendingtoolkit
Tools to create blend catalogs, produce training samples and implement blending metrics
https://github.com/lsstdesc/blendingtoolkit
blended-galaxies blending cosmology crowded-scenes galaxies simulation tutorials
Last synced: 3 months ago
JSON representation
Tools to create blend catalogs, produce training samples and implement blending metrics
- Host: GitHub
- URL: https://github.com/lsstdesc/blendingtoolkit
- Owner: LSSTDESC
- License: mit
- Created: 2018-07-27T15:22:14.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2025-07-29T21:04:56.000Z (6 months ago)
- Last Synced: 2025-08-31T07:39:04.749Z (5 months ago)
- Topics: blended-galaxies, blending, cosmology, crowded-scenes, galaxies, simulation, tutorials
- Language: Jupyter Notebook
- Homepage: https://lsstdesc.org/BlendingToolKit/index.html
- Size: 189 MB
- Stars: 30
- Watchers: 263
- Forks: 11
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# BlendingToolKit
[](https://github.com/LSSTDESC/BlendingToolKit/actions/workflows/pytest.yml)
[](https://github.com/LSSTDESC/BlendingToolKit/actions/workflows/notebooks.yml)
[](https://github.com/LSSTDESC/BlendingToolKit/actions/workflows/docs.yml)
[](https://codecov.io/gh/LSSTDESC/BlendingToolKit)
[](https://github.com/pre-commit/pre-commit)
[![PyPI][pypi-badge]][pypi]
[pypi-badge]:
[pypi]:
## 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 .
## Workflow
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 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.
## Citing BTK
If you use this software for your research, please cite using the following bibtex entry:
```
@article{article,
author = {Mendoza, Ismael and Torchylo, Andrii and Sainrat, Thomas and Guinot, Axel and Boucaud, Alexandre and Paillasa, Maxime and Avestruz, Camille and Adari, Prakruth and Aubourg, Eric and Biswas, Biswajit and Buchanan, James and Burchat, Patricia and Doux, Cyrille and Joseph, Remy and Kamath, Sowmya and Malz, Alex and Merz, Grant and Miyatake, Hironao and Roucelle, Cécile and Zhang, Tianqing},
year = {2025},
month = {02},
pages = {},
title = {The Blending ToolKit: A simulation framework for evaluation of galaxy detection and deblending},
volume = {8},
journal = {The Open Journal of Astrophysics},
doi = {10.33232/001c.129699}
}
```