autolens.Imaging#

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[Convolver]) – The Point Spread Function kernel of the image which accounts for diffraction due to the telescope optics via 2D convolution.
psf_setup_state (bool) – If True, a ConvolverState is precomputed from the PSF kernel and mask, storing the convolution pair indices required for efficient 2D convolution. This is set automatically to True when a mask is applied via apply_mask() and should not normally be set by hand.
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.
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.
sparse_operator (Optional[ImagingSparseOperator]) – The sparse linear algebra formalism of the linear algebra equations precomputes the convolution of every pair of masked noise-map values given the PSF (see inversion.inversion_util). Pass the ImagingSparseOperator object here to enable this linear algebra formalism for pixelized reconstructions.

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.
`apply_sparse_operator`	Precompute the PSF precision operator for efficient pixelized source reconstruction.
`apply_sparse_operator_cpu`	Precompute the PSF precision operator using a CPU-only Numba implementation.
`from_fits`	Load an imaging dataset from multiple .fits file.
`trimmed_after_convolution_from`	Return a copy of the dataset with all arrays trimmed to remove the border pixels affected by PSF convolution edge effects.

Attributes

`grid`	The primary coordinate grid of the dataset, equivalent to grids.lp.
`mask`	The mask of the dataset, derived from the mask of the data array.
`noise_covariance_matrix_inv`	Returns the inverse of the noise covariance matrix, which is used when computing a chi-squared which accounts for covariance via a fit.
`pixel_scales`	The (y, x) arcsecond-to-pixel conversion factor of the dataset, as a (float, float) tuple.
`shape_native`	The 2D shape of the dataset image in its native (unmasked) dimensions, e.g. (rows, columns).
`shape_slim`	The 1D size of the dataset data array after masking, i.e. the number of unmasked pixels.
`signal_to_noise_map`	The signal-to-noise map of the dataset, computed as data / noise_map.
`signal_to_noise_max`	The maximum signal-to-noise value across all unmasked pixels in the dataset.

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.

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 mask is applied to the data, noise_map, over_sample_size_lp and over_sample_size_pixelization arrays. If a noise_covariance_matrix is present, the rows and columns corresponding to masked pixels are removed so it stays consistent with the remaining unmasked pixels. The PSF ConvolverState is recomputed for the new mask.

The apply_mask function cannot be called multiple times — a new mask cannot expand the unmasked region beyond what was already unmasked, as the underlying data has already been trimmed. An exception is raised if this is attempted. If you wish to apply a different mask, reload the dataset from .fits files.

Parameters:: mask (Mask2D) – The 2D mask that is applied to the image.
Returns:: A new Imaging dataset with the mask applied to all arrays.
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.

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.

apply_sparse_operator(batch_size=128)[source]#

Precompute the PSF precision operator for efficient pixelized source reconstruction.

The sparse linear algebra formalism precomputes the convolution of every pair of masked noise-map values given the PSF (see inversion.inversion_util). This is the imaging equivalent of the interferometer NUFFT precision matrix.

The ImagingSparseOperator stores these precomputed values in the imaging dataset ensuring they are only computed once per analysis, enabling fast repeated likelihood evaluations during model fitting.

Parameters:: batch_size (int) – The number of image pixels processed per batch when computing the sparse operator via FFT-based convolution. Reducing this lowers peak memory usage at the cost of speed.
Returns:: A new Imaging dataset with the precomputed ImagingSparseOperator attached, enabling efficient pixelized source reconstruction via the sparse linear algebra formalism.
Return type:: Imaging

apply_sparse_operator_cpu()[source]#

Precompute the PSF precision operator using a CPU-only Numba implementation.

This is the CPU alternative to apply_sparse_operator(), using Numba JIT compilation for the convolution loop rather than JAX. It requires numba to be installed; an InversionException is raised if it is not available.

The resulting SparseLinAlgImagingNumba operator is stored on the returned Imaging dataset and used by FitImaging when performing pixelized source reconstructions.

Returns:: A new Imaging dataset with a precomputed Numba-based sparse operator attached, enabling efficient pixelized source reconstruction on CPU hardware.
Return type:: Imaging