autolens.Mask2D#

Bases: Mask

A 2D mask, used for masking values which are associated with a a uniform rectangular grid of pixels.

When applied to 2D data with the same shape, values in the mask corresponding to False entries are unmasked and therefore used in subsequent calculations. .

The ``Mask2D`, has in-built functionality which:

Maps data structures between two data representations: slim` (all unmasked False values in a 1D ndarray) and native (all unmasked values in a 2D or 3D ndarray).
Has a Geometry2D object (defined by its (y,x) pixel scales and (y,x) origin) which defines how coordinates are converted from pixel units to scaled units.
Associates Cartesian Grid2D objects of (y,x) coordinates with the data structure (e.g. a (y,x) grid of all unmasked pixels).

A detailed description of the 2D mask API is provided below.

__Slim__

Below is a visual illustration of a Mask2D, where a total of 10 pixels are unmasked (values are False):

x x x x x x x x x x
x x x x x x x x x x     This is an example ``Mask2D``, where:
x x x x x x x x x x
x x x x O O x x x x     x = `True` (Pixel is masked and excluded from the array)
x x x O O O O x x x     O = `False` (Pixel is not masked and included in the array)
x x x O O O O x x x
x x x x x x x x x x
x x x x x x x x x x
x x x x x x x x x x
x x x x x x x x x x

The mask pixel index’s are as follows (the positive / negative direction of the Grid2D objects associated with the mask are also shown on the y and x axes).

<--- -ve  x  +ve -->

 x x x x x x x x x x  ^
 x x x x x x x x x x  I
 x x x x x x x x x x  I
 x x x x 0 1 x x x x +ve
 x x x 2 3 4 5 x x x  y
 x x x 6 7 8 9 x x x -ve
 x x x x x x x x x x  I
 x x x x x x x x x x  I
 x x x x x x x x x x \/
 x x x x x x x x x x

The Mask2D’s slim data representation is an ndarray of shape [total_unmasked_pixels].

For the Mask2D above the slim representation therefore contains 10 entries and two examples of these entries are:

mask[3] = the 4th unmasked pixel's value.
mask[6] = the 7th unmasked pixel's value.

A Cartesian grid of (y,x) coordinates, corresponding to all slim values (e.g. unmasked pixels) is given by:

__native__

Masked data represented as an an ndarray of shape [total_y_values, total_x_values], where all masked entries have values of 0.0.

For the following mask:

x x x x x x x x x x
x x x x x x x x x x     This is an example ``Mask2D``, where:
x x x x x x x x x x
x x x x O O x x x x     x = `True` (Pixel is masked and excluded from the array)
x x x O O O O x x x     O = `False` (Pixel is not masked and included in the array)
x x x O O O O x x x
x x x x x x x x x x
x x x x x x x x x x
x x x x x x x x x x
x x x x x x x x x x

The mask has the following indexes:

<--- -ve  x  +ve -->

 x x x x x x x x x x  ^
 x x x x x x x x x x  I
 x x x x x x x x x x  I
 x x x x 0 1 x x x x +ve
 x x x 2 3 4 5 x x x  y
 x x x 6 7 8 9 x x x -ve
 x x x x x x x x x x  I
 x x x x x x x x x x  I
 x x x x x x x x x x  \/
 x x x x x x x x x x

In the above array:

- mask[0,0] = True (it is masked)
- mask[0,0] = True (it is masked)
- mask[3,3] = True (it is masked)
- mask[3,3] = True (it is masked)
- mask[3,4] = False (not masked)
- mask[3,5] = False (not masked)
- mask[4,5] = False (not masked)

SLIM TO NATIVE MAPPING

The Mask2D has functionality which maps data between the slim and native data representations.

For the example mask above, the 1D ndarray given by derive_indexes.slim_to_native is:

slim_to_native[0] = [3,4]
slim_to_native[1] = [3,5]
slim_to_native[2] = [4,3]
slim_to_native[3] = [4,4]
slim_to_native[4] = [4,5]
slim_to_native[5] = [4,6]
slim_to_native[6] = [5,3]
slim_to_native[7] = [5,4]
slim_to_native[8] = [5,5]
slim_to_native[9] = [5,6]

Parameters:

mask (Union[ndarray, List]) – The ndarray of shape [total_y_pixels, total_x_pixels] containing the bool’s representing the mask, where False signifies an entry is unmasked and used in calculations.
pixel_scales (Union[Tuple[float], Tuple[float, float], float]) – The (y,x) scaled units to pixel units conversion factors of every pixel. If this is input as a float, it is converted to a (float, float) structure.
origin (Tuple[float, float]) – The (y,x) scaled units origin of the mask’s coordinate system.
invert (bool) – If True, the bool’s of the input mask are inverted, so False entries become True and vice versa.
xp – The array module to use (default numpy; pass jax.numpy for JAX support). Controls whether internal index arrays are computed on CPU or GPU.

Methods

`all`
`all_false`	Create a mask where all pixels are False and therefore unmasked.
`astype`
`circular`	Returns a Mask2D (see Mask2D.__new__) where all False entries are within a circle of input radius.
`circular_annular`	Returns a Mask2D (see Mask2D.__new__) where all False entries are within an annulus of input inner radius and outer radius.
`copy`
`elliptical`	Returns a Mask2D (see Mask2D.__new__) where all False entries are within an ellipse.
`elliptical_annular`	Returns a Mask2D (see Mask2D.__new__) where all False entries are within an elliptical annulus of input inner and outer scaled major-axis and centre.
`from_fits`	Load a `Mask2D` from a 2D boolean array stored in a `.fits` file.
`from_pixel_coordinates`	Returns a Mask2D (see Mask2D.__new__) where all False entries are defined from an input list of list of pixel coordinates.
`instance_flatten`	Flatten an instance of an autoarray class into a tuple of its attributes (i.e.. a pytree).
`instance_unflatten`	Unflatten a tuple of attributes (i.e. a pytree) into an instance of an autoarray class.
`invert`
`max`
`min`
`rescaled_from`	Returns the `Mask2D` rescaled to a bigger or small shape via input `rescale_factor`.
`reshape`
`resized_from`	Returns the `Mask2D` resized to a small or bigger `ndarray`, but with the same distribution of
`sqrt`
`sum`
`trimmed_array_from`	Map a padded 1D array of values to its original 2D array, trimming all edge values.
`unmasked_blurred_array_from`	Convolve a padded array with the PSF and trim it back to the original image shape.
`with_new_array`	Copy this object but give it a new array.

Attributes

`array`
`circular_radius`	Returns the radius in scaled units of a circular mask.
`derive_grid`	Returns the `DeriveGrid2D` object associated with the mask, which computes derived grids of (y,x) coordinates such as the unmasked pixel grid, edge grid, and border grid.
`derive_indexes`	Returns the `DeriveIndexes2D` object associated with the mask, which contains derived index arrays used to map data between `slim` (1D unmasked) and `native` (2D full-shape) representations.
`derive_mask`	Returns the `DeriveMask2D` object associated with the mask, which computes derived masks such as the edge mask, border mask, and blurring mask.
`dimensions`	The number of dimensions of the mask (e.g. 1 for a 1D mask, 2 for a 2D mask).
`dtype`
`extent_index_for_masked_pixel`	A property that is only computed once per instance and then replaces itself with an ordinary attribute.
`fft_index_for_masked_pixel`	A property that is only computed once per instance and then replaces itself with an ordinary attribute.
`geometry`	Return the 2D geometry of the mask, representing its uniform rectangular grid of (y,x) coordinates defined by its `shape_native`.
`header_dict`	Returns the pixel scales of the mask as a header dictionary, which can be written to a .fits file.
`imag`
`is_all_false`	Returns True if all pixels in a mask are False (i.e. every pixel is unmasked), else returns False.
`is_all_true`	Returns True if all pixels in a mask are True, else returns False.
`is_circular`	Returns whether the unmasked region of the mask is a filled circular disc.
`is_transformed`
`mask`	The boolean ndarray of the mask, where False entries are unmasked (used in calculations) and True entries are masked (excluded from calculations).
`mask_centre`	The (y,x) scaled coordinate centre of the unmasked pixels in the mask.
`native`	Returns the data structure in its native format which contains all unmaksed values to the native dimensions.
`native_for_slim`	A 2D array of shape [total_unmasked_pixels, 2] that maps every unmasked pixel's slim index to its (y, x) native 2D index.
`ndim`
`pixel_scale`	The pixel scale of the mask as a single float value.
`pixel_scales`
`pixels_in_mask`	The total number of unmasked pixels (values are False) in the mask.
`real`
`shape`
`shape_native`	The 2D shape of the mask in its native representation, equal to the shape of the underlying boolean ndarray.
`shape_native_masked_pixels`	The (y,x) shape corresponding to the extent of unmasked pixels that go vertically and horizontally across the mask.
`shape_slim`	The 1D shape of the mask, which is equivalent to the total number of unmasked pixels in the mask.
`size`
`zoom`	Returns the `Zoom2D` object associated with the mask, which computes the zoomed region of the mask around its unmasked pixels for use in visualization.

property native_for_slim#

A 2D array of shape [total_unmasked_pixels, 2] that maps every unmasked pixel’s slim index to its (y, x) native 2D index.

For example, if slim_to_native[3] = [2, 5], the 4th unmasked pixel (slim index 3) is located at row 2, column 5 in the native 2D array.

property native: Structure#: Returns the data structure in its native format which contains all unmaksed values to the native dimensions.

property geometry: Geometry2D#: Return the 2D geometry of the mask, representing its uniform rectangular grid of (y,x) coordinates defined by its shape_native.

property derive_indexes: DeriveIndexes2D#: Returns the DeriveIndexes2D object associated with the mask, which contains derived index arrays used to map data between slim (1D unmasked) and native (2D full-shape) representations.

property derive_mask: DeriveMask2D#: Returns the DeriveMask2D object associated with the mask, which computes derived masks such as the edge mask, border mask, and blurring mask.

property derive_grid: DeriveGrid2D#: Returns the DeriveGrid2D object associated with the mask, which computes derived grids of (y,x) coordinates such as the unmasked pixel grid, edge grid, and border grid.

property zoom: Zoom2D#: Returns the Zoom2D object associated with the mask, which computes the zoomed region of the mask around its unmasked pixels for use in visualization.

classmethod all_false(shape_native, pixel_scales, origin=(0.0, 0.0), invert=False)[source]#

Create a mask where all pixels are False and therefore unmasked.

Parameters:

shape_native (Tuple[int, int]) – The 2D shape of the mask that is created.
pixel_scales (Union[Tuple[float], Tuple[float, float], float]) – The (y,x) scaled units to pixel units conversion factors of every pixel. If this is input as a float, it is converted to a (float, float) structure.
origin (Tuple[float, float]) – The (y,x) scaled units origin of the mask’s coordinate system.
invert (bool) – If True, the bool’s of the input mask are inverted, for example False’s become True and visa versa.

classmethod circular(shape_native, radius, pixel_scales, origin=(0.0, 0.0), centre=(0.0, 0.0), invert=False)[source]#

Returns a Mask2D (see Mask2D.__new__) where all False entries are within a circle of input radius.

The radius and centre are both input in scaled units.

Parameters:

shape_native (Tuple[int, int]) – The (y,x) shape of the mask in units of pixels.
radius (float) – The radius in scaled units of the circle within which pixels are False and unmasked.
pixel_scales (Union[Tuple[float], Tuple[float, float], float]) – The (y,x) scaled units to pixel units conversion factors of every pixel. If this is input as a float, it is converted to a (float, float) structure.
origin (Tuple[float, float]) – The (y,x) scaled units origin of the mask’s coordinate system.
centre (Tuple[float, float]) – The (y,x) scaled units centre of the circle used to mask pixels.
invert (bool) – If True, the bool’s of the input mask are inverted, for example False’s become True and visa versa.

classmethod circular_annular(shape_native, inner_radius, outer_radius, pixel_scales, origin=(0.0, 0.0), centre=(0.0, 0.0), invert=False)[source]#

Returns a Mask2D (see Mask2D.__new__) where all False entries are within an annulus of input inner radius and outer radius.

The inner_radius, outer_radius and centre are all input in scaled units.

Parameters:

shape_native (Tuple[int, int]) – The (y,x) shape of the mask in units of pixels.
inner_radius (float) – The inner radius in scaled units of the annulus within which pixels are False and unmasked.
outer_radius (float) – The outer radius in scaled units of the annulus within which pixels are False and unmasked.
pixel_scales (Union[Tuple[float], Tuple[float, float], float]) – The (y,x) scaled units to pixel units conversion factors of every pixel. If this is input as a float, it is converted to a (float, float) structure.
origin (Tuple[float, float]) – The (y,x) scaled units origin of the mask’s coordinate system.
centre (Tuple[float, float]) – The (y,x) scaled units centre of the annulus used to mask pixels.
invert (bool) – If True, the bool’s of the input mask are inverted, for example False’s become True and visa versa.

classmethod elliptical(shape_native, major_axis_radius, axis_ratio, angle, pixel_scales, origin=(0.0, 0.0), centre=(0.0, 0.0), invert=False)[source]#

Returns a Mask2D (see Mask2D.__new__) where all False entries are within an ellipse.

The major_axis_radius, and centre are all input in scaled units.

Parameters:

shape_native (Tuple[int, int]) – The (y,x) shape of the mask in units of pixels.
major_axis_radius (float) – The major-axis in scaled units of the ellipse within which pixels are unmasked.
axis_ratio (float) – The axis-ratio of the ellipse within which pixels are unmasked.
angle (float) –

The rotation angle of the ellipse within which pixels are unmasked, (counter-clockwise from the positive
x-axis).
pixel_scales (Union[Tuple[float], Tuple[float, float], float]) – The (y,x) scaled units to pixel units conversion factors of every pixel. If this is input as a float, it is converted to a (float, float) structure.
origin (Tuple[float, float]) – The (y,x) scaled units origin of the mask’s coordinate system.
centre (Tuple[float, float]) – The (y,x) scaled units centred of the ellipse used to mask pixels.
invert (bool) – If True, the bool’s of the input mask are inverted, for example False’s become True and visa versa.

classmethod elliptical_annular(shape_native, inner_major_axis_radius, inner_axis_ratio, inner_phi, outer_major_axis_radius, outer_axis_ratio, outer_phi, pixel_scales, origin=(0.0, 0.0), centre=(0.0, 0.0), invert=False)[source]#

Returns a Mask2D (see Mask2D.__new__) where all False entries are within an elliptical annulus of input inner and outer scaled major-axis and centre.

The outer_major_axis_radius, inner_major_axis_radius and centre are all input in scaled units.

Parameters:

(int (shape_native) – The (y,x) shape of the mask in units of pixels.
int) – The (y,x) shape of the mask in units of pixels.
pixel_scales (Union[Tuple[float], Tuple[float, float], float]) – The scaled units to pixel units conversion factor of each pixel.
inner_major_axis_radius (float) – The major-axis in scaled units of the inner ellipse within which pixels are masked.
inner_axis_ratio (float) – The axis-ratio of the inner ellipse within which pixels are masked.
inner_phi (float) – The rotation angle of the inner ellipse within which pixels are masked, (counter-clockwise from the positive x-axis).
outer_major_axis_radius (float) – The major-axis in scaled units of the outer ellipse within which pixels are unmasked.
outer_axis_ratio (float) – The axis-ratio of the outer ellipse within which pixels are unmasked.
outer_phi (float) – The rotation angle of the outer ellipse within which pixels are unmasked, (counter-clockwise from the positive x-axis).
origin (Tuple[float, float]) – The (y,x) scaled units origin of the mask’s coordinate system.
centre (Tuple[float, float]) – The (y,x) scaled units centre of the elliptical annuli used to mask pixels.
invert (bool) – If True, the bool’s of the input mask are inverted, for example False’s become True and visa versa.

classmethod from_pixel_coordinates(shape_native, pixel_coordinates, pixel_scales, origin=(0.0, 0.0), buffer=0, invert=False)[source]#

Returns a Mask2D (see Mask2D.__new__) where all False entries are defined from an input list of list of pixel coordinates.

These may be buffed via an input buffer, whereby all entries in all 8 neighboring directions by this amount.

Parameters:

(int (shape_native) – The (y,x) shape of the mask in units of pixels.
int) – The (y,x) shape of the mask in units of pixels.
pixel_coordinates ([[<class ‘int’>, <class ‘int’>]]) – The input lists of 2D pixel coordinates where False entries are created.
pixel_scales (Union[Tuple[float], Tuple[float, float], float]) – The scaled units to pixel units conversion factor of each pixel.
origin (Tuple[float, float]) – The (y,x) scaled units origin of the mask’s coordinate system.
buffer (int) – All input pixel_coordinates are buffed with False entries in all 8 neighboring directions by this amount.
invert (bool) – If True, the bool’s of the input mask are inverted, for example False’s become True and visa versa.

classmethod from_fits(file_path, pixel_scales, hdu=0, origin=(0.0, 0.0), resized_mask_shape=None, invert=False)[source]#

Load a Mask2D from a 2D boolean array stored in a .fits file.

Parameters:

file_path (Union[Path, str]) – The full path of the .fits file, including the file name and extension.
pixel_scales (Union[Tuple[float], Tuple[float, float], float]) – The (y,x) scaled units to pixel units conversion factors of every pixel. If this is input as a float, it is converted to a (float, float) structure.
hdu (int) – The HDU number in the .fits file containing the mask array.
origin (Tuple[float, float]) – The (y,x) scaled units origin of the mask’s coordinate system.
resized_mask_shape (Tuple[int, int]) – If provided, the loaded mask is resized to this (y,x) shape after loading.
invert (bool) – If True, the bool’s of the loaded mask are inverted, so False entries become True and vice versa.

Returns:

The mask loaded from the .fits file.

Return type:

Mask2D

property shape_native: Tuple[int, ...]#: The 2D shape of the mask in its native representation, equal to the shape of the underlying boolean ndarray.

fft_index_for_masked_pixel#

A property that is only computed once per instance and then replaces itself with an ordinary attribute. Deleting the attribute resets the property.

Source: https://github.com/bottlepy/bottle/commit/fa7733e075da0d790d809aa3d2f53071897e6f76

extent_index_for_masked_pixel#

A property that is only computed once per instance and then replaces itself with an ordinary attribute. Deleting the attribute resets the property.

Source: https://github.com/bottlepy/bottle/commit/fa7733e075da0d790d809aa3d2f53071897e6f76

trimmed_array_from(padded_array, image_shape)[source]#

Map a padded 1D array of values to its original 2D array, trimming all edge values.

Parameters:: padded_array – A 1D array of values which were computed using a padded grid

unmasked_blurred_array_from(padded_array, psf, image_shape)[source]#

Convolve a padded array with the PSF and trim it back to the original image shape.

This relies on a padded array whose shape extends beyond the masked region, so that PSF convolution does not suffer from edge effects. The result is trimmed back to image_shape after convolution.

Parameters:

padded_array – The padded Array2D (or slim 1D representation) of values to be convolved with the PSF.
psf – The PSF convolver used to blur the padded array.
image_shape – The (y,x) shape of the original (unpadded) image, used to trim the blurred result.

Returns:

The blurred and trimmed Array2D of shape image_shape.

Return type:

Array2D

property header_dict: Dict#

Returns the pixel scales of the mask as a header dictionary, which can be written to a .fits file.

A 2D mask has different pixel scale variables for each dimension, the header therefore contain both pixel scales as separate y and x entries.

Return type:: A dictionary containing the pixel scale of the mask, which can be output to a .fits file.

property mask_centre: Tuple[float, float]#

The (y,x) scaled coordinate centre of the unmasked pixels in the mask.

This is computed as the mean of the (y,x) scaled coordinates of all unmasked pixels.

Return type:: The (y,x) centre of the unmasked region of the mask in scaled units.

property shape_native_masked_pixels: Tuple[int, int]#

The (y,x) shape corresponding to the extent of unmasked pixels that go vertically and horizontally across the mask.

For example, if a mask is primarily surrounded by True entries, and there are 15 False entries going vertically and 12 False entries going horizontally in the central regions of the mask, then shape_masked_pixels=(15,12).

rescaled_from(rescale_factor)[source]#

Returns the Mask2D rescaled to a bigger or small shape via input rescale_factor.

For example, for a rescale_factor=2.0 the following mask:

::

[[ True, True],: [False, False]]

Will double in size and become:

::

[[True, True, True, True],: [True, True, True, True], [False, False, False, False], [False, False, False, False]]

Parameters:: rescale_factor – The factor by which the Mask2D is rescaled (less than 1.0 produces a smaller mask, greater than 1.0 produces a bigger mask).

Examples

import autoarray as aa

mask_2d = aa.Mask2D(
    mask=[
         [ True,  True],
         [False, False]
    ],
    pixel_scales=1.0,
)

print(mask_2d.rescaled_from(rescale_factor=2.0)

resized_from(new_shape, pad_value=0.0)[source]#

Returns the Mask2D resized to a small or bigger ndarray, but with the same distribution of: False and True entries.

Resizing which increases the Mask2D shape pads it with values on its edge.

Resizing which reduces the Mask2D shape removes entries on its edge.

For example, for a new_shape=(4,4) the following mask:

::

[[ True, True],: [False, False]]

Will be padded with zeros (False values) and become:

::

[[True, True, True, True]: [True, True, True, True], [True, False, False, True], [True, True, True, True]]

Parameters:

new_shape – The new two-dimensional shape of the resized Mask2D.
pad_value (int) – The value new values are padded using if the resized Mask2D is bigger.

Examples

import autoarray as aa

mask_2d = aa.Mask2D(
    mask=[
         [ True,  True],
         [False, False]
    ],
    pixel_scales=1.0,
)

print(mask_2d.resized_from(new_shape=(4,4))

property is_circular: bool#

Returns whether the unmasked region of the mask is a filled circular disc.

The check is robust to circles whose centre is offset from the coordinate origin, including offsets that do not align with pixel boundaries. It rejects annular, square and other non-disc shapes.

The algorithm:

The bounding box of unmasked pixels must be square to within one pixel. Offset centres that fall between pixel centres can produce a one-pixel asymmetry in the bounding box, which is allowed; anything larger indicates a non-circular shape such as an ellipse. Tiny masks (bounding box <= 2 pixels) require an exactly square bounding box, since the one-pixel slack would otherwise admit 1x2 strips.
The pixel at the geometric centre of the bounding box must be unmasked. This rejects annular masks whose inner hole is at least one pixel wide.
The centre and radius of the unmasked region are inferred from the bounding box and pixel count, and a reference circular mask is built with those parameters. The input mask must match the reference within a small number of pixels (tolerance scales with mask area to absorb rim quantization). This rejects squares, crosses and tight annuli that slipped past the earlier checks.

This function does not support rectangular masks and an exception will be raised if the pixel scales in each direction are different.

property circular_radius: float#

Returns the radius in scaled units of a circular mask.

The radius is computed from the bounding box of the unmasked region, taking the larger of the y and x extents as the diameter in pixels. This is robust to offset centres that fall between pixel boundaries (where the bounding box can be asymmetric by one pixel).

The mask is first checked that it is circular using the is_circular property, with an exception raised if it is not.

This function does not support rectangular masks and an exception will be raised if the pixel scales in each direction are different.

Return type:: The circular radius of the mask in scaled units.