autolens.Imaging#

class Imaging[source]#

Bases: AbstractDataset

An imaging dataset, containing the image data, noise-map, PSF and associated quantities for calculations like the grid.

This object is the input to the FitImaging object, which fits the dataset with a model image and quantifies the goodness-of-fit via a residual map, likelihood, chi-squared and other quantities.

The following quantities of the imaging data are available and used for the following tasks:

  • data: The image data, which shows the signal that is analysed and fitted with a model image.

  • noise_map: The RMS standard deviation error in every pixel, which is used to compute the chi-squared value

and likelihood of a fit.

  • psf: The Point Spread Function of the data, used to perform 2D convolution on images to produce a model

image which is compared to the data.

The dataset also has a number of (y,x) grids of coordinates associated with it, which map to the centres of its image pixels. They are used for performing calculations which map directly to the data and have over sampling calculations built in which approximate the 2D line integral of these calculations within a pixel. This is explained in more detail in the GridsDataset class.

Parameters:

  • data (Array2D) – The array of the image data containing the signal that is fitted (in PyAutoGalaxy and PyAutoLens the recommended units are electrons per second).

  • noise_map (Optional[Array2D]) – An array describing the RMS standard deviation error in each pixel used for computing quantities like the chi-squared in a fit (in PyAutoGalaxy and PyAutoLens the recommended units are electrons per second).

  • psf (Optional[Kernel2D]) – The Point Spread Function kernel of the image which accounts for diffraction due to the telescope optics via 2D convolution.

  • noise_covariance_matrix (Optional[ndarray]) – A noise-map covariance matrix representing the covariance between noise in every data value, which can be used via a bespoke fit to account for correlated noise in the data.

  • over_sample_size_lp (Union[int, Array2D]) – The over sampling scheme size, which divides the grid into a sub grid of smaller pixels when computing values (e.g. images) from the grid to approximate the 2D line integral of the amount of light that falls into each pixel.

  • over_sample_size_pixelization (Union[int, Array2D]) – How over sampling is performed for the grid which is associated with a pixelization, which is therefore passed into the calculations performed in the inversion module.

  • pad_for_convolver (bool) – The PSF convolution may extend beyond the edges of the image mask, which can lead to edge effects in the convolved image. If True, the image and noise-map are padded to ensure the PSF convolution does not extend beyond the edge of the image.

  • use_normalized_psf (Optional[bool]) – If True, the PSF kernel values are rescaled such that they sum to 1.0. This can be important for ensuring the PSF kernel does not change the overall normalization of the image when it is convolved with it.

  • check_noise_map (bool) – If True, the noise-map is checked to ensure all values are above zero.

Methods

apply_mask

Apply a mask to the imaging dataset, whereby the mask is applied to the image data, noise-map and other quantities one-by-one.

apply_noise_scaling

Apply a mask to the imaging dataset using noise scaling, whereby the maskmay zero the data and increase noise-map values to change how they enter the likelihood calculation.

apply_over_sampling

Apply new over sampling objects to the grid and grid pixelization of the dataset.

from_fits

Load an imaging dataset from multiple .fits file.

output_to_fits

Output an imaging dataset to multiple .fits file.

trimmed_after_convolution_from

Attributes

convolver

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

grid

grids

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

mask

noise_covariance_matrix_inv

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

pixel_scales

shape_native

shape_slim

signal_to_noise_map

The estimated signal-to-noise_maps mappers of the image.

signal_to_noise_max

The maximum value of signal-to-noise_maps in an image pixel in the image's signal-to-noise_maps mappers.

w_tilde

A property that is only computed once per instance and then replaces itself with an ordinary attribute.
classmethod from_fits(pixel_scales, data_path, noise_map_path, data_hdu=0, noise_map_hdu=0, psf_path=None, psf_hdu=0, noise_covariance_matrix=None, check_noise_map=True, over_sample_size_lp=4, over_sample_size_pixelization=4)[source]#

Load an imaging dataset from multiple .fits file.

For each attribute of the imaging data (e.g. data, noise_map, pre_cti_data) the path to the .fits and the hdu containing the data can be specified.

The noise_map assumes the noise value in each data value are independent, where these values are the the RMS standard deviation error in each pixel.

A noise_covariance_matrix can be input instead, which represents the covariance between noise values in the data and can be used to fit the data accounting for correlations (the noise_map is the diagonal values of this matrix).

If the dataset has a mask associated with it (e.g. in a mask.fits file) the file must be loaded separately via the Mask2D object and applied to the imaging after loading via fits using the from_fits method.

Parameters:

  • pixel_scales (Union[Tuple[float], Tuple[float, float], float]) – The (y,x) arcsecond-to-pixel units conversion factor of every pixel. If this is input as a float, it is converted to a (float, float).

  • data_path (Union[Path, str]) – The path to the data .fits file containing the image data (e.g. ‘/path/to/image.fits’).

  • data_hdu (int) – The hdu the image data is contained in the .fits file specified by data_path.

  • psf_path (Union[Path, str, None]) – The path to the psf .fits file containing the psf (e.g. ‘/path/to/psf.fits’).

  • psf_hdu (int) – The hdu the psf is contained in the .fits file specified by psf_path.

  • noise_map_path (Union[Path, str]) – The path to the noise_map .fits file containing the noise_map (e.g. ‘/path/to/noise_map.fits’).

  • noise_map_hdu (int) – The hdu the noise map is contained in the .fits file specified by noise_map_path.

  • noise_covariance_matrix (Optional[ndarray]) – A noise-map covariance matrix representing the covariance between noise in every data value.

  • check_noise_map (bool) – If True, the noise-map is checked to ensure all values are above zero.

  • over_sample_size_lp (Union[int, Array2D]) – The over sampling scheme size, which divides the grid into a sub grid of smaller pixels when computing values (e.g. images) from the grid to approximate the 2D line integral of the amount of light that falls into each pixel.

  • over_sample_size_pixelization (Union[int, Array2D]) – How over sampling is performed for the grid which is associated with a pixelization, which is therefore passed into the calculations performed in the inversion module.

Return type:

Imaging

apply_mask(mask)[source]#

Apply a mask to the imaging dataset, whereby the mask is applied to the image data, noise-map and other quantities one-by-one.

The original unmasked imaging data is stored as the self.unmasked attribute. This is used to ensure that if the apply_mask function is called multiple times, every mask is always applied to the original unmasked imaging dataset.

Parameters:

mask (Mask2D) – The 2D mask that is applied to the image.

Return type:

Imaging

apply_noise_scaling(mask, noise_value=100000000.0, signal_to_noise_value=None, should_zero_data=True)[source]#

Apply a mask to the imaging dataset using noise scaling, whereby the maskmay zero the data and increase noise-map values to change how they enter the likelihood calculation.

Given this data region is masked, it is likely thr data itself should not be included and therefore the masked data values are set to zero. This can be disabled by setting should_zero_data=False.

Two forms of scaling are supported depending on whether the signal_to_noise_value is input:

  • noise_value: The noise-map values in the masked region are set to this value, typically a very large value,

such that they are never included in the likelihood calculation.

  • signal_to_noise_value: The noise-map values in the masked region are set to values such that they give

this signal-to-noise ratio. This overwrites the noise_value parameter.

For certain modeling tasks, the mask defines regions of the data that are used to calculate the likelihood. For example, all data points in a mask may be used to create a pixel-grid, which is used in the likelihood. When data points are moved via apply_mask, they would be omitted from this grid entirely, which would lead to an incorrect likelihood calculation. Noise scaling retains these data points in the likelihood calculation, but ensures they do not contribute to the fit.

This function can only be applied before actual masking.

Parameters:

  • mask (Mask2D) – The 2D mask that is applied to the image and noise-map, to scale the noise-map values to large values.

  • noise_value (float) – The value that the noise-map values are set to in the masked region where noise scaling is applied.

  • signal_to_noise_value (Optional[float]) – The noise-map values are instead set to values such that they give this signal-to-noise_maps ratio. This overwrites the noise_value parameter.

  • should_zero_data (bool) – If True, the data values in the masked region are set to zero.

Return type:

Imaging

apply_over_sampling(over_sample_size_lp=None, over_sample_size_pixelization=None)[source]#

Apply new over sampling objects to the grid and grid pixelization of the dataset.

This method is used to change the over sampling of the grid and grid pixelization, for example when the user wishes to perform over sampling with a higher sub grid size or with an iterative over sampling strategy.

The grid and grids.pixelization` are cached properties which after use are stored in memory for efficiency. This function resets the cached properties so that the new over sampling is used in the grid and grid pixelization.

Parameters:

  • over_sample_size_lp (Union[int, Array2D]) – The over sampling scheme size, which divides the grid into a sub grid of smaller pixels when computing values (e.g. images) from the grid to approximate the 2D line integral of the amount of light that falls into each pixel.

  • over_sample_size_pixelization (Union[int, Array2D]) – How over sampling is performed for the grid which is associated with a pixelization, which is therefore passed into the calculations performed in the inversion module.

Return type:

AbstractDataset

output_to_fits(data_path, psf_path=None, noise_map_path=None, overwrite=False)[source]#

Output an imaging dataset to multiple .fits file.

For each attribute of the imaging data (e.g. data, noise_map) the path to the .fits can be specified, with hdu=0 assumed automatically.

If the data has been masked, the masked data is output to .fits files. A mask can be separately output to a file mask.fits via the Mask objects output_to_fits method.

Parameters:

  • data_path (Union[Path, str]) – The path to the data .fits file where the image data is output (e.g. ‘/path/to/data.fits’).

  • psf_path (Union[Path, str, None]) – The path to the psf .fits file where the psf is output (e.g. ‘/path/to/psf.fits’).

  • noise_map_path (Union[Path, str, None]) – The path to the noise_map .fits where the noise_map is output (e.g. ‘/path/to/noise_map.fits’).

  • overwrite (bool) – If True, the .fits files are overwritten if they already exist, if False they are not and an exception is raised.