btk.deblend module

This method implements deblending algorithms to be used within the BTK framework.

Additional deblending algorithms can be implemented following the same structure as the ones already implemented. Feel free to contact the BTK team if you need help or if you would like to add your deblender to the main BTK repository.

Contains the Deblender classes and its subclasses.

class btk.deblend.DeblendGenerator(deblenders: List[Deblender] | Deblender, draw_blend_generator: DrawBlendsGenerator, njobs: int = 1, verbose: bool = False)

Bases: object

Run one or more deblenders on the batches from the given draw_blend_generator.

__init__(deblenders: List[Deblender] | Deblender, draw_blend_generator: DrawBlendsGenerator, njobs: int = 1, verbose: bool = False)

Initialize deblender generator.

Parameters:

  • deblenders – Deblender or a list of Deblender that will be used on the outputs of the draw_blend_generator.

  • draw_blend_generator – Instance of subclasses of DrawBlendsGenerator.

  • njobs – The number of parallel processes to run [Default: 1].

  • verbose – Whether to print information about deblending.

class btk.deblend.Deblender(max_n_sources: int)

Bases: ABC

Abstract base class containing the deblender class for BTK.

Each new deblender class should be a subclass of Deblender.

__call__(blend_batch: BlendBatch, njobs: int = 1, **kwargs) → DeblendBatch

Calls the (user-implemented) deblend method along with validation of the input.

Parameters:

  • ii – The index of the example in the batch.

  • blend_batch – Instance of BlendBatch class.

  • njobs – Number of processes to use.

  • kwargs – Additional arguments to pass to deblender call.

Returns:

Instance of DeblendedExample class.

__init__(max_n_sources: int) → None

Initialize the Deblender class.

Parameters:

max_n_sources – Maximum number of sources returned by the deblender.

batch_call(blend_batch: BlendBatch, njobs: int = 1, **kwargs) → DeblendBatch

Implements the call of the deblender on the entire batch.

Overwrite this function if you perform measurments on the batch. The default fucntionality is to use multiprocessing to speed up the iteration over all examples in the batch.

Parameters:

  • blend_batch – Instance of BlendBatch class

  • njobs – Number of jobs to paralelize across

  • kwargs – Additional keyword arguments to pass to each deblend call.

Returns:

Instance of DeblendedBatch class

abstract deblend(ii: int, blend_batch: BlendBatch) → DeblendExample

Runs the deblender on the ii-th example of a given batch.

This method should be overwritten by the user if a new deblender is implemented.

Parameters:

  • ii – The index of the example in the batch.

  • blend_batch – Instance of BlendBatch class

Returns:

Instance of DeblendedExample class

class btk.deblend.MultiResolutionDeblender(max_n_sources: int, survey_names: list | tuple)

Bases: ABC

Abstract base class for deblenders using multiresolution images.

__call__(ii: int, mr_batch: MultiResolutionBlendBatch, njobs: int = 1) → DeblendBatch

Calls the (user-implemented) deblend method along with validation of the input.

Parameters:

  • ii – The index of the example in the batch.

  • mr_batch – Instance of MultiResolutionBlendBatch class

  • njobs – Number of processes to use.

Returns:

Instance of DeblendedExample class

__init__(max_n_sources: int, survey_names: list | tuple) → None

Initialize the multiresolution deblender.

batch_call(mr_batch: MultiResolutionBlendBatch, njobs: int = 1) → DeblendBatch

Implements the call of the deblender on the entire batch.

Overwrite this function if you perform measurments on a batch. The default fucntionality is to use multiprocessing to speed up the iteration over all examples in the batch.

Parameters:

  • mr_batch – Instance of MultiResolutionBlendBatch class

  • njobs – Number of njobs to paralelize across

Returns:

Instance of DeblendedBatch class

abstract deblend(ii: int, mr_batch: MultiResolutionBlendBatch) → DeblendExample

Runs the MR deblender on the ii-th example of a given batch.

This method should be overwritten by the user if a new deblender is implemented.

Parameters:

  • ii – The index of the example in the batch.

  • mr_batch – Instance of MultiResolutionBlendBatch class

Returns:

Instance of DeblendedExample class

class btk.deblend.PeakLocalMax(max_n_sources: int, sky_level: float, threshold_scale: int = 5, min_distance: int = 2, use_mean: bool = False, use_band: int | None = None)

Bases: Deblender

This class detects centroids with skimage.feature.peak_local_max.

The function performs detection and deblending of the sources based on the provided band index. If use_mean feature is used, then the Deblender will use the average of all the bands.

__init__(max_n_sources: int, sky_level: float, threshold_scale: int = 5, min_distance: int = 2, use_mean: bool = False, use_band: int | None = None) → None

Initializes Deblender class. Exactly one of ‘use_mean’ or ‘use_band’ must be specified.

Parameters:

  • max_n_sources – See parent class.

  • sky_level – Background intensity in images to be detected (assumed constant).

  • threshold_scale – Minimum number of sigmas above noise level for detections.

  • min_distance – Minimum distance in pixels between two peaks.

  • use_mean – Flag to use the band average for deblending.

  • use_band – Integer index of the band to use for deblending

deblend(ii: int, blend_batch: BlendBatch) → DeblendExample

Performs deblending on the ii-th example from the batch.

class btk.deblend.Scarlet(max_n_sources: int, thresh: float = 1.0, e_rel: float = 1e-05, max_iter: int = 200, max_components: int = 2, min_snr: float = 50)

Bases: Deblender

Implementation of the scarlet deblender.

__init__(max_n_sources: int, thresh: float = 1.0, e_rel: float = 1e-05, max_iter: int = 200, max_components: int = 2, min_snr: float = 50)

Initialize the Scarlet deblender class.

This class uses the scarlet deblender to deblend the images. We follow the basic implementation that is layed out in the Scarlet documentation: https://pmelchior.github.io/scarlet/0-quickstart.html. For more details on each of the argument also see the Scarlet API at: https://pmelchior.github.io/scarlet/api/scarlet.initialization.html.

Note that as of commit 45187fd, Scarlet raises a LinAlg error if two sources are on the same pixel, which is allowed by the majority of currently implemented sampling functions in BTK. To get around this, our Deblender implementation automatically catches this exception and outputs an array of zeroes for the deblended images of the particular blend that caused this exception. See this issue for details: https://github.com/pmelchior/scarlet/issues/282#issuecomment-2074886534

Parameters:

  • max_n_sources – See parent class.

  • thresh – Multiple of the backround RMS used as a flux cutoff for morphology initialization for scarlet.source.ExtendedSource class. (Default: 1.0)

  • e_rel – Relative error for convergence of the loss function See scarlet.blend.Blend.fit method for details. (Default: 1e-5)

  • max_iter – Maximum number of iterations for the optimization (Default: 200)

  • min_snr – Mininmum SNR per component to accept the source. (Default: 50)

  • max_components – Maximum number of components in a source. (Default: 2)

deblend(ii: int, blend_batch: BlendBatch, reference_catalogs: Table | None = None) → DeblendExample

Performs deblending on the ii-th example from the batch.

Parameters:

  • ii – The index of the example in the batch.

  • blend_batch – Instance of BlendBatch class.

  • reference_catalogs – Reference catalog to use for deblending. If None, the truth catalog is used.

Returns:

Instance of DeblendedExample class.

class btk.deblend.SepMultiBand(max_n_sources: int, matching_threshold: float = 1.0, thresh: float = 1.5)

Bases: Deblender

This class returns centers detected with SEP by combining predictions in different bands.

For each band in the input image we run sep for detection and append new detections to a running list of detected coordinates. In order to avoid repeating detections, we run a KD-Tree algorithm to calculate the angular distance between each new coordinate and its closest neighbour. Then we discard those new coordinates that were closer than matching_threshold to any one of already detected coordinates.

__init__(max_n_sources: int, matching_threshold: float = 1.0, thresh: float = 1.5)

Initialize the SepMultiBand Deblender.

Parameters:

  • max_n_sources – See parent class.

  • matching_threshold – Threshold value for match detections that are close (arcsecs).

  • thresh – See SepSingleBand class.

deblend(ii: int, blend_batch: BlendBatch) → DeblendExample

Performs deblending on the ii-th example from the batch.

class btk.deblend.SepSingleBand(max_n_sources: int, thresh: float = 1.5, min_area: int = 5, use_mean: bool = False, use_band: int | None = None)

Bases: Deblender

Return detection, segmentation and deblending information running SEP on a single band.

The function performs detection and deblending of the sources based on the provided band index. If use_mean feature is used, then we use the average of all the bands.

For more details on SEP (Source-Extractor Python), see: https://sep.readthedocs.io/en/v1.1.x/index.html#

__init__(max_n_sources: int, thresh: float = 1.5, min_area: int = 5, use_mean: bool = False, use_band: int | None = None) → None

Initializes Deblender class. Exactly one of ‘use_mean’ or ‘use_band’ must be specified.

Parameters:

  • max_n_sources – See parent class.

  • thresh – Threshold pixel value for detection use in sep.extract. This is interpreted as a relative threshold: the absolute threshold at pixel (j, i) will be thresh * err[j, i] where err is set to the global rms of the background measured by SEP.

  • min_area – Minimum number of pixels required for an object. Default is 5.

  • use_mean – Flag to use the band average for deblending.

  • use_band – Integer index of the band to use for deblending.

deblend(ii: int, blend_batch: BlendBatch) → DeblendExample

Performs deblending on the i-th example from the batch.