FittableImageModel

class photutils.psf.FittableImageModel(data, *, flux=1.0, x_0=0.0, y_0=0.0, normalize=False, normalization_correction=1.0, origin=None, oversampling=1, fill_value=0.0, **kwargs)

Bases: 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:

datandarray

Array containing 2D image.

origintuple, 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.

normalizebool, 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 \sum\limits_{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_correctionfloat, 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. In the case of aperture correction, normalization_correction should be a value larger than one, as the total flux, including regions outside of the aperture, should be larger than the flux inside the aperture, and thus the correction is applied as an inversely multiplied factor.

fill_valuefloat, 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.

kwargsdict, optional

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

oversamplingint or array_like (int)

The integer oversampling factor(s) of the ePSF relative to the input stars along each axis. If oversampling is a scalar then it will be used for both axes. If oversampling has two elements, they must be in (y, x) order.

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
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	Names of the parameters that describe models of this type.
shape	A tuple of dimensions of the data array in numpy style (ny, nx).
x_0
x_origin	X-coordinate of the origin of the coordinate system.
y_0
y_origin	Y-coordinate of the origin of the coordinate system.

Methods Summary

compute_interpolator(**kwargs)	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 = Parameter('flux', value=1.0)

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 successfully 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.

An input to this model is multiplied by this factor to yield the index into the stored image.

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

Names of the parameters that describe models of this type.

The parameters in this tuple are in the same order they should be passed in when initializing a model of a specific type. Some types of models, such as polynomial models, have a different number of parameters depending on some other property of the model, such as the degree.

When defining a custom model class the value of this attribute is automatically set by the Parameter attributes defined in the class body.

shape

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

x_0 = Parameter('x_0', value=0.0)

x_origin

X-coordinate of the origin of the coordinate system.

y_0 = Parameter('y_0', value=0.0)

y_origin

Y-coordinate of the origin of the coordinate system.

Methods Documentation

compute_interpolator(**kwargs)

Compute/define the interpolating spline.

This function can be overridden in a subclass to define custom interpolators.

Parameters:

**kwargsdict, optional

Additional optional keyword arguments:

• degreeint, 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.

• sfloat, 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 overridden 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 kwargs 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, *, use_oversampling=True)

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

Parameters:

use_oversamplingbool, optional

Whether to use the oversampling factor to calculate the model pixel indices. The default is True, which means the input indices will be multiplied by this factor.