flint.masking¶

Utility functions to make image based masks from images, with the initial thought being towards FITS images.

Classes¶

`MaskingOptions`	Contains options for the creation of clean masks from some subject
`SkewResult`

Functions¶

`_adaptive_minimum_absolute_clip`(→ numpy.ndarray)
`_create_signal_from_rmsbkg`(→ numpy.ndarray)
`_get_signal_image`(→ numpy.ndarray)
`_minimum_absolute_clip`(→ numpy.ndarray)	Given an input image or signal array, construct a simple image mask by applying a
`_need_to_make_signal`(→ bool)	Isolated functions to consider whether a signal image is needed
`_verify_set_positive_seed_clip`(→ float)	Ensure that the positive seed clip is handled appropriately
`beam_shape_erode`(...)	Construct a kernel representing the shape of the restoring beam at
`cli`()
`consider_beam_mask_round`(→ bool)	Evaluate whether a self-calibration round should have a beam clean mask
`convolve_image_by_scale`(...)	Generate a convolved version of the input image based on some convolved scale.
`create_beam_mask_kernel`(→ numpy.ndarray)	Make a mask using the shape of a beam in a FITS Header object. The
`create_boxcar_skew_mask`(→ numpy.ndarray)
`create_convolved_erosion_mask`(→ flint.naming.FITSMaskNames)	Create a per-scale clean mask by smoothing the input image to some scale, and then
`create_multi_scale_erosion`(...)	Specialised encode per-scale clean masks as bitmapped per-pixel integer values.
`create_snr_mask_from_fits`(→ flint.naming.FITSMaskNames)	Create a mask for an input FITS image based on a signal to noise given a corresponding pair of RMS and background FITS images.
`extract_beam_mask_from_mosaic`(→ flint.naming.FITSMaskNames)	Extract a region based on an existing FITS image from a masked FITS
`fft_binary_erosion`(→ numpy.typing.NDArray[numpy.bool])	Attempt to perform a binary erosion using convolution therom. FFT
`get_parser`(→ argparse.ArgumentParser)
`grow_low_snr_mask`(→ numpy.ndarray)	There may be cases where normal thresholding operations based on simple pixel-wise SNR
`minimum_absolute_clip`(→ numpy.ndarray)	Implements minimum absolute clip method. A minimum filter of a particular
`reverse_negative_flood_fill`(→ numpy.ndarray)	Attempt to:

Module Contents¶

class flint.masking.MaskingOptions(/, **data: Any)[source]¶

Bases: flint.options.BaseOptions

Contains options for the creation of clean masks from some subject image. Clipping levels specified are in units of RMS (or sigma). They are NOT in absolute units.

base_snr_clip: float = 4[source]¶: A base clipping level to be used should other options not be activated

beam_shape_erode: bool = False[source]¶: Erode the mask using the shape of the restoring beam

beam_shape_erode_minimum_response: float = 0.6[source]¶: The minimum response of the beam that is used to form the erode structure shape

beam_shape_erode_scales: tuple[int, Ellipsis] | None = None[source]¶: The multi-scale convolution sizes, in pixels, to perform a binary erosion with. Output scales are encoded as a bitmapped value (e.g. n’th scale is n’th bit)

convolve_first: bool = False[source]¶: Attempt to construct mask across scales by first convolving the input image by a scale kernel, then run the island construction stage

flood_fill: bool = False[source]¶: Whether to attempt to flood fill when constructing a mask. This should be True for grow_low_snr_islands and suppress_artefacts to have an effect.

flood_fill_positive_flood_clip: float = 1.5[source]¶: Clipping level used to grow seeded islands down to

flood_fill_positive_seed_clip: float = 4.5[source]¶: The clipping level to seed islands that will be grown to lower signal metric

flood_fill_use_mac: bool = False[source]¶: If True, the clipping levels are used as the increase_factor when using a minimum absolute clip

flood_fill_use_mac_adaptive_max_depth: int | None = None[source]¶: Determines the number of adaptive boxcar scales to use when constructing seed mask. If None no adaptive boxcar sizes

flood_fill_use_mac_adaptive_skew_delta: float = 0.2[source]¶: A box is consider too small for a pixel if the fractional proportion of positive pixels is larger than the deviation away of (0.5 + frac). This threshold is therefore 0 to 0.5

flood_fill_use_mac_adaptive_step_factor: float = 2.0[source]¶: Stepping size used to increase box by should adaptive detect poor boxcar statistics

flood_fill_use_mac_box_size: int = 75[source]¶: The size of the mac box size should mac be used

grow_low_snr_island: bool = False[source]¶: Whether to attempt to grow a mask to capture islands of low SNR (e.g. diffuse emission)

grow_low_snr_island_clip: float = 1.75[source]¶: The minimum significance levels of pixels to be to seed low SNR islands for consideration

grow_low_snr_island_size: int = 768[source]¶: The number of pixels an island has to be for it to be accepted

class flint.masking.SkewResult[source]¶

Bases: NamedTuple

box_size: int[source]¶: Size of the boxcar window applies

positive_pixel_frac: numpy.ndarray[source]¶: The fraction of positive pixels in a boxcar function

skew_delta: float[source]¶: The test threshold for skew

skew_mask: numpy.ndarray[source]¶: Mask of pixel positions indicating which positions failed the skew test

flint.masking._adaptive_minimum_absolute_clip(image: numpy.ndarray, increase_factor: float = 2.0, box_size: int = 100, adaptive_max_depth: int = 3, adaptive_box_step: float = 2.0, adaptive_skew_delta: float = 0.2) → numpy.ndarray[source]¶

flint.masking._create_signal_from_rmsbkg(image: pathlib.Path | numpy.ndarray, rms: pathlib.Path | numpy.ndarray, bkg: pathlib.Path | numpy.ndarray) → numpy.ndarray[source]¶

flint.masking._get_signal_image(image: numpy.ndarray | None = None, rms: numpy.ndarray | None = None, background: numpy.ndarray | None = None, signal: numpy.ndarray | None = None) → numpy.ndarray[source]¶

flint.masking._minimum_absolute_clip(image: numpy.ndarray, increase_factor: float = 2.0, box_size: int = 100) → numpy.ndarray[source]¶

Given an input image or signal array, construct a simple image mask by applying a rolling boxcar minimum filter, and then selecting pixels above a cut of the absolute value value scaled by increase_factor. This is a pixel-wise operation.

Parameters:

image (np.ndarray) – The input array to consider
increase_factor (float, optional) – How large to scale the absolute minimum by. Defaults to 2.0.
box_size (int, optional) – Size of the rolling boxcar minimum filtr. Defaults to 100.

Returns:

The mask of pixels above the locally varying threshold

Return type:

np.ndarray

flint.masking._need_to_make_signal(masking_options: MaskingOptions) → bool[source]¶: Isolated functions to consider whether a signal image is needed

flint.masking._verify_set_positive_seed_clip(positive_seed_clip: float, signal: numpy.ndarray) → float[source]¶: Ensure that the positive seed clip is handled appropriately

flint.masking.beam_shape_erode(mask: numpy.ndarray, fits_header: astropy.io.fits.Header, minimum_response: float = 0.6, scales: list[int] | tuple[int, Ellipsis] | None = None) → numpy.typing.NDArray[numpy.bool] | numpy.typing.NDArray[numpy.int32][source]¶

Construct a kernel representing the shape of the restoring beam at

a particular level, and use it as the basis of a binary erosion of the input mask.

The fits_header is used to construct the beam shape that matches the same pixel size

The scales parameters outlines the scales being used to clean at during some multi-scale deconvolution algorithm. If provided the binary eroision is carried out at each scale (the beam is convolved by a circular gaussian at this scale). The outputs are stored as a bitmask per pixel where the n’th scales is stored as the n’th bit.

Args:: mask (np.ndarray): The current mask that will be eroded based on the beam shape fits_header (fits.Header): The fits header of the mask used to generate the beam kernel shape minimum_response (float, optional): The minimum response of the main restoring beam to craft the shape from. Defaults to 0.6. scales (list[int] | tuple[int, …] | None, optional): Defines the scales that are being used during multi-scale clean. Perform the beam erosion at each of these scales. Defaults to None.

Returns:

NDArray[np.bool] | NDArray[np.int32]: The eroded beam shape. If a no/single scale provide it is a bool return, otherwise int32.

flint.masking.cli()[source]¶

flint.masking.consider_beam_mask_round(current_round: int, mask_rounds: str | Collection[int] | int, allow_beam_masks: bool = True) → bool[source]¶

Evaluate whether a self-calibration round should have a beam clean mask constructed. Rules are:

if mask_rounds is a string and is “all”, all rounds will have a beam mask
if ‘mask_rounds’ is a single integer, so long as current_round is larger it will have a beam mask
if mask_rounds is iterable and contains current_round it will have a beam mask
if allow_beam_masks is False a False is returned. Otherwise options above are considered.

Parameters:

current_round (int) – The current self-calibration round that is being performed
mask_rounds (Union[str, Collection[int], int]) – The rules to consider whether a beam mask is needed
allow_beam_masks (bool, optional) – A global allow / deny. This should be True for other rules to be considered. Defaults to True.

Returns:

Whether per beam mask should be performed

Return type:

bool

flint.masking.convolve_image_by_scale(image_data: numpy.typing.NDArray[numpy.floating], scale: int) → numpy.typing.NDArray[numpy.floating][source]¶

Generate a convolved version of the input image based on some convolved scale. Note that here the scale refers to the scales used by wsclean. Per the multiscale documentation, where considering gaussians:

>> fwhm = 0.45 * scale

Also not that:

>> fwhm = 2.355 * sigma

Parameters:

image_data (NDArray[np.floating]) – The imaged to be convolved
scale (int) – The pixel scale to smooth with

Returns:

Smoother version of the input image

Return type:

NDArray[np.floating]

flint.masking.create_beam_mask_kernel(fits_header: astropy.io.fits.Header, kernel_size: int | tuple[int, int] = 100, minimum_response: float = 0.6, pixel_scale: int | None = None, auto_resize: bool = True) → numpy.ndarray[source]¶

Make a mask using the shape of a beam in a FITS Header object. The beam properties in the ehader are used to generate the two-dimensional Gaussian main lobe, from which a cut is made based on the minimum power.

Parameters:

fits_header (fits.Header) – The FITS header to create beam from
kernel_size (int | tuple[int, int], optional) – Size of the output kernel in pixels. Will be a square. Defaults to 100.
minimum_response (float, optional) – Minimum response of the beam shape for the mask to be constructed from. Defaults to 0.6.
pixel_scale (int | None, optional) – Convolve the restoring beam by this scale. The input scale is in pixel units. Defaults to None.
auto_resize (bool, optional) – If True and the kernel is evaluated to all 1’s, enlarge the kernel_size by a factor of 2. Defaults to True.

Raises:

KeyError – Raised if CDELT1 and CDELT2 missing

Returns:

Boolean mask of the kernel shape

Return type:

np.ndarray

flint.masking.create_boxcar_skew_mask(image: numpy.ndarray, skew_delta: float, box_size: int) → numpy.ndarray[source]¶

flint.masking.create_convolved_erosion_mask(fits_image_path: pathlib.Path, masking_options: MaskingOptions) → flint.naming.FITSMaskNames[source]¶

Create a per-scale clean mask by smoothing the input image to some scale, and then applying a reverse flood fill with the minimum absolute clip statistic. After the initial mask per scale is constructed a binary erosion is then performed to further refine the mask.

Parameters:

fits_image_path (Path) – The path to the FITS image to load.
masking_options (MaskingOptions) – Options to use throughout the convolve and erosion process.

Returns:

Clean mask written to a FITS file. Should multiple scales be specified they are encoded bitwise per pixel.

Return type:

FITSMaskNames

flint.masking.create_multi_scale_erosion(mask: numpy.typing.NDArray[numpy.bool], fits_header: astropy.io.fits.Header, scale: int, minimum_response: float = 0.6) → numpy.typing.NDArray[numpy.int32][source]¶

Specialised encode per-scale clean masks as bitmapped per-pixel integer values.

Parameters:

mask (np.ndarray) – The current mask that will be eroded based on the beam shape
fits_header (fits.Header) – The fits header of the mask used to generate the beam kernel shape
scales (list[int] | None, optional) – Defines the scales that are being used during multi-scale clean. Perform the beam erosion at each of these scales. Defaults to None.
minimum_response (float, optional) – The minimum response of the main restoring beam to craft the shape from. Defaults to 0.6.

Returns:

_description_

Return type:

NDArray[np.int32]

flint.masking.create_snr_mask_from_fits(fits_image_path: pathlib.Path, masking_options: MaskingOptions, fits_rms_path: pathlib.Path | None, fits_bkg_path: pathlib.Path | None, create_signal_fits: bool = False, overwrite: bool = True) → flint.naming.FITSMaskNames[source]¶

Create a mask for an input FITS image based on a signal to noise given a corresponding pair of RMS and background FITS images.

Internally should a signal image be needed it is computed as something akin to: > signal = (image - background) / rms

This is done in a staged manner to minimise the number of (potentially large) images held in memory.

Each of the input images needs to share the same shape. This means that compression features offered by some tooling (e.g. BANE –compress) can not be used.

Depending on the MaksingOptions used the signal image may not be needed.

Once the signal map as been computed, all pixels below min_snr are flagged.

Parameters:

fits_image_path (Path) – Path to the FITS file containing an image
masking_options (MaskingOptions) – Configurables on the masking operation procedure.
fits_rms_path (Optional[Path], optional) – Path to the FITS file with an RMS image corresponding to fits_image_path. Defaults to None.
fits_bkg_path (Optional[Path], optional) – Path to the FITS file with an background image corresponding to fits_image_path. Defaults to None.
create_signal_fits (bool, optional) – Create an output signal map. Defaults to False.
overwrite (bool) – Passed to fits.writeto, and will overwrite files should they exist. Defaults to True.

Returns:

Container describing the signal and mask FITS image paths. If create_signal_path is None, then the signal_fits attribute will be None.

Return type:

FITSMaskNames

flint.masking.extract_beam_mask_from_mosaic(fits_beam_image_path: pathlib.Path, fits_mosaic_mask_names: flint.naming.FITSMaskNames) → flint.naming.FITSMaskNames[source]¶

Extract a region based on an existing FITS image from a masked FITS image. Here a masked FITS image is intended to be one created by create_snr_mask_from_fits.

A simple cutout (e.g. CutOut2D) might not work as intended, as when creating the field image (the intended use case here) might be regridded onto a unique pixel grid that does not correspond to one that would be constructed by wsclean.

Parameters:

fits_beam_image_path (Path) – The template image with a valid WCS. This region is used to extract the masked region
fits_mosaic_mask_names (FITSMaskNames) – The previously masked image

Returns:

_description_

Return type:

FITSMaskNames

flint.masking.fft_binary_erosion(mask: numpy.typing.NDArray[numpy.bool] | numpy.typing.NDArray[numpy.floating], kernel: numpy.typing.NDArray[numpy.bool]) → numpy.typing.NDArray[numpy.bool][source]¶

Attempt to perform a binary erosion using convolution therom. FFT the input mask, FFT the input kernel, multiply, FFT the result. This would give the running sum of the kernel moved across the image, which in the case of boolean-type values will be the number of overlapping 1’s.

The returned mask is after ensuring the kernel total sum matches the running sum.

Parameters:

mask (NDArray[np.bool] | NDArray[np.floating]) – The mask that will be eroded
kernel (NDArray[np.bool]) – The kernel structure used for the erosion

Returns:

The eroded mask

Return type:

NDArray[np.bool]

flint.masking.get_parser() → argparse.ArgumentParser[source]¶

flint.masking.grow_low_snr_mask(image: numpy.ndarray | None = None, rms: numpy.ndarray | None = None, background: numpy.ndarray | None = None, signal: numpy.ndarray | None = None, grow_low_snr: float = 2.0, grow_low_island_size: int = 512, region_mask: numpy.ndarray | None = None) → numpy.ndarray[source]¶

There may be cases where normal thresholding operations based on simple pixel-wise SNR cuts fail to pick up diffuse, low surface brightness regions of emission. When some type of masking operation is used there may be instances where these regions are never cleaned.

Sometimes smoothing can help to pick up these features, but when attempting to pass such a mask through to the imagery of choice the islands may be larger than the features at their native resolution, unless some other more sophisticated filtering is performed.

This function attempts to grow masks to capture islands of contiguous pixels above a low SNR cut that would otherwise go uncleaned.

Parameters:: Args – image (Optional[np.ndarray], optional): The total intensity pixels to have the mask for. Defaults to None. rms (Optional[np.ndarray], optional): The noise across the image. Defaults to None. background (Optional[np.ndarray], optional): The background acros the image. If None, zeros are assumed. Defaults to None. signal(Optional[np.ndarray], optional): A signal map. Defaults to None. grow_low_snr (float, optional): The SNR pixekls have to be above. Defaults to 2. grow_low_island_size (int, optional): The minimum number of pixels an island should be for it to be considered valid. Defaults to 512. region_mask (Optional[np.ndarray], optional): Whether some region should be masked out before the island size constraint is applied. Defaults to None.
Returns:: The derived mask of objects with low-surface brightness
Return type:: np.ndarray

flint.masking.minimum_absolute_clip(image: numpy.ndarray, increase_factor: float = 2.0, box_size: int = 100, adaptive_max_depth: int | None = None, adaptive_box_step: float = 2.0, adaptive_skew_delta: float = 0.2) → numpy.ndarray[source]¶

Implements minimum absolute clip method. A minimum filter of a particular boxc size is applied to the input image. The absolute of the output is taken and increased by a guard factor, which forms the clipping level used to construct a clean mask:

>>> image > (absolute(minimum_filter(image, box)) * factor)

The idea is only valid for zero mean and normally distributed pixels, with positive definite flux, making it appropriate for Stokes I.

Larger box sizes and guard factors will make the mask more conservative. Should the boxcar be too small relative to some feature it is aligned it is possible that an excess of positive pixels will produce an less than optimal clipping level. An adaptive box size mode, if activated, attempts to use a larger box around these regions.

The basic idea being detecting regions where the boxcar is too small is around the idea that there should be a similar number of positive to negative pixels. Should there be too many positive pixels in a region it is likely there is an

Parameters:

image (np.ndarray) – Image to create a mask for
increase_factor (float, optional) – The guard factor used to inflate the absolute of the minimum filter. Defaults to 2.0.
box_size (int, optional) – Size of the box car of the minimum filter. Defaults to 100.
adaptive_max_depth (Optional[int], optional) – The maximum number of rounds that the adaptive mode is allowed to perform when rescaling boxcar results in certain directions. Defaults to None.
adaptive_box_step (float, optional) – A multiplicative factor to increase the boxcar size by each round. Defaults to 2.0.
adaptive_skew_delta (float, optional) – Minimum deviation from 0.5 that needs to be met to classify a region as skewed. Defaults to 0.2.

Returns:

Final mask

Return type:

np.ndarray

flint.masking.reverse_negative_flood_fill(base_image: numpy.ndarray, masking_options: MaskingOptions, pixels_per_beam: float | None = None) → numpy.ndarray[source]¶

Attempt to:

seed masks around bright regions of an image and grow them to lower significance thresholds
remove regions of negative and positive islands that surround bright sources.

An initial set of islands (and masks) are constructed by first using the positive_seed_clip to create an initial SNR based mask. These islands then are binary dilated to grow the islands to adjacent pixels at a lower significance level (see scipy.ndimage.binary_dilation).

Next an attempt is made to remove artefacts around bright sources, where there are likely to be positive and negative artefacts that originate from calibration errors, deconvolution errors, or residual structure from an incomplete clean.

This operation will search for islands of _negative_ pixels above a threshold. These pixels are then grown after a guard mask has been constructed around bright pixels.

The assumptions that go into this process:

the no genuine source of negative sky emission
if there are bright negative artefacts there are likely bright positive artefacts nearby
such negative pixels are ~10% level artefacts from a presumed bright sources

Optionally, the grow_low_snr_mask may also be considered via the grow_low_snr and grow_low_island_size parameters.

Parameters:

base_image (np.ndarray) – The base image or signal map that is used throughout the fill procedure.
masking_options (MaskingOptions) – Options to carry out masking.
pixels_per_beam (Optional[float], optional) – The number of pixels that cover a beam. Defaults to None.

Returns:

Mask of the pixels to clean

Return type:

np.ndarray