FittableImageModel

class photutils.psf.FittableImageModel[source]

Bases: astropy.modeling.Fittable2DModel

A fittable 2D model of an image allowing for image intensity scaling and image translations.

This class takes 2D image data and computes the values of the model at arbitrary locations (including at intra-pixel, fractional positions) within this image using spline interpolation provided by RectBivariateSpline.

The fittable model provided by this class has three model parameters: an image intensity scaling factor (flux) which is applied to (normalized) image, and two positional parameters (x_0 and y_0) indicating the location of a feature in the coordinate grid on which the model is to be evaluated.

If this class is initialized with flux (intensity scaling factor) set to None, then flux is going to be estimated as sum(data).

Parameters:

data : numpy.ndarray

Array containing 2D image.

origin : tuple, None, optional

A reference point in the input image data array. When origin is None, origin will be set at the middle of the image array.

If origin represents the location of a feature (e.g., the position of an intensity peak) in the input data, then model parameters x_0 and y_0 show the location of this peak in an another target image to which this model was fitted. Fundamentally, it is the coordinate in the model’s image data that should map to coordinate (x_0, y_0) of the output coordinate system on which the model is evaluated.

Alternatively, when origin is set to (0,0), then model parameters x_0 and y_0 are shifts by which model’s image should be translated in order to match a target image.

normalize : bool, optional

Indicates whether or not the model should be build on normalized input image data. If true, then the normalization constant (N) is computed so that

\[N \cdot C \cdot \Sigma_{i,j}D_{i,j} = 1,\]

where N is the normalization constant, C is correction factor given by the parameter normalization_correction, and \(D_{i,j}\) are the elements of the input image data array.

normalization_correction : float, optional

A strictly positive number that represents correction that needs to be applied to model’s data normalization (see C in the equation in the comments to normalize for more details).

A possible application for this parameter is to account for aperture correction. Assuming model’s data represent a PSF to be fitted to some target star, we set normalization_correction to the aperture correction that needs to be applied to the model. That is, normalization_correction in this case should be set to the ratio between the total flux of the PSF (including flux outside model’s data) to the flux of model’s data. Then, best fitted value of the flux model parameter will represent an aperture-corrected flux of the target star.

fill_value : float, optional

The value to be returned by the evaluate or astropy.modeling.Model.__call__ methods when evaluation is performed outside the definition domain of the model.

ikwargs : dict, optional

Additional optional keyword arguments to be passed directly to the compute_interpolator method. See compute_interpolator for more details.

Attributes Summary

data Get original image data.
fill_value Fill value to be returned for coordinates outside of the domain of definition of the interpolator.
flux Intensity scaling factor for image data.
interpolator_kwargs Get current interpolator’s arguments used when interpolator was created.
normalization_constant Get normalization constant.
normalization_correction Set/Get flux correction factor.
normalization_status Get normalization status.
normalized_data Get normalized and/or intensity-corrected image data.
nx Number of columns in the data array.
ny Number of rows in the data array.
origin A tuple of x and y coordinates of the origin of the coordinate system in terms of pixels of model’s image.
oversampling The factor by which the stored image is oversampled.
param_names
shape A tuple of dimensions of the data array in numpy style (ny, nx).
x_0 X-position of a feature in the image in the output coordinate grid on which the model is evaluated.
x_origin X-coordinate of the origin of the coordinate system.
y_0 Y-position of a feature in the image in the output coordinate grid on which the model is evaluated.
y_origin Y-coordinate of the origin of the coordinate system.

Methods Summary

compute_interpolator([ikwargs]) Compute/define the interpolating spline.
evaluate(x, y, flux, x_0, y_0) Evaluate the model on some input variables and provided model parameters.

Attributes Documentation

data

Get original image data.

fill_value

Fill value to be returned for coordinates outside of the domain of definition of the interpolator. If fill_value is None, then values outside of the domain of definition are the ones returned by the interpolator.

flux

Intensity scaling factor for image data.

interpolator_kwargs

Get current interpolator’s arguments used when interpolator was created.

normalization_constant

Get normalization constant.

normalization_correction

Set/Get flux correction factor.

Note

When setting correction factor, model’s flux will be adjusted accordingly such that if this model was a good fit to some target image before, then it will remain a good fit after correction factor change.

normalization_status

Get normalization status. Possible status values are:

  • 0: Performed. Model has been successfuly normalized at user’s request.
  • 1: Failed. Attempt to normalize has failed.
  • 2: NotRequested. User did not request model to be normalized.
normalized_data

Get normalized and/or intensity-corrected image data.

nx

Number of columns in the data array.

ny

Number of rows in the data array.

origin

A tuple of x and y coordinates of the origin of the coordinate system in terms of pixels of model’s image.

When setting the coordinate system origin, a tuple of two int or float may be used. If origin is set to None, the origin of the coordinate system will be set to the middle of the data array ((npix-1)/2.0).

Warning

Modifying origin will not adjust (modify) model’s parameters x_0 and y_0.

oversampling

The factor by which the stored image is oversampled. I.e., an input to this model is multipled by this factor to yield the index into the stored image.

param_names = ('flux', 'x_0', 'y_0')
shape

A tuple of dimensions of the data array in numpy style (ny, nx).

x_0

X-position of a feature in the image in the output coordinate grid on which the model is evaluated.

x_origin

X-coordinate of the origin of the coordinate system.

y_0

Y-position of a feature in the image in the output coordinate grid on which the model is evaluated.

y_origin

Y-coordinate of the origin of the coordinate system.

Methods Documentation

compute_interpolator(ikwargs={})[source]

Compute/define the interpolating spline. This function can be overriden in a subclass to define custom interpolators.

Parameters:

ikwargs : dict, optional

Additional optional keyword arguments. Possible values are:

  • degree : int, tuple, optional
    Degree of the interpolating spline. A tuple can be used to provide different degrees for the X- and Y-axes. Default value is degree=3.
  • s : float, optional
    Non-negative smoothing factor. Default value s=0 corresponds to interpolation. See RectBivariateSpline for more details.

Notes

  • When subclassing FittableImageModel for the purpose of overriding compute_interpolator(), the evaluate() may need to overriden as well depending on the behavior of the new interpolator. In addition, for improved future compatibility, make sure that the overriding method stores keyword arguments ikwargs by calling _store_interpolator_kwargs method.
  • Use caution when modifying interpolator’s degree or smoothness in a computationally intensive part of the code as it may decrease code performance due to the need to recompute interpolator.
evaluate(x, y, flux, x_0, y_0)[source]

Evaluate the model on some input variables and provided model parameters.