BlendingToolKit

BlendingToolKit (btk) is a framework to generate images of blended objects and evaluate performance metrics for different detection, deblending and measurement algorithms.

Detecting and separating overlapping sources, or “deblending”, is primarily a research problem with several potential algorithmic solutions, including machine learning approaches. Computation of performance metrics on identical datasets will enable comparison between different algorithms. The goals of the btk framework are to allow the user to easily and quickly generate datasets of blended objects for testing different detection, deblending and measurement algorithms, as well as training samples for machine learning algorithms.

Key features or functionalities of the framework include:

• generation of training/validation/test sets for developing and testing detection, deblending and measurement algorithms.
• data augmentation and independent (but reproducible) noise realizations.
• customization options for including user-defined functions for blend generation, observing conditions, etc., and for producing images on the fly.

Getting Started

Installation

BlendingToolKit (btk) is essentially a wrapper around the WeakLensingDeblending package, which uses GalSim to simulate galaxy images. These packages along with their dependencies need to be installed first.

The following dependencies are pip installable:

• numpy
• astropy
• fitsio
• scipy
• lmfit

Install fitsio and lmfit

These two uncommon packages can be installed via:

# in conda.
conda install -c conda-forge fitsio
conda install -c conda-forge lmfit

# in pip.
pip install fitsio
pip install lmfit

Install GalSim

GalSim is a python module that has much of its implementation in C++ for improved computational efficiency. It can be installed with

pip install galsim

However you may have to install FFTW and Eigen manually. Refer to this for more details.

Install WeakLensingDeblending package

WeakLensingDeblending package must first be cloned:

git clone https://github.com/DarkEnergyScienceCollaboration/WeakLensingDeblending.git

Then run the following inside the WeakLensingDeblending folder:

cd WeakLensingDeblending
python setup.py install

Install BlendingToolKit with GIT

The code is hosted on github. First download the repo:

git clone https://github.com/LSSTDESC/BlendingToolKit.git

Then install using

cd BlendingToolKit
python setup.py install

Optional Packages

BlendingToolKit is meant to perform detection/deblending/measurement with any user input algorithm; therefore, no detection/deblending/measurement algorithm is hard-coded into the basic framework. However, the tutorial notebooks include several examples of detection/deblending/measurement algorithms that can be performed with btk. These tutorial notebooks require:

1. scarlet (multi-band deblender)
2. sep (Python library for Source Extraction and Photometry)
3. lsst (LSST science pipeline)

Input Catalog

BlendingToolKit (btk) requires an input catalog that contains information required to simulate galaxies and blends. Each galaxy is parameterized as a bulge + disk + agn with parameters following the LSST DM catalog schema

CatSim

The catalog simulation framework (CatSim) is a database of astrophysical sources with properties that are representative of what the LSST will observe at its ten-year coadded depth. Refer to the official CatSim page for more details. The btk package includes a sample input catalog that contains parameters of 100 galaxies. A more extensive catalog can be downloaded from here.

Cosmo DC2

CosmoDC2 is a large synthetic galaxy catalog designed to support precision dark energy science with the Large Synoptic Survey Telescope (LSST). Refer to this notebook on how to inject the DC2 catalog into a CatSim-like catalog that can be analyzed with btk. The btk package includes a sample input catalog that contains parameters of 15 blend scenes with 61 galaxies.

User Guide

This document gives a detailed look into the work-flow of BlendingToolKit (btk). For a quick tutorial on how to run btk, see the jupyter notebook tutorials here. This page is especially useful if you plan to use btk with your own detection/deblending/measurement algorithm.

The workflow of btk is shown here:

1. Set parameter values (config): define parameter values to create postage stamps, including size of stamp, number of objects per blend, and how many stamps are to be drawn in one batch – i.e., the number of stamps btk will produce together in a singe batch. The observing survey name (e.g., LSST, DES), the name of the input catalog to draw objects from, and the names of the observing bands are also specified here. See here for more details.
2. Load Catalog (load_catalog): Reads the input catalog file. This step includes an option to input user-defined selection criteria.
3. Make blend catalog (create_blend_generator): Samples objects from the input catalog based on a user defined sampling function to create a catalog with parameters of each blend. This step outputs a generator that yields a new set of catalogs each time it is run with next(). This notebook shows several examples of user input sampling functions to create different blend catalogs.
4. Make observing conditions (create_observing_generator): Creates a class that contains information about the observing conditions such as PSF definition, noise level, etc. The default is to use the full-depth values corresponding to the survey named in config. However, a user can define a function to generate class with observing conditions of their choice. The user function can be such that it varies the observing conditions every time it’s called. This notebook shows an example of a such a user input function that generates different observing conditions. Note that all blends drawn in a batch will be generated with the same observing conditions.
5. Draw blends (create_blend_generator): Simulates scene of overlapping objects, convolved by the PSF and with pixel noise (option set in config). Scene image is generated in each observing band. An “isolated” image of each object is also drawn without pixel contributions from other objects, in each band.
6. Detection/Deblending/Measure (measure): A user defined class to perform detection/deblending/measurement goes here. btk does not include any default algorithm; rather, it provides a framework for the user to run their choice of algorithm for the images generated in create_blend_generator. This notebook contains examples of running btk with SEP (SourceExtractor with python) , LSST science pipeline and SCARLET.
7. Compute metrics (metrics): compares the true centroids, shapes, and flux values to those predicted by the user-provided measure algorithm. Currently, metrics assesses only detection performance by returning the number of objects correctly detected, the number that are undetected and the number of spurious detections. This notebook shows how this can be done.

BlendingToolKit can be run end-to-end using an input yaml config file, parsed by btk_input.py, which then runs btk with the defined parameters. This is shown in detail in the tutorial notebook.

Utils

btk/utils.py contains functions that the user may find useful in creating functions to perform detection/deblending/measurement in measure. For example, it shows how a class derived from measure.Measurement_params can be defined by the user for use with SEP, the LSST science pipeline or stand-alone SCARLET; see point 6 above.

Tutorials

The following jupyter notebooks are included in the notebooks/ directory:

Run basic btk (run_basic.ipynb).

This notebook shows how btk can be used to generate images of multi-band blend scenes, along with isolated object images – i.e., PSF-convolved object images are drawn both in isolation and in the blend scene for each band. The blend scenes are drawn with and without pixel noise.

The notebook also shows examples of performing:

• detection with SEP, lsst science pipeline,
• deblending with scarlet,
• segmentation with SEP.

Multi-band images are plotted using functions defined in btk.plot_utils

Run btk with user-input custom functions (custom_sampling_function.ipynb).

btk generates postage stamp images of blend scenes from an input catalog. How a particular scene is sampled from this catalog is defined in a function input to btk.create_blend_generator.generate. This notebook demonstrates how users can define their own sampling function to draw blend image scenes.

Also shown is an example of how a user-defined custom function can be used to generate different observing conditions. This enables on-the-fly generation of blend scene images with different noise levels and observing PSFs.

Evaluate detection metrics with btk (detection_metrics.ipynb).

This notebook shows how to test the performance of different detection algorithms for a test set size of 100 blend scenes. Detected centroids are compared to true centers to ascertain if a source was detected or not. A detection efficiency matrix is computed that shows the fraction of detected objects for different number of objects in the blend scene. Also plotted are histograms of fraction of objects that were detected as a function of intrinsic galaxy parameters.

Run btk with an input config file (with_config_file_input.ipynb).

This notebook shows how to run btk with an input config yaml file. The input yaml config file contains information on how to simulate the blend scene, which detection/deblending/measurement algorithm to run and where to save the outputs. The config file is parsed by btk_input.py which then runs btk with the defined parameters.

The tutorial shows how to run btk_input.py with an example config file (input/example-config.yaml) for three types of simulations:

1. Two-galaxy blends sampled randomly from CatSim galaxies
2. Up to 10 galaxy blends sampled randomly from CatSim galaxies
3. Blends defined as galaxy “groups” from a pre-processed wld output

Modules API Reference

btk package

Module contents

Toolkit for fast simulation and analysis of overlapping objects for the LSST Dark Energy Science Collaboration.

The code generates on the fly images of overlapping parametric galaxies, while providing a framework to test user defined detection/deblending/measurement algorithms.

Submodules

btk.config module

btk.get_input_catalog module

btk.create_blend_generator module

Contains class BlendGenerator to combine entries from a given catalog into blends.

class btk.create_blend_generator.BlendGenerator(catalog, sampling_function, batch_size=8, shifts=None, indexes=None, verbose=False)

Bases: object

btk.create_observing_generator module

btk.draw_blends module

btk.measure module