# 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/psf/black)
[](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 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{mendoza2024btk,
author = {{Mendoza}, Ismael and {Torchylo}, Andrii and {Sainrat}, Thomas and {Guinot}, Axel and {Boucaud}, Alexandre and {Paillassa}, 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 I. and {Merz}, Grant and {Miyatake}, Hironao and {Roucelle}, C{\'e}cile and {Zhang}, Tianqing and {the LSST Dark Energy Science Collaboration}},
title = "{The Blending ToolKit: A simulation framework for evaluation of galaxy detection and deblending}",
journal = {arXiv e-prints},
keywords = {Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - Cosmology and Nongalactic Astrophysics},
year = 2024,
month = sep,
eid = {arXiv:2409.06986},
pages = {arXiv:2409.06986},
doi = {10.48550/arXiv.2409.06986},
archivePrefix = {arXiv},
eprint = {2409.06986},
primaryClass = {astro-ph.IM},
adsurl = {https://ui.adsabs.harvard.edu/abs/2024arXiv240906986M},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
```
Raw data
{
"_id": null,
"home_page": "https://lsstdesc.org/BlendingToolKit/index.html",
"name": "blending_toolkit",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.8.1",
"maintainer_email": null,
"keywords": "cosmology, galaxies, blending, lsst, simulation",
"author": "Ismael Mendoza",
"author_email": "imendoza@umich.edu",
"download_url": "https://files.pythonhosted.org/packages/28/0c/9adec7429df53a3003efc0c22d937ee44f1a605af3dcc7877d0dc3bf0bf8/blending_toolkit-1.0.1.tar.gz",
"platform": null,
"description": "# BlendingToolKit\n\n[](https://github.com/LSSTDESC/BlendingToolKit/actions/workflows/pytest.yml)\n[](https://github.com/LSSTDESC/BlendingToolKit/actions/workflows/notebooks.yml)\n[](https://github.com/LSSTDESC/BlendingToolKit/actions/workflows/docs.yml)\n[](https://codecov.io/gh/LSSTDESC/BlendingToolKit)\n[](https://github.com/psf/black)\n[](https://github.com/pre-commit/pre-commit)\n[![PyPI][pypi-badge]][pypi]\n\n[pypi-badge]: <https://img.shields.io/pypi/pyversions/blending-toolkit?color=yellow&logo=pypi>\n[pypi]: <https://pypi.org/project/blending-toolkit/>\n\n## Summary\n\nFramework for fast generation and analysis of galaxy blends catalogs. This toolkit is a convenient way of\nproducing multi-band postage stamp images of blend scenes and evaluate the performance of deblending algorithms.\n\nDocumentation can be found at <https://lsstdesc.org/BlendingToolKit/index.html>.\n\n## Workflow\n\n<img src=\"docs/source/images/diagram.png\" alt=\"btk workflow\" width=\"550\"/>\n\nIn red are components of the BTK pipeline that are intended to be easily customized by users to meet their\nscience needs.\n\n## Code example\n\nIn what follows we illustrate how to use BTK to generate blended images, run a deblender on them, and\nevaluate the performance of the deblender using metrics. For more details on this example see our\nquick-start notebook at `notebooks/00-quickstart.ipynb`.\n\n```python\nimport btk\n\n# setup CATSIM catalog\ncatalog_name = \"../data/input_catalog.fits\"\ncatalog = btk.catalog.CatsimCatalog.from_file(catalog_name)\n\n# setup survey parameters\nsurvey = btk.survey.get_surveys(\"LSST\")\n\n# setup sampling function\n# this function determines how to organize galaxies in catalog into blends\nstamp_size = 24.0\nsampling_function = btk.sampling_functions.DefaultSampling(\n catalog=catalog, max_number=5, max_mag=25.3, stamp_size=stamp_size\n)\n\n# setup generator to create batches of blends\nbatch_size = 100\ndraw_generator = btk.draw_blends.CatsimGenerator(\n catalog, sampling_function, survey, batch_size\n)\n\n# get batch of blends\nblend_batch = next(draw_generator)\n\n# setup deblender (we use SEP in this case)\ndeblender = btk.deblend.SepSingleBand(max_n_sources=5,\n use_band=2 # measure on 'r' band\n )\n\n# run deblender on generated blend images (all batches)\ndeblend_batch = deblender(blend_batch)\n\n# setup matcher\nmatcher = btk.match.PixelHungarianMatcher(pixel_max_sep=5.0 # maximum separation in pixels for matching\n)\n\n# match true and predicted catalogs\ntruth_catalogs = blend_batch.catalog_list\npred_catalogs = deblend_batch.catalog_list\nmatching = matcher(truth_catalogs, pred_catalogs) # object with matching information\n\n# compute detection performance on this batch\nrecall = btk.metrics.detection.Recall(batch_size)\nprecision = btk.metrics.detection.Precision(batch_size)\nprint(\"Recall: \", recall(matching.tp, matching.t, matching.p))\nprint(\"Precision: \", precision(matching.tp, matching.t, matching.p))\n```\n\n## Installation\n\nBTK is pip installable, with the following command:\n\n```bash\npip install blending-toolkit\n```\n\nIn case of any issues and for details of required packages, please see the more detailed installation instructions [here](https://lsstdesc.org/BlendingToolKit/install.html).\n\n## Contributing\n\nEveryone can contribute to this project, please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) document for details.\n\nIn short, to interact with the project you can:\n\n- Ask or Answer questions on the [Discussions Q&A page](https://github.com/LSSTDESC/BlendingToolKit/discussions).\n- Report a bug by opening a [GitHub issue](https://github.com/LSSTDESC/BlendingToolKit/issues).\n- 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.\n- Submit a [Pull Request](https://github.com/LSSTDESC/BlendingToolKit/pulls) to contribute to the code.\n\nIssues 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.\n\n## Citing BTK\n\nIf you use this software for your research, please cite using the following bibtex entry:\n\n```\n@ARTICLE{mendoza2024btk,\n author = {{Mendoza}, Ismael and {Torchylo}, Andrii and {Sainrat}, Thomas and {Guinot}, Axel and {Boucaud}, Alexandre and {Paillassa}, 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 I. and {Merz}, Grant and {Miyatake}, Hironao and {Roucelle}, C{\\'e}cile and {Zhang}, Tianqing and {the LSST Dark Energy Science Collaboration}},\n title = \"{The Blending ToolKit: A simulation framework for evaluation of galaxy detection and deblending}\",\n journal = {arXiv e-prints},\n keywords = {Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - Cosmology and Nongalactic Astrophysics},\n year = 2024,\n month = sep,\n eid = {arXiv:2409.06986},\n pages = {arXiv:2409.06986},\n doi = {10.48550/arXiv.2409.06986},\narchivePrefix = {arXiv},\n eprint = {2409.06986},\n primaryClass = {astro-ph.IM},\n adsurl = {https://ui.adsabs.harvard.edu/abs/2024arXiv240906986M},\n adsnote = {Provided by the SAO/NASA Astrophysics Data System}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Blending ToolKit",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/LSSTDESC/BlendingToolKit/issues",
"Homepage": "https://lsstdesc.org/BlendingToolKit/index.html",
"Repository": "https://github.com/LSSTDESC/BlendingToolKit"
},
"split_keywords": [
"cosmology",
" galaxies",
" blending",
" lsst",
" simulation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c4ee43b261c73f7720d3c82b6f4440cdb36d6615374fbe4d006a080ce462562c",
"md5": "e42a050ba8f2680081b669a38a504a45",
"sha256": "614fec16e9836a1a55624059af149dad95a874e9dcfbdf5f78153f0983c39e6e"
},
"downloads": -1,
"filename": "blending_toolkit-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e42a050ba8f2680081b669a38a504a45",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.8.1",
"size": 47090,
"upload_time": "2024-10-21T17:25:57",
"upload_time_iso_8601": "2024-10-21T17:25:57.273189Z",
"url": "https://files.pythonhosted.org/packages/c4/ee/43b261c73f7720d3c82b6f4440cdb36d6615374fbe4d006a080ce462562c/blending_toolkit-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "280c9adec7429df53a3003efc0c22d937ee44f1a605af3dcc7877d0dc3bf0bf8",
"md5": "8889f36b94f9fbd938928bc4a8536de0",
"sha256": "40294162e23e4f235e56d9f83866cc8ee9b7a1fce517d5d667f253d6975b83e1"
},
"downloads": -1,
"filename": "blending_toolkit-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "8889f36b94f9fbd938928bc4a8536de0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.8.1",
"size": 43006,
"upload_time": "2024-10-21T17:25:59",
"upload_time_iso_8601": "2024-10-21T17:25:59.050718Z",
"url": "https://files.pythonhosted.org/packages/28/0c/9adec7429df53a3003efc0c22d937ee44f1a605af3dcc7877d0dc3bf0bf8/blending_toolkit-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-21 17:25:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LSSTDESC",
"github_project": "BlendingToolKit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "blending_toolkit"
}
JSON
