btk.measure module

File containing measurement infrastructure for the BlendingToolKit.

Contains examples of functions that can be used to apply a measurement algorithm to the blends simulated by BTK. Every measurement function should have the following skeleton:

def measure_function(batch, idx, **kwargs):
    # do some measurements on the images contained in batch.
    return output

where batch is the output from the DrawBlendsGenerator object (see its __next__ method) and idx is the index corresponding to which image in the batch to measure. The additional keyword arguments **kwargs can be passed via the measure_kwargs dictionary argument in the MeasureGenerator initialize which are shared among all the measurement functions.

It should return a dictionary containing a subset of the following keys/values (note the key catalog` is mandatory):

  • catalog (astropy.table.Table): An astropy table containing measurement information. The len of the table should be n_objects. If your DrawBlendsGenerator uses a single survey, the following column names are required:

    • x_peak: horizontal centroid position in pixels.

    • y_peak: vertical centroid position in pixels.

    For multiple surveys (multi-resolution), we instead require:

    • ra: object centroid right ascension in arcseconds, following the convention from the wcs object included in the input batch.

    • dec: vertical centroid position in arcseconds, following the convention from the wcs object included in the input batch.

  • deblended_image (np.ndarray): Array of deblended isolated images with shape: (n_objects, n_bands, stamp_size, stamp_size) or (n_objects, stamp_size, stamp_size, n_bands) depending on convention. The order of this array should correspond to the order in the returned catalog. Where n_objects is the number of detected objects by the algorithm. If you are using the multiresolution feature, you should instead return a dictionary with a key for each survey containing the aforementioned array.

  • segmentation (np.ndarray): Array of booleans with shape (n_objects,stamp_size,stamp_size) The pixels set to True in the i-th channel correspond to the i-th object. The order should correspond to the order in the returned catalog. If you are using the multiresolution feature, you should instead return a dictionary with a key for each survey containing the aforementioned array.

Omitted keys in the returned dictionary are automatically assigned a None value (except for catalog which is a mandatory entry).

class btk.measure.MeasureGenerator(measure_functions, draw_blend_generator, cpus=1, verbose=False, measure_kwargs: List[dict] | None = None, save_path=None)

Bases: object

Generates output of deblender and measurement algorithm.

__init__(measure_functions, draw_blend_generator, cpus=1, verbose=False, measure_kwargs: List[dict] | None = None, save_path=None)

Initialize measurement generator.

Parameters:

  • measure_functions – Function or list of functions that returns a dict with measurements given output from the draw_blend_generator.

  • draw_blend_generator – Generator that outputs dict with blended images, isolated images, blend catalog, wcs info, and psf.

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

  • verbose (bool) – Whether to print information about measurement.

  • measure_kwargs (list) – List of dictionaries containing keyword arguments to be passed in to each of the measure_functions. Each dictionnary is passed one time to each function, meaning that each function which be ran as many times as there are different dictionnaries.

  • save_path (str) – Path to a directory where results will be saved. If left as None, results will not be saved.

run_batch(batch, index, **kwargs)

Perform measurements on a single blend.

btk.measure.add_pixel_columns(catalog, wcs)

Uses the wcs to add a column to the catalog corresponding to pixel coordinates.

The catalog must contain ra and dec columns.

Parameters:

  • catalog (astropy.table.Table) – Catalog to modify.

  • wcs (astropy.wcs.WCS) – WCS corresponding to the wanted transformation.

btk.measure.basic_measure(batch, idx, channels_last=False, surveys=None, is_multiresolution=False, **kwargs)

Return centers detected with skimage.feature.peak_local_max.

For each potentially multi-band image, an average over the bands is taken before measurement. NOTE: If this function is used with the multiresolution feature, measurements will be carried on the first survey.

Parameters:

  • batch (dict) – Output of DrawBlendsGenerator object’s __next__ method.

  • idx (int) – Index number of blend scene in the batch to preform measurement on.

Returns:

dict containing catalog with entries corresponding to measured peaks.

btk.measure.sep_multiband_measure(batch, idx, channels_last=False, surveys=None, matching_threshold=1.0, sigma_noise=1.5, is_multiresolution=False, **kwargs)

Returns centers detected with source extractor 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.

NOTE: If this function is used with the multiresolution feature, measurements will be carried on the first survey.

Parameters:

  • batch (dict) – Output of DrawBlendsGenerator object’s __next__ method.

  • idx (int) – Index number of blend scene in the batch to preform measurement on.

  • sigma_noise (float) – Sigma threshold for detection against noise.

  • matching_threshold (float) – Match centers of objects that are closer than this threshold to a single prediction (in arseconds).

Returns:

dict containing catalog with entries corresponding to measured peaks.

btk.measure.sep_singleband_measure(batch, idx, meas_band_num=3, use_mean=False, channels_last=False, surveys=None, sigma_noise=1.5, is_multiresolution=False, **kwargs)

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 the measurement function is using the average of all the bands.

NOTE: If this function is used with the multiresolution feature, measurements will be carried on the first survey, and deblended images or segmentations will not be returned.

Parameters:

  • batch (dict) – Output of DrawBlendsGenerator object’s __next__ method.

  • idx (int) – Index number of blend scene in the batch to preform measurement on.

  • meas_band_num (int) – Indicates the index of band to use fo the measurement

  • use_mean (bool) – If True, then algorithm uses the average of all the bands

  • sigma_noise (float) – Sigma threshold for detection against noise.

Returns:

dict with the centers of sources detected by SEP detection algorithm.