giant.point_spread_functions¶

This package provides classes for creating/using point spread function is GIANT.

In GIANT a Point Spread Function (PSF) represents the way a camera spreads out light from a point source across multiple pixels. This is analogous to the modulation transfer function (MTF) but in the spatial domain instead of the frequency domain.

PSFs are used extensively throughout GIANT. They are used to locate the centroid of stars and unresolved objects in stellar_opnav, unresolved, and calibration. They are also used in relative_opnav to “blur” templates to make them more closely resemble what is actually captured by the camera before attempting cross-correlation.

There are many different ways to model PSFs for cameras, but one of the most popular and common is to use a 2D Gaussian function. Giant provides implementations for using Gaussian functions as the PSF in classes Gaussian, GeneralizedGaussian, IterativeGaussian, IterativeGeneralizedGaussian, IterativeGaussianWBackground and IterativeGeneralizedGaussianWBackground. These fully implemented classes can generally be used as is throughout GIANT for most cameras. In some cases however a camera may have a PSF that is not well modeled by a Gaussian function, in which case, the point_spread_functions module provides some abstract base classes and common functionality that can make creating a new PSF easier.

If you are just starting out, we recommend that you begin with one of the provided PSF models as these are generally sufficient and are easy to use.

class giant.point_spread_functions.PointSpreadFunction[source]¶

This abstract base class serves as the template for implementing a point spread function in GIANT.

A point spread function models how a camera spreads out a point source of light across multiple pixels in an image. GIANT uses PSFs both for making rendered templates more realistic for correlation in relative_opnav and for centroiding of stars and unresolved bodies for center finding (unresolved), attitude estimation (stellar_opnav), and camera calibration (calibration).

In general, a PSF class is assigned to the ImageProcessing.psf attribute and an initialized version of the class is assigned to the Camera.psf attribute. GIANT will then use the specified PSF wherever it is needed. For more details refer to the point_spread_functions package documentation.

This class serves as a prototype for implementing a PSF in GIANT. It defines all the interfaces that GIANT expects for duck typing as abstract methods and properties to help you know you’ve implemented everything you need.

Note

Because this is an ABC, you cannot create an instance of this class (it will raise a TypeError)

save_residuals: bool = 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 before initialization.

abstract apply_1d(image_1d, direction=None, step=1)[source]¶

Applies the defined PSF using the stored parameters to the 1D image scans provided.

image_1d can be a 2D array but in that case each row will be treated as an independent 1D scan.

For non-symmetric PSFs, a direction argument can be supplied which should be the direction in the image of each scan line. This can be used to determine the appropriate cross-section of the PSF to use for applying to the 1D scans (if applicable). If no direction is provided then the x direction [1, 0] is assumed.

Parameters:

image_1d (ndarray) – The scan line(s) to be blurred using the PSF
direction (ndarray | None) – The direction for the 1D cross section of the PSF. This should be either None, a length 2 array, or a shape nx2 array where n is the number of scan lines
step (Real) – The step size of the lines being blurred.

Returns:

an array containing the input after blurring with the defined PSF

Return type:

ndarray

abstract generate_kernel()[source]¶

Generates a square kernel centered at the centroid of the PSF normalized to have a volume (sum) of 1.

Essentially this evaluates \(z = f(x, y)\) for x in \([x_0-size//2, x_0+size//2]\) and y in \([y_0-size//2, y_0+size//2]\) where x0 is the x location of the centroid of the PSF and y0 is the y location of the centroid of the PSF.

The resulting values are then normalized to sum to 1 so that the result can be applied using convolution without changing the overall signal level.

Returns:: A normalized kernel of the PSF centered at the centroid
Return type:: ndarray

abstract evaluate(x, y)[source]¶

This method evaluates the PSF at the given x and y.

This method is not intended to be used to apply the PSF for an image (use the callable capability of the class instead for this). Instead it simply computes the height of the PSF above the xy-plane at the requested locations.

Parameters:

x (Sequence | ndarray) – The x locations the height of the PSF is to be calculated at.
y (Sequence | ndarray) – The y locations the height of the PSF is to be calculated at.

Returns:

A numpy array containing the height of the PSF at the requested locations the same shape as x and y.

Return type:

ndarray

abstract classmethod fit(x, y, z)[source]¶

This function fits the defined PSF to the input data and returns an initialize version of the class based on the fit.

The fit assumes that z = f(x, y) where f is the PSF (and thus z is the “height” of the PSF).

If the fit is unsuccessful then this should set the attributes of the PSF to NaN to indicate to the rest of GIANT that the fit failed.

Parameters:

x (Sequence | ndarray) – The x values underlying the surface the PSF is to be fit to
y (Sequence | ndarray) – The y values underlying the surface the PSF is to be fit to
z (Sequence | ndarray) – The z or “height” values of the surface the PSF is to be fit to

Returns:

An instance of the PSF that best fits the provided data

Return type:

PointSpreadFunction

abstract property centroid: ndarray¶

This should return the centroid or peak of the initialized PSF as a x, y length 2 numpy array.

This property is used to enable the PSF class to be used in identifying the center of illumination in image processing (see ImageProcessing.centroiding).

abstract property residual_rss: float | None¶

This should return residual sum of squares (RSS) of the post-fit residuals from fitting this PSF to the data.

If the PSF is not the result of a fit or the save_residuals is False this will return None.

abstract property residual_mean: float | None¶

This should return the mean of the post-fit residuals from fitting this PSF to the data.

If the PSF is not the result of a fit or the save_residuals is False this will return None.

abstract property residual_std: float | None¶

This should return the standard deviation of the post-fit residuals from fitting this PSF to the data.

If the PSF is not the result of a fit or the save_residuals is False this will return None.

abstract property covariance: ndarray | None¶

This should return the formal covariance of the PSF parameters (if the PSF was fit and not initialized).

If the PSF is not the result of a fit or the save_residuals is False this will return None.

abstract volume()[source]¶

This should compute the total volume contained under the PSF.

Returns:: The total volume contained under the PSF
Return type:: float

compare(other)[source]¶

For real PSFs, this method generates how well the PSF matches another between 0 and 1, with 1 being a perfect match and 0 being a horrible match.

Typically this is evaluated as the clipped pearson product moment coefficient between the kernels of the 2 psfs.

Parameters:: other (PointSpreadFunction) –
Return type:: float

class giant.point_spread_functions.SizedPSF(size=None, **kwargs)[source]¶

This ABC adds common functionality for a PSF where the required size can be determine algorithmically.

Specifically, this adds an instance attribute size which stores the size of the PSF, a new abstract method determine_size() which should be implemented to algorithmically determine the size of the kernel required for the PSF, and concrete method generate_kernel(), which generates a square unit kernel based on the size.

Parameters:: size (int | None) – The size of the kernel to generate.

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.

abstract determine_size()[source]¶

Sets the size required for the kernel algorithmically.

Typically this is based on the width of the PSF.

The determined size should be stored in the instance attribute size

Return type:: None

generate_kernel(size=None)[source]¶

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.

Essentially this evaluates \(z = f(x, y)\) for x in \([x_0-size//2, x_0+size//2]\) and y in \([y_0-size//2, y_0+size//2]\) where x0 is the x location of the centroid of the PSF and y0 is the y location of the centroid of the PSF.

The resulting values are then normalized to sum to 1 so that the result can be applied using convolution without changing the overall signal level.

Parameters:: size (int | None) – The size of the kernel to generate (ie return a (size, size) shaped array). Overrides the size attribute.
Returns:: A normalized kernel of the PSF centered at the centroid

compare(other)[source]¶

For real PSFs, this method generates how well the PSF matches another between 0 and 1, with 1 being a perfect match and 0 being a horrible match.

Typically this is evaluated as the clipped pearson product moment coefficient between the kernels of the 2 psfs.

Parameters:: other (SizedPSF) –
Return type:: float

class giant.point_spread_functions.InitialGuessIterativeNonlinearLSTSQPSF[source]¶

This class provides a fit class method which generates the initial guess from a subclass and then converges to a better solution using iterative Nonlinear LSTSQ.

This class is designed to work where you have a non-iterative but biased class for estimating the defined PSF (as is done with Gaussian PSFs by using a logarithmic transformation). If that is the case, and the unbiased estimator class uses the same attributes and the biased estimator class, then you can use this as is to add the ability to get the biased estimate and then correct it. Otherwise you will need to do things yourself and shouldn’t bother with this class.

To use this class, override the fit() method, and then call super().fit_lstsq(x, y, z)

This also adds 2 instance attributes _residuals and _covariance which store the covariance and residuals of the fit if requested.

classmethod fit_lstsq(x, y, z)[source]¶

This fits a PSF to a surface using iterative non-linear least squares estimation.

The estimation in this function is performed iteratively. First, a non-iterative fit is performed using the super class’s fit method. This initial fit is then refined using iterative non-linear least squares to remove biases that might have been introduced in the non-iterative fit..

If the fit is unsuccessful due to a rank deficient matrix then update_states() will be called which will likely result in the state parameters being set to NaN.

Parameters:

x (Sequence | ndarray) – The x values underlying the surface the PSF is to be fit to
y (Sequence | ndarray) – The y values underlying the surface the PSF is to be fit to
z (Sequence | ndarray) – The z or “height” values of the surface the PSF is to be fit to

Returns:

The initialized PSF with values according to the fit

Return type:

InitialGuessIterativeNonlinearLSTSQPSF

class giant.point_spread_functions.InitialGuessIterativeNonlinearLSTSQPSFwBackground(bg_b_coef=None, bg_c_coef=None, bg_d_coef=None, **kwargs)[source]¶

This class provides a fit class method which generates the initial guess from a subclass and then converges to a better solution using iterative Nonlinear LSTSQ including a background gradient.

This class is designed to work where you have a non-iterative but biased class for estimating the defined PSF (as is done with Gaussian PSFs by using a logarithmic transformation). If that is the case, and the unbiased estimator class uses the same attributes and the biased estimator class, then you can use this as is to add the ability to get the biased estimate and then correct it along with the background gradient. Otherwise you will need to do things yourself and shouldn’t bother with this class.

To use this class, override the fit() method, and then call super().fit_lstsq(x, y, z)

This also adds 2 instance attributes _residuals and _covariance which store the covariance and residuals of the fit if requested.

Parameters:

bg_b_coef (Real | None) – The x slope of the background gradient
bg_c_coef (Real | None) – They y slope of the background gradient
bg_d_coef (Real | None) – The constant offset of the background gradient

classmethod fit_lstsq(x, y, z)[source]¶

This fits a PSF to a surface using iterative non-linear least squares estimation.

The estimation in this function is performed iteratively. First, the rough background is estimated and removed. Then, a non-iterative fit is performed using the super class’s fit method on the data with the rough background removed. This initial fit is then refined using iterative non-linear least squares to remove biases that might have been introduced in the non-iterative fit.

If the fit is unsuccessful due to a rank deficient matrix then update_states() will be called which will likely result in the state parameters being set to NaN.

Parameters:

x (Sequence | ndarray) – The x values underlying the surface the PSF is to be fit to
y (Sequence | ndarray) – The y values underlying the surface the PSF is to be fit to
z (Sequence | ndarray) – The z or “height” values of the surface the PSF is to be fit to

Returns:

The initialized PSF with values according to the fit

Return type:

InitialGuessIterativeNonlinearLSTSQPSFwBackground

compute_jacobian_all(x, y, computed)[source]¶

This method computes the Jacobian of the PSF with respect to a change in the state.

Mathematically, it should return the nxm matrix

\[\mathbf{J} = \frac{\partial f(x, y)}{\partial \mathbf{t}}\]

where \(f(x,y)\) is the function being fit, \(\mathbf{t}\) is a length m vector of the state parameters, and \(\mathbf{J}\) is the Jacobian matrix. This specific implementation appends the background Jacobian to the normal PSF Jacobian for estimating background terms.

Parameters:

x (ndarray) – The x values to evaluate the Jacobian at as a length n array
y (ndarray) – The y values to evaluate the Jacobian at as a length n array
computed (ndarray) – \(f(x,y)\) evaluated at x and y as a length n array. This is provided for efficiency and convenience as the evaluated function is frequently needed in the computation of the Jacobian and it is definitely needed in the non-linear least squares. If not needed for computing the Jacobian this can safely be ignored.

Returns:

The Jacobian matrix as a nxm numpy array, with n being the number of measurements and m being the number of state parameters being estimated

Return type:

ndarray

evaluate(x, y)[source]¶

This method evaluates the PSF at the given x and y.

This method is not intended to be used to apply the PSF for an image (use the callable capability of the class instead for this). Instead it simply computes the height of the PSF above the xy-plane at the requested locations.

Parameters:

x (Sequence | ndarray) – The x locations the height of the PSF is to be calculated at.
y (Sequence | ndarray) – The y locations the height of the PSF is to be calculated at.

Returns:

A numpy array containing the height of the PSF at the requested locations the same shape as x and y.

Return type:

ndarray

class giant.point_spread_functions.IterativeNonlinearLSTSQwBackground(bg_b_coef=None, bg_c_coef=None, bg_d_coef=None, **kwargs)[source]¶

This class provides support for estimating the superposition of the PSF and a linear background gradient.

This class is typically not used by the user except when implementing a new PSF class that uses iterative nonlinear least squares to fit the PSF to data.

Beyond the typical implementation in IterativeNonLinearLSTSQ, this class provides a concrete implementation of methods compute_jacobian_bg(), evaluate_bg(), and apply_update_bg() which handle the linear background gradient of the form

\[f_{bg}(x, y) = f(x,y)+Bx+Cy+D\]

where \(f_{bg}(x,y)\) is the PSF with the background, \(f(x,y)\) is the PSF without the background, \(B\) is the slope of the gradient in the x direction, \(C\) is the slope of the gradient in the y direction and \(D\) is the constant background level.

The way this class should be used it to subclass it, then in the regular compute_jacobian() method call compute_jacobian_bg() and include with the rest of your Jacobian matrix (typically at the end), then in evaluate() call evaluate_bg() and add the results to the PSF, and finally in update_states() call update_states_bg() inputting the portion of the state vector that contains the background update according to where you added it to your existing Jacobian.

The background terms are stored in instance attributes bg_b_coef, bg_c_coef, and bg_d_coef.

Parameters:

bg_b_coef (Real | None) – The x slope of the background gradient
bg_c_coef (Real | None) – They y slope of the background gradient
bg_d_coef (Real | None) – The constant offset of the background gradient

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

static compute_jacobian_bg(x, y)[source]¶

This computes the Jacobian matrix for the background terms.

Mathematically this is

\[\mathbf{J}_{bg} = \left[\begin{array}{ccc}\frac{\partial f_{bg}(x,y)}{\partial B} & \frac{\partial f_{bg}(x,y)}{\partial C} & \frac{\partial f_{bg}(x,y)}{\partial D}\end{array}\right]= \left[\begin{array}{ccc} x & y & 1\end{array}\right]\]

The results from this function should be appended to the rest of the Jacobian matrix using hstack.

Parameters:

x (ndarray) – The x values underlying the data the surface is to be fit to
y (ndarray) – The y values underlying the data the surface is to be fit to

Returns:

The Jacobian for the background as a nx3 numpy array

Return type:

ndarray

apply_update_bg(bg_update)[source]¶

This applies the background update to the background state

This typically should be called from the regular update_state() and only fed the components of the update vector that correspond to the background Jacobian matrix.

Parameters:: bg_update (Sequence | ndarray | None) – The update to apply to the background terms as a length 3 array
Return type:: None

evaluate_bg(x, y)[source]¶

This computes the background component at locations x and y.

The background component is defined as

\[Bx+Cy+D\]

Parameters:

x (ndarray) – The x values where the background is to be computed at
y (ndarray) – The y values where the background is to be computed at

Returns:

The background according to the model

Return type:

ndarray

classmethod fit_bg(x, y, z)[source]¶

This method tries to fit the background using linear least squares without worrying about any PSF included.

This is useful if you need to subtract off a rough estimate of the background before attempting to fit the PSF for an initial guess. The results of the fit are stored in the bg_b_coef, bg_c_coef, and bg_d_coef.

Parameters:

x (Sequence | ndarray) – The x values underlying the data the background is to be fit to
y (Sequence | ndarray) – The y values underlying the data the background is to be fit to
z (Sequence | ndarray) – The z or “height” values for the background

Returns:

The initialized BG PSF with values according to the fit for the background only

Return type:

IterativeNonlinearLSTSQwBackground

class giant.point_spread_functions.IterativeNonlinearLSTSQPSF[source]¶

This ABC defines common attributes, properties, and methods for Iterative Non-linear least squares estimation of a Point Spread function.

This class is typically not used by the user except when implementing a new PSF class that uses iterative nonlinear least squares to fit the PSF to data.

To use this class when implementing a new PSF, simply subclass it and then override the abstract methods compute_jacobian() and update_state() (in addition to the required abstract methods from the typical PointSpreadFunction ABC) according to the PSF you are implementing. You may also want to override the default class attributes max_iter, atol, and rtol, which control when to break out of the iterations.

Once you have overridden the abstract methods (and possibly the class attributes), you simply need to call the converge() method from somewhere within the fit() method after initializing the class with the initial guess of the PSF parameters. The converge() method will then perform iterative non-linear least squares until convergence or the maximum number of iterations have been performed according the the max_iter, atol, and rtol class attributes. The converged solution will be stored as the updated class parameters

max_iter: int = 20¶: An integer defining the maximum number of iterations to attempt in the iterative least squares solution.

atol: float = 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: float = 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)

abstract compute_jacobian(x, y, computed)[source]¶

This method computes the Jacobian of the PSF with respect to a change in the state.

Mathematically, it should return the nxm matrix

\[\mathbf{J} = \frac{\partial f(x, y)}{\partial \mathbf{t}}\]

where \(f(x,y)\) is the function being fit, \(\mathbf{t}\) is a length m vector of the state parameters, and \(\mathbf{J}\) is the Jacobian matrix

Parameters:

x (ndarray) – The x values to evaluate the Jacobian at as a length n array
y (ndarray) – The y values to evaluate the Jacobian at as a length n array
computed (ndarray) – \(f(x,y)\) evaluated at x and y as a length n array. This is provided for efficiency and convenience as the evaluated function is frequently needed in the computation of the Jacobian and it is definitely needed in the non-linear least squares. If not needed for computing the Jacobian this can safely be ignored.

Returns:

The Jacobian matrix as a nxm numpy array, with n being the number of measurements and m being the number of state parameters being estimated

Return type:

ndarray

abstract update_state(update)[source]¶

Updates the current values based on the provided update vector.

The provided update vector is in the order according to order of the columns returned from compute_jacobian().

If the input is None then this method should set the state parameters to NaN to indicate to the rest of GIANT that the estimation failed.

Parameters:: update (Sequence | ndarray | None) – The vector of additive updates to apply or None to indicate that the fit failed
Return type:: None

converge(x, y, z)[source]¶

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)\)

Iterative non-linear least squares is performed by linearizing at each step about the current best estimate of the state. This means that for each iteration, the Jacobian matrix is computed based off the current best estimate of the state, and then used to form a linear approximation of the model using a Taylor expansion. The resulting estimate is a delta from the current state, so that it is typically applied by adding the resulting update state vector to the existing states (although in some instances such as for rotations, a more complicated update application may be needed.

Iterative non-linear least squares typically needs an adequate initial guess to ensure convergence, therefore, it is recommended that the state of the class be appropriately initialized before calling this method (what is appropriate is dependent on the PSF itself.

The iteration performed in this method can be controlled using the max_iter, atol, and rtol class attributes which control the maximum number of iterations to attempt for convergence, the absolute tolerance criteria for convergence, and the relative tolerance criteria for convergence respectively.

This method use compute_jacobian() to return the Jacobian matrix for the current estimate of the state vector and update_state() to apply the estimated update at each iteration step, therefore, these methods should expect the same order of state elements.

If the iteration diverges then this method will call update_state() with None as the argument, which should typically indicate that the state parameters should be set to NaN so that other GIANT algorithms are aware the PSF fit failed.

If save_residuals is set to True, then this function will return a vector of the residuals and the covariance matrix from the fit as numpy arrays. Otherwise it returns None, None.

Parameters:

x (ndarray) – The x locations of the expected values as a 1D array
y (ndarray) – The y locations of the expected values as a 1D array
z (ndarray) – The expected values to fit to as a 1D array

Returns:

Either (residuals, covariance) as (n,) and (m,m) arrays if save_residuals is True or (None, None).

Return type:

Tuple[Sequence | ndarray | None, Sequence | ndarray | None]

class giant.point_spread_functions.KernelBasedCallPSF[source]¶

This ABC adds concrete common functionality for applying the initialized PSF to 2D images to PointSpreadFunction.

The implementation that is shared by most PSFs for 2D images is stored in __call__(). This method, works by generating a square kernel of the PSF by a call to generate_kernel() and then convolving the kernel with the image. For most PSFs, this form will be used, although a few like Gaussian may have a further optimized call sequence.

class giant.point_spread_functions.KernelBasedApply1DPSF[source]¶

This ABC adds concrete common functionality for applying the initialized PSF to 1D scan lines to PointSpreadFunction.

The implementation that is shared by most PSFs for 1D scan lines is stored in apply_1d_sized(). This method, which isn’t part of the actual interface GIANT expects, is used for applying the specified PSF to 1D scan lines if the size of the required kernel is known. Therefore, when implementing method:apply_1d, all you need to do is calculate the required size of the 1D kernel and then dispatch to apply_1d_sized(). An example of this can be seen in Gaussian.

apply_1d_sized(image_1d, size, direction=None, step=1)[source]¶

Applies the defined PSF using the stored parameters to the 1D image scans provided with a given kernel size.

image_1d can be a 2D array but in that case each row will be treated as an independent 1D scan.

For non-symmetric PSFs, a direction argument can be supplied which should be the direction in the image of each scan line. This can be used to determine the appropriate cross-section of the PSF to use for applying to the 1D scans (if applicable). If no direction is provided then the x direction [1, 0] is assumed.

This method works by sampling the PSF in the (optionally) specified direction(s) centered around the centroid of the PSF according to the input size. These kernels are then applied to the input scan lines using a Fourier transform, and the resulting scan lines are returned.

Parameters:

image_1d (ndarray) – The scan line(s) to be blurred using the PSF
size (int) – The size of the kernel to use when convolving the PSF with the scan line
direction (ndarray | None) – The direction for the 1D cross section of the PSF. This should be either None, a length 2 array, or a shape nx2 array where n is the number of scan lines
step (Real) – The step size of the lines being blurred.

Returns:

an array containing the input after blurring with the defined PSF

Return type:

ndarray

class giant.point_spread_functions.Gaussian(sigma_x=1, sigma_y=0, size=None, amplitude=None, centroid_x=0, centroid_y=0, **kwargs)[source]¶

A class for representing and fitting a standard (non-rotated) 2D gaussian point spread function.

This class represents a 2D Gaussian function of the form

\[f(x, y) = A e^{\left(-\left[\frac{(x-x_0)^2}{2\sigma_x^2}+\frac{(y-y_0)^2}{2\sigma_y^2}\right]\right)}\]

where \(A\) is the amplitude of the PSF, \(\sigma_x\) is the Gaussian RMS width in the x direction, \(\sigma_y\) is the Gaussian RMS width in the y direction, and \((x_0,y_0)\) is the centroid of the Gaussian (location of the peak response).

This class can be used for both estimating a Gaussian fit to an observed PSF (using the fit() class method to create an instance) as well as for applying the represented PSF to 1D scan lines (using apply_1d()) and 2D images (using the call capabilities of an instance of this class). In addition, if generated from a fit to data, this class will store the residuals and statistics about the residuals of the fit if the class attribute save_residuals is set to True before calling fit().

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

Parameters:

sigma_x (Real | None) – The Gaussian RMS width in the x direction in pixels
sigma_y (Real | None) – 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
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 (Real | None) – 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 (Real | None) – 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 (Real | None) – 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.

classmethod fit(x, y, z)[source]¶

This fits a 2d gaussian function to a surface using least squares estimation.

The fit assumes that z = f(x, y) where f is the gaussian function (and thus z is the “height” of the gaussian function).

The fit performed is for a 2D gaussian function of the form

\[z = f(x, y) = A e^{\left(-\left[\frac{(x-x_0)^2}{2\sigma_x^2}+\frac{(y-y_0)^2}{2\sigma_y^2}\right]\right)}\]

The estimation in this function is performed by transforming the gaussian function into the logspace, which allows us to perform a true linear least squares fit without iteration but overweights the tails of the function. Therefore, it is best to constrain the data you are fitting to be near the peak of the PSF to ensure that too much noise is not being given extra weight in the fit.

If the fit is unsuccessful due to a rank deficient matrix or a fit of a hyperbolic surface the resulting data will be set to np.nan.

Parameters:

x (Sequence | ndarray) – The x values underlying the surface the PSF is to be fit to
y (Sequence | ndarray) – The y values underlying the surface the PSF is to be fit to
z (Sequence | ndarray) – The z or “height” values of the surface the PSF is to be fit to

Returns:

The initialized PSF with values according to the fit

Return type:

Gaussian

compute_jacobian(x, y, computed)[source]¶

This method computes the Jacobian of the PSF with respect to a change in the state.

It returns a mx5 matrix defined as

\[\mathbf{J} = \left[\begin{array}{ccccc} \frac{\partial f}{\partial x_0} & \frac{\partial f}{\partial y_0} & \frac{\partial f}{\partial \sigma_x} & \frac{\partial f}{\partial \sigma_y} & \frac{\partial f}{\partial A}\end{array}\right]=\left[\begin{array}{ccccc} \frac{x-x_0}{\sigma_x^2}f(x, y) & \frac{y-y_0}{\sigma_y^2}f(x, y) & \frac{(x-x_0)^2}{\sigma_x^3}f(x, y) & \frac{(y-y_0)^2}{\sigma_y^3}f(x, y) & \frac{f(x, y)}{A}\end{array}\right]\]

Parameters:

x (ndarray) – The x values to evaluate the Jacobian at as a length m array
y (ndarray) – The y values to evaluate the Jacobian at as a length m array
computed (ndarray) – The PSF evaluated at x and y as a length m array

Returns:

The Jacobian matrix as a mx5 numpy array

update_state(update)[source]¶

Updates the current values based on the provided update vector.

The provided update vector is in the order of \([x_0, y_0, \sigma_x, \sigma_y, A]\).

If the update vector is set to None then sets everything to NaN to indicate a bad fit.

Parameters:: update (Sequence | ndarray | None) – The vector of additive updates to apply
Return type:: None

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, \sigma_x, \sigma_y, A]\).

evaluate(x, y)[source]¶

This method evaluates the PSF at the given x and y.

This method is not intended to be used to apply the PSF for an image (use the callable capability of the class instead for this). Instead it simply computes the height of the PSF above the xy-plane at the requested locations.

Specifically, this method computes

\[z = f(x, y) = A e^{\left(-\left[\frac{(x-x_0)^2}{2\sigma_x^2}+\frac{(y-y_0)^2}{2\sigma_y^2}\right]\right)}\]

Parameters:

x (Sequence | ndarray) – The x locations the height of the PSF is to be calculated at.
y (Sequence | ndarray) – The y locations the height of the PSF is to be calculated at.

Returns:

A numpy array containing the height of the PSF at the requested locations the same shape as x and y.

Return type:

ndarray

class giant.point_spread_functions.GeneralizedGaussian(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, **kwargs)[source]¶

A class for representing and fitting a generalized (rotated) 2D gaussian point spread function.

This class represents a 2D Gaussian function of the form

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

where \(A\) is the amplitude of the PSF, \(a\) is the coefficient for \((x-x_0)^2\), \(c\) is the coefficient for \((y-y_0)^2\), \(b\) is the coefficient for \((x-x_0)(y-y_0)\), and \((x_0,y_0)\) is the centroid of the Gaussian (location of the peak response).

This is equivalent to a function of the form

\[\begin{split}f(x, y) = A e^{-\left[\begin{array}{cc} (x-x_0) & (y-y_0)\end{array}\right]\mathbf{B}\mathbf{S}\mathbf{B}^T \left[\begin{array}{c}(x-x_0) \\ (y-y_0)\end{array}\right]}\end{split}\]

where

\[\begin{split}\mathbf{B} = \left[\begin{array}{cc} \text{cos}(\theta) & -\text{sin}(\theta) \\ \text{sin}(\theta) & \text{cos}(\theta)\end{array}\right] \\ \mathbf{S} = \left[\begin{array}{cc} \frac{1}{\sigma_x^2} & 0 \\ 0 & \frac{1}{\sigma_y^2}\end{array}\right]\end{split}\]

\(\theta\) is the angle between the x-axis and the principal axis of the Gaussian, \(sigma_x\) is the Gaussian RMS width in the semi-major axis direction, and \(\sigma_x\) is the RMS width in the semi-minor axis direction.

When creating an instance of this class you can specify either a, b, c or sigma_x, sigma_y, theta and the class will convert and store appropriately. This class also allows you to retrieve either a, b, c or sigma_x, sigma_y, theta.

This class can be used for both estimating a Gaussian fit to an observed PSF (using the fit() class method to create an instance) as well as for applying the represented PSF to 1D scan lines (using apply_1d) and 2D images (using the *call* capabilities of an instance of this class). In addition, if generated from a fit to data, this class will store the residuals and statistics about the residuals of the fit if the class attribute :attr:`save_residuals() is set to True before calling fit().

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

Parameters:

a_coef (Real | None) – The a coefficient of the Gaussian polynomial
b_coef (Real | None) – The b coefficient of the Gaussian polynomial
c_coef (Real | None) – The c coefficient of the Gaussian polynomial
sigma_x (Real | None) – The Gaussian RMS width in the x direction in pixels
sigma_y (Real | None) – 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 (Real | None) – 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 (Real | None) – 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 (Real | None) – 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.
theta (Real | None) –

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

classmethod fit(x, y, z)[source]¶

This fits a generalized (rotated) 2d gaussian function to a surface using least squares estimation.

The fit assumes that z = f(x, y) where f is the gaussian function (and thus z is the “height” of the gaussian function).

The fit performed is for a generalized 2D gaussian function of the form

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

The estimation in this function is performed by transforming the gaussian function into the logspace, which allows us to perform a true linear least squares fit without iteration but overweights the tails of the function. Therefore, it is best to constrain the data you are fitting to be near the peak of the PSF to ensure that too much noise is not being given extra weight in the fit.

If the fit is unsuccessful due to a rank deficient matrix or a fit of a hyperbolic surface the resulting data will be set to np.nan.

Parameters:

x (Sequence | ndarray) – The x values underlying the data the gaussian surface is to be fit to
y (Sequence | ndarray) – The y values underlying the data the gaussian surface is to be fit to
z (Sequence | ndarray) – The z or “height” values for the gaussian surface

Returns:

The initialized PSF with values according to the fit

Return type:

GeneralizedGaussian

compute_jacobian(x, y, computed)[source]¶

This method computes the Jacobian of the PSF with respect to a change in the state.

This is used internally for computing the covariance. It returns a 5xn matrix defined as

\[\begin{split}\mathbf{J} = \left[\begin{array}{cccccc} \frac{\partial f}{\partial x_0} & \frac{\partial f}{\partial y_0} & \frac{\partial f}{\partial a} & \frac{\partial f}{\partial b} & \frac{\partial f}{\partial c} & \frac{\partial f}{\partial A} \end{array}\right]=\left[\begin{array}{c} \left(2a(x-x_0)+2b(y-y_0)\right)f(x, y) \\ \left(2c(y-y_0)+2b(x-x_0)\right)f(x, y) \\ -(x-x_0)^2f(x, y) \\ -2(x-x_0)(y-y_0)f(x, y) \\ -(y-y_0)^2f(x, y) \\ \frac{f(x, y)}{A} \end{array}\right]^T\end{split}\]

Parameters:

x (ndarray) – The x values to evaluate the Jacobian at as a length m array
y (ndarray) – The y values to evaluate the Jacobian at as a length m array
computed (ndarray) – The PSF evaluated at x and y as a length m array

Returns:

The Jacobian matrix as a 5xm numpy array

update_state(update)[source]¶

Updates the current values based on the provided update vector.

The provided update vector is in the order of \([x_0, y_0, a, b, c, A]\).

If the update vector is set to None then sets everything to NaN to indicate a bad fit.

Parameters:: update (Sequence | ndarray | None) – The vector of additive updates to apply
Return type:: None

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]\).

evaluate(x, y)[source]¶

This method evaluates the PSF at the given x and y.

This method is not intended to be used to apply the PSF for an image (use the callable capability of the class instead for this). Instead it simply computes the height of the PSF above the xy-plane at the requested locations.

Specifically, this method computes

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

Parameters:

x (Sequence | ndarray) – The x locations the height of the PSF is to be calculated at.
y (Sequence | ndarray) – The y locations the height of the PSF is to be calculated at.

Returns:

A numpy array containing the height of the PSF at the requested locations the same shape as x and y.

Return type:

ndarray

class giant.point_spread_functions.IterativeGaussian(sigma_x=1, sigma_y=0, size=None, amplitude=None, centroid_x=0, centroid_y=0, **kwargs)[source]¶

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

This class only differs from the Gaussian class in the way the fit() class method works. 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.

For more details about the model this works with, see the Gaussian documentation.

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

Parameters:

sigma_x (Real | None) – The Gaussian RMS width in the x direction in pixels
sigma_y (Real | None) – 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
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 (Real | None) – 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 (Real | None) – 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 (Real | None) – 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.

classmethod fit(x, y, z)[source]¶

This fits a 2d gaussian function to a surface using iterative non-linear least squares estimation.

The fit assumes that z = f(x, y) where f is the gaussian function (and thus z is the “height” of the gaussian function).

The fit performed is for a 2D gaussian function of the form

\[z = f(x, y) = A e^{\left(-\left[\frac{(x-x_0)^2}{2\sigma_x^2}+\frac{(y-y_0)^2}{2\sigma_y^2}\right]\right)}\]

The estimation in this function is performed iteratively. First, a transformed fit is performed using the Gaussian.fit() method. This initial fit is then refined using iterative non-linear least squares to remove biases that can be introduced in the transformed fit.

If the fit is unsuccessful due to a rank deficient matrix or a fit of a hyperbolic surface the resulting data will be set to np.nan.

Parameters:

x (Sequence | ndarray) – The x values underlying the surface the PSF is to be fit to
y (Sequence | ndarray) – The y values underlying the surface the PSF is to be fit to
z (Sequence | ndarray) – The z or “height” values of the surface the PSF is to be fit to

Returns:

The initialized PSF with values according to the fit

Return type:

IterativeGaussian

class giant.point_spread_functions.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)[source]¶

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) –

classmethod fit(x, y, z)[source]¶

This fits a 2d gaussian function to a surface using iterative non-linear least squares estimation.

The fit assumes that z = f(x, y) where f is the gaussian function (and thus z is the “height” of the gaussian function).

The fit performed is for a 2D gaussian function of the form

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

The estimation in this function is performed iteratively. First, the rough background is estimated and removed. Then, a transformed fit is performed using the super class’s fit method on the data with the rough background removed. This initial fit is then refined using iterative non-linear least squares on the original data to remove biases that might have been introduced in the non-iterative fit.

If the fit is unsuccessful due to a rank deficient matrix or a fit of a hyperbolic surface the resulting data will be set to np.nan.

Parameters:

x (Sequence | ndarray) – The x values underlying the surface the PSF is to be fit to
y (Sequence | ndarray) – The y values underlying the surface the PSF is to be fit to
z (Sequence | ndarray) – The z or “height” values of the surface the PSF is to be fit to

Returns:

The initialized PSF with values according to the fit

Return type:

IterativeGaussianWBackground

update_state(update)[source]¶

Updates the current values based on the provided update vector.

The provided update vector is in the order of \([x_0, y_0, \sigma_x, \sigma_y, A, B, C, D]\).

If the update vector is set to None then sets everything to NaN to indicate a bad fit.

Parameters:: update (Sequence | ndarray | None) – The vector of additive updates to apply
Return type:: None

compute_jacobian(x, y, computed)[source]¶

This method computes the Jacobian of the PSF with respect to a change in the state.

It returns a mx8 matrix defined as

\[\mathbf{J} = \left[\begin{array}{cccccccc} \frac{\partial f}{\partial x_0} & \frac{\partial f}{\partial y_0} & \frac{\partial f}{\partial \sigma_x} & \frac{\partial f}{\partial \sigma_y} & \frac{\partial f}{\partial A} & \frac{\partial f}{\partial B} & \frac{\partial f}{\partial C} & \frac{\partial f}{\partial D}\end{array}\right]=\left[\begin{array}{cccccccc} \frac{x-x_0}{\sigma_x^2}f(x, y) & \frac{y-y_0}{\sigma_y^2}f(x, y) & \frac{(x-x_0)^2}{\sigma_x^3}f(x, y) & \frac{(y-y_0)^2}{\sigma_y^3}f(x, y) & \frac{f(x, y)}{A} & x & y & 1\end{array}\right]\]

Parameters:

x (ndarray) – The x values to evaluate the Jacobian at as a length m array
y (ndarray) – The y values to evaluate the Jacobian at as a length m array
computed (ndarray) – The PSF evaluated at x and y as a length m array

Returns:

The Jacobian matrix as a mx8 numpy array

Return type:

ndarray

class giant.point_spread_functions.IterativeGeneralizedGaussian(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, **kwargs)[source]¶

A class for representing and fitting a generalized (rotated) 2D Gaussian point spread function using iterative non-linear least squares.

This class only differs from the GeneralizedGaussian class in the way the fit() class method works. 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.

For more details about the model this works with, see the GeneralizedGaussian documentation.

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.
theta (float) –

classmethod fit(x, y, z)[source]¶

This fits a 2d gaussian function to a surface using iterative non-linear least squares estimation.

The fit assumes that z = f(x, y) where f is the gaussian function (and thus z is the “height” of the gaussian function).

The fit performed is for a 2D gaussian function of the form

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

The estimation in this function is performed iteratively. First, a transformed fit is performed using the Gaussian.fit() method. This initial fit is then refined using iterative non-linear least squares to remove biases that can be introduced in the transformed fit.

If the fit is unsuccessful due to a rank deficient matrix or a fit of a hyperbolic surface the resulting data will be set to np.nan.

Parameters:

x (Sequence | ndarray) – The x values underlying the data the gaussian surface is to be fit to
y (Sequence | ndarray) – The y values underlying the data the gaussian surface is to be fit to
z (Sequence | ndarray) – The z or “height” values for the gaussian surface

Returns:

The initialized PSF with values according to the fit

Return type:

IterativeGeneralizedGaussian

class giant.point_spread_functions.IterativeGaussianWBackground(sigma_x=1, sigma_y=0, size=None, amplitude=None, centroid_x=0, centroid_y=0, bg_b_coef=None, bg_c_coef=None, bg_d_coef=None, **kwargs)[source]¶

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 Gaussian 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[\frac{(x-x_0)^2}{2\sigma_x^2}+\frac{(y-y_0)^2}{2\sigma_y^2}\right]\right)} + Bx+Cy+D\]

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

Parameters:

sigma_x (Real | None) – The Gaussian RMS width in the x direction in pixels
sigma_y (Real | None) – 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
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 (Real | None) – 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 (Real | None) – 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 (Real | None) – 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

classmethod fit(x, y, z)[source]¶

This fits a 2d gaussian function to a surface using iterative non-linear least squares estimation.

The fit assumes that z = f(x, y) where f is the gaussian function (and thus z is the “height” of the gaussian function).

The fit performed is for a 2D gaussian function of the form

\[z = f(x, y) = A e^{\left(-\left[\frac{(x-x_0)^2}{2\sigma_x^2}+\frac{(y-y_0)^2}{2\sigma_y^2}\right]\right)} +Bx+Cy+D\]

The estimation in this function is performed iteratively. First, the rough background is estimated and removed. Then, a transformed fit is performed using the super class’s fit method on the data with the rough background removed. This initial fit is then refined using iterative non-linear least squares on the original data to remove biases that might have been introduced in the non-iterative fit.

If the fit is unsuccessful due to a rank deficient matrix or a fit of a hyperbolic surface the resulting data will be set to np.nan.

Parameters:

x (Sequence | ndarray) – The x values underlying the surface the PSF is to be fit to
y (Sequence | ndarray) – The y values underlying the surface the PSF is to be fit to
z (Sequence | ndarray) – The z or “height” values of the surface the PSF is to be fit to

Returns:

The initialized PSF with values according to the fit

Return type:

IterativeGaussianWBackground

update_state(update)[source]¶

Updates the current values based on the provided update vector.

The provided update vector is in the order of \([x_0, y_0, \sigma_x, \sigma_y, A, B, C, D]\).

If the update vector is set to None then sets everything to NaN to indicate a bad fit.

Parameters:: update (Sequence | ndarray | None) – The vector of additive updates to apply
Return type:: None

compute_jacobian(x, y, computed)[source]¶

This method computes the Jacobian of the PSF with respect to a change in the state.

It returns a mx8 matrix defined as

\[\mathbf{J} = \left[\begin{array}{cccccccc} \frac{\partial f}{\partial x_0} & \frac{\partial f}{\partial y_0} & \frac{\partial f}{\partial \sigma_x} & \frac{\partial f}{\partial \sigma_y} & \frac{\partial f}{\partial A} & \frac{\partial f}{\partial B} & \frac{\partial f}{\partial C} & \frac{\partial f}{\partial D}\end{array}\right]=\left[\begin{array}{cccccccc} \frac{x-x_0}{\sigma_x^2}f(x, y) & \frac{y-y_0}{\sigma_y^2}f(x, y) & \frac{(x-x_0)^2}{\sigma_x^3}f(x, y) & \frac{(y-y_0)^2}{\sigma_y^3}f(x, y) & \frac{f(x, y)}{A} & x & y & 1\end{array}\right]\]

Parameters:

x (ndarray) – The x values to evaluate the Jacobian at as a length m array
y (ndarray) – The y values to evaluate the Jacobian at as a length m array
computed (ndarray) – The PSF evaluated at x and y as a length m array

Returns:

The Jacobian matrix as a mx8 numpy array

Return type:

ndarray

class giant.point_spread_functions.Moment(centroid_x=None, centroid_y=None, **kwargs)[source]¶

This class implements a moment based (center of illumination) algorithm for locating the centroid of a PSF.

This class implements a fully functional PSF object for GIANT, however, because it does not actually model how light is spread out, if applied to an image or scan lines it just returns the input unaltered. Also, since this isn’t actually an estimation, the covariance and residuals are undefined so these are always set to NaN.

Note:

This object can be biased toward the center of an image if it is applied naively. You must be careful in selecting which points to pass to this function.

Parameters:

centroid_x (Real | None) – The x component of the centroid in pixels
centroid_y (Real | None) – The y component of the centroid in pixels

centroid_x: float¶: The x location of the centroid

centroid_y: float¶: The y location of the centroid

apply_1d(image_1d, direction=None, step=1)[source]¶

Just returns the input scan lines as is.

Parameters:

image_1d (ndarray) – the scan lines to apply the PSF to
direction (Sequence | ndarray | None) – the direction of the scan lines
step (Real) – the step size of the scan lines

Returns:

the unaltered scan lines

Return type:

ndarray

generate_kernel()[source]¶

Returns a 3x3 array of zeros except the center which is one because this does nothing.

Returns:: The nothing kernel
Return type:: ndarray

evaluate(x, y)[source]¶

Returns an array of zeros the same shape of x/y.

Parameters:

x (Sequence | ndarray) – The x values to evaluate at
y (Sequence | ndarray) – The y values to evaluate at

Returns:

An array of zeros

Return type:

ndarray

classmethod fit(x, y, z)[source]¶

This function identifies the centroid of the PSF for the input data using a moment algorithm (center of illumination).

\[x_0 = \frac{\sum{\mathbf{x}\mathbf{I}}}{\sum{\mathbf{I}}} \qquad y_0 = \frac{\sum{\mathbf{y}\mathbf{I}}}{\sum{\mathbf{I}}}\]

Parameters:

x (Sequence | ndarray) – The x values underlying the surface the PSF is to be fit to
y (Sequence | ndarray) – The y values underlying the surface the PSF is to be fit to
z (Sequence | ndarray) – The z or “height” values of the surface the PSF is to be fit to

Returns:

An instance of the PSF that best fits the provided data

Return type:

Moment

property centroid: ndarray¶

The location of the center of the PSF as an (x, y) length 2 numpy array.

This property is used to enable the PSF class to be used in identifying the center of illumination in image processing (see ImageProcessing.centroiding).

Returns:: The (x, y) location of the peak of the PSF as a 1D numpy array

property residual_rss: Real | None¶

The rss of the residuals (undefined).

Returns:: NaN or None since this is undefined.

property residual_mean: Real | None¶

The mean of the residuals (undefined).

Returns:: NaN or None since this is undefined.

property residual_std: Real | None¶

The standard deviation of the residuals (undefined).

Returns:: NaN or None since this is undefined.

property covariance: Sequence | ndarray | None¶

The covariance of the fit (undefined).

Returns:: A 2x2 array of NaN or None since this is undefined.

volume()[source]¶

The volume is undefined for a moment PSF so just return 0

Returns:: 0
Return type:: float

Modules

`psf_meta`	Provides abstract base classes for the construction of Point Spread Function classes for GIANT.
`moments`	Defines a PSF object for estimating centroids using a moment (center-of-illumination) algorithm.
`gaussians`	Defines PSF subclasses for representing/fitting various forms of 2D Gaussian functions.

Concrete Classes

`Moment`	This class implements a moment based (center of illumination) algorithm for locating the centroid of a PSF.
`Gaussian`	A class for representing and fitting a standard (non-rotated) 2D gaussian point spread function.
`IterativeGaussian`	A class for representing and fitting a standard (non-rotated) 2D Gaussian point spread function using iterative non-linear least squares.
`IterativeGaussianWBackground`	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.
`GeneralizedGaussian`	A class for representing and fitting a generalized (rotated) 2D gaussian point spread function.
`IterativeGeneralizedGaussian`	A class for representing and fitting a generalized (rotated) 2D Gaussian point spread function using iterative non-linear least squares.
`IterativeGeneralizedGaussianWBackground`	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.

Abstract Classes

`PointSpreadFunction`	This abstract base class serves as the template for implementing a point spread function in GIANT.
`SizedPSF`	This ABC adds common functionality for a PSF where the required size can be determine algorithmically.
`KernelBasedCallPSF`	This ABC adds concrete common functionality for applying the initialized PSF to 2D images to `PointSpreadFunction`.
`KernelBasedApply1DPSF`	This ABC adds concrete common functionality for applying the initialized PSF to 1D scan lines to `PointSpreadFunction`.
`IterativeNonlinearLSTSQPSF`	This ABC defines common attributes, properties, and methods for Iterative Non-linear least squares estimation of a Point Spread function.
`IterativeNonlinearLSTSQwBackground`	This class provides support for estimating the superposition of the PSF and a linear background gradient.
`InitialGuessIterativeNonlinearLSTSQPSF`	This class provides a fit class method which generates the initial guess from a subclass and then converges to a better solution using iterative Nonlinear LSTSQ.
`InitialGuessIterativeNonlinearLSTSQPSFwBackground`	This class provides a fit class method which generates the initial guess from a subclass and then converges to a better solution using iterative Nonlinear LSTSQ including a background gradient.

Navigation

Related Topics

giant.point_spread_functions¶