IterativeGeneralizedGaussianWBackground

class giant.point_spread_functions.gaussians.IterativeGeneralizedGaussianWBackground(a_coef=None, b_coef=None, c_coef=None, sigma_x=None, sigma_y=None, theta=None, amplitude=None, centroid_x=0, centroid_y=0, size=None, bg_b_coef=None, bg_c_coef=None, bg_d_coef=None)

Bases: GeneralizedGaussian, InitialGuessIterativeNonlinearLSTSQPSFwBackground

A class for representing and fitting the superposition of a standard (non-rotated) 2D Gaussian point spread function and a linear background gradiant using iterative non-linear least squares.

This class differs from the GeneralizedGaussian class in the way the fit() class method works and in the fact that it adds a background gradient to the model. In this version, the fit is performed using iterative non-linear least squares, which is typically more accurate than using the logarithmic transformation to do linear least squares at the expense of more computation time.

The specific model that is fit is given by

\[f(x, y) = A e^{\left(-\left[a(x-x_0)^2+b(x-x_0)(y-y_0)+c(y-y_0)^2\right]\right)} + Bx+Cy+D\]

This class can be used anywhere GIANT expects a point spread function

Parameters:

• a_coef (float) – The a coefficient of the Gaussian polynomial

• b_coef (float) – The b coefficient of the Gaussian polynomial

• c_coef (float) – The c coefficient of the Gaussian polynomial

• sigma_x (float) – The Gaussian RMS width in the x direction in pixels

• sigma_y (float) – The Gaussian RMS Width in the y direction in pixels. If set to 0 or None this is set to be the same as sigma_x

• sigma_x – The angle between the x-axis and the principal axis of the Gaussian in radians.

• size (int) – The size of the kernel to use when applying this PSF in pixels. If set to 0 or None will be computed based on the Gaussian RSM widths.

• amplitude (float) – The amplitude of the gaussian kernel to use when applying this PSF. If set to 0 or None this will be computed so that the kernel does not increase/decrease the total signal.

• centroid_x (float) – The x location of the peak of the Gaussian PSF in pixels. This is not used when applying the PSF, but it is used when fitting the PSF. Typically this is not specified by the user.

• centroid_y (float) – The y location of the peak of the Gaussian PSF in pixels. This is not used when applying the PSF, but it is used when fitting the PSF. Typically this is not specified by the user.

• bg_b_coef (float) – The x slope of the background gradient

• bg_c_coef (float) – They y slope of the background gradient

• bg_d_coef (float) – The constant offset of the background gradient

• theta (float) –

save_residuals = False

This class attribute specifies whether to save the residuals when fitting the specified PSF to data.

Saving the residuals can be important for in depth analysis but can use a lot of space when many fits are being performed and stored so this defaults to off. To store the residuals simply set this to True either before or after initialization.

max_iter = 20

An integer defining the maximum number of iterations to attempt in the iterative least squares solution.

atol = 1e-10

The absolute tolerance cut-off for the iterative least squares. (The iteration will cease when the new estimate is within this tolerance for every element from the previous estimate)

rtol = 1e-10

The relative tolerance cut-off for the iterative least squares. (The iteration will cease when the maximum percent change in the state vector from one iteration to the next is less than this value)

a_coef: float

The \((x-x_0)^2\) coefficient from the exponential component of the generalized 2D Gaussian.

b_coef: float

The \((x-x_0)(y-y_0)\) coefficient from the exponential component of the generalized 2D Gaussian.

c_coef: float

The \((y-y_0)^2\) coefficient from the exponential component of the generalized 2D Gaussian.

sigma_x: float

The RMS width in the semi-major axis direction.

sigma_y: float

The RMS width in the semi-minor axis direction.

theta: float

The angle between the semi-major axis and the x axis

amplitude: float

The amplitude of the Gaussian.

This specifies how much energy the Gaussian function increases or decreases the signal by.

Typically this is set so that the kernel does not increase or decrease the signal, which can be achieved by using the normalize_amplitude() method.

centroid_x: float

The x location of the peak of the Gaussian kernel

When applying the gaussian kernel, the centroid doesn’t matter as it will always be applied as if it was centered on a pixel. In general this is just used when estimating a kernel to locate the peak of the PSF in the image.

centroid_y: float

The y location of the peak of the Gaussian kernel

When applying the gaussian kernel, the centroid doesn’t matter as it will always be applied as if it was centered on a pixel. In general this is just used when estimating a kernel to locate the peak of the PSF in the image.

bg_b_coef: float

The x slope of the background gradient

bg_c_coef: float

The y slope of the background gradient

bg_d_coef: float

The constant offset of the background gradient

property residuals: ndarray

A 1D array containing residuals of the fit of this Gaussian Model to data.

These are only populated when initialized by fit() and when the class attribute save_residuals is set to true.

property covariance: ndarray | None

The formal covariance of the PSF parameters after fitting this PSF model to data.

If this instance is not the result of a fit (fit()) of if save_residuals is False then this will return None.

The order of the state vector (and thus the covariance matrix) is \([x_0, y_0, a, b, c, A]\).

size: int

The size of the kernel to return on a call to generate_kernel().

Typically this should be an odd number to ensure that the kernel is square and centered.

property residual_mean: float | None

The mean of the post-fit residuals after fitting this PSF model to data.

If this instance is not the result of a fit (fit()) or if save_residuals is False then this will return None

property residual_std: float | None

The standard deviation of the post-fit residuals after fitting this PSF model to data.

If this instance is not the result of a fit (fit()) or if save_residuals is False then this will return None

property residual_rss: float | None

The sum of squares of the post-fit residuals after fitting this PSF model to data.

If this instance is not the result of a fit (fit()) or if save_residuals is False then this will return None

Summary of Methods

fit	This fits a 2d gaussian function to a surface using iterative non-linear least squares estimation.
__call__	This method generates a kernel and then convolves it with the input image.
apply_1d	Applies the defined PSF using the stored parameters to the 1D image scans provided.
apply_1d_sized	Applies the defined PSF using the stored parameters to the 1D image scans provided with a given kernel size.
compute_jacobian	This method computes the Jacobian of the PSF with respect to a change in the state.
determine_size	Sets the size for the kernel based on the width of the PSF.
evaluate	This method evaluates the PSF at the given x and y.
generate_kernel	Generates a square kernel centered at the centroid of the PSF normalized to have a volume (sum) of 1 for the size input or specified in the size attribute.
normalize_amplitude	Calculate and store the amplitude that makes the volume under the gaussian surface equal to 1
update_state	Updates the current values based on the provided update vector.
apply_update_bg	This applies the background update to the background state
compute_jacobian_all	This method computes the Jacobian of the PSF with respect to a change in the state.
compute_jacobian_bg	This computes the Jacobian matrix for the background terms.
converge	Performs iterative non-linear least squares on a PSF model until convergence has been reached for a function of the form \(z=f(x, y)\)
evaluate_bg	This computes the background component at locations x and y.
fit_bg	This method tries to fit the background using linear least squares without worrying about any PSF included.
fit_lstsq	This fits a PSF to a surface using iterative non-linear least squares estimation.