BlendingToolKit

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

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.

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:

pip install blending-toolkit

In case of any issues and for details of required packages, please see the more detailed installation instructions here.

Contributing

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

In short, to interact with the project you can:

• Ask or Answer questions on the Discussions Q&A page.
• Report a bug by opening a GitHub issue.
• Open a GitHub issue or Discussions to ask for feedback on a planned contribution.
• Submit a Pull Request 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}
}