Ellipse¶
- class photutils.isophote.Ellipse(image, geometry=None, threshold=0.1)[source]¶
Bases:
object
Class to fit elliptical isophotes to a galaxy image.
The isophotes in the image are measured using an iterative method described by Jedrzejewski (1987; MNRAS 226, 747). See the Notes section below for details about the algorithm.
- Parameters:
- image2D
ndarray
The image array.
- geometry
EllipseGeometry
instance orNone
, optional The optional geometry that describes the first ellipse to be fitted. If
None
, a defaultEllipseGeometry
instance is created centered on the image frame with ellipticity of 0.2 and a position angle of 90 degrees.- thresholdfloat, optional
The threshold for the object centerer algorithm. By lowering this value the object centerer becomes less strict, in the sense that it will accept lower signal-to-noise data. If set to a very large value, the centerer is effectively shut off. In this case, either the geometry information supplied by the
geometry
parameter is used as is, or the fit algorithm will terminate prematurely. Note that once the object centerer runs successfully, the (x, y) coordinates in thegeometry
attribute (anEllipseGeometry
instance) are modified in place. The default is 0.1.
- image2D
Notes
The image is measured using an iterative method described by Jedrzejewski (1987; MNRAS 226, 747). Each isophote is fitted at a pre-defined, fixed semimajor axis length. The algorithm starts from a first-guess elliptical isophote defined by approximate values for the (x, y) center coordinates, ellipticity, and position angle. Using these values, the image is sampled along an elliptical path, producing a 1-dimensional function that describes the dependence of intensity (pixel value) with angle (E). The function is stored as a set of 1D numpy arrays. The harmonic content of this function is analyzed by least-squares fitting to the function:
\[y = y0 + (A1 * \sin(E)) + (B1 * \cos(E)) + (A2 * \sin(2 * E)) + (B2 * \cos(2 * E))\]Each one of the harmonic amplitudes (A1, B1, A2, and B2) is related to a specific ellipse geometric parameter in the sense that it conveys information regarding how much the parameter’s current value deviates from the “true” one. To compute this deviation, the image’s local radial gradient has to be taken into account too. The algorithm picks up the largest amplitude among the four, estimates the local gradient, and computes the corresponding increment in the associated ellipse parameter. That parameter is updated, and the image is resampled. This process is repeated until any one of the following criteria are met:
the largest harmonic amplitude is less than a given fraction of the rms residual of the intensity data around the harmonic fit.
a user-specified maximum number of iterations is reached.
more than a given fraction of the elliptical sample points have no valid data in then, either because they lie outside the image boundaries or because they were flagged out from the fit by sigma-clipping.
In any case, a minimum number of iterations is always performed. If iterations stop because of reasons 2 or 3 above, then those ellipse parameters that generated the lowest absolute values for harmonic amplitudes will be used. At this point, the image data sample coming from the best fit ellipse is fitted by the following function:
\[y = y0 + (An * sin(n * E)) + (Bn * cos(n * E))\]with \(n = 3\) and \(n = 4\). The corresponding amplitudes (A3, B3, A4, and B4), divided by the semimajor axis length and local intensity gradient, measure the isophote’s deviations from perfect ellipticity (these amplitudes, divided by semimajor axis and gradient, are the actual quantities stored in the output
Isophote
instance).The algorithm then measures the integrated intensity and the number of non-flagged pixels inside the elliptical isophote, and also inside the corresponding circle with same center and radius equal to the semimajor axis length. These parameters, their errors, other associated parameters, and auxiliary information, are stored in the
Isophote
instance.Errors in intensity and local gradient are obtained directly from the rms scatter of intensity data along the fitted ellipse. Ellipse geometry errors are obtained from the errors in the coefficients of the first and second simultaneous harmonic fit. Third and fourth harmonic amplitude errors are obtained in the same way, but only after the first and second harmonics are subtracted from the raw data. For more details, see the error analysis in Busko (1996; ASPC 101, 139).
After fitting the ellipse that corresponds to a given value of the semimajor axis (by the process described above), the axis length is incremented/decremented following a pre-defined rule. At each step, the starting, first-guess, ellipse parameters are taken from the previously fitted ellipse that has the closest semimajor axis length to the current one. On low surface brightness regions (those having large radii), the small values of the image radial gradient can induce large corrections and meaningless values for the ellipse parameters. The algorithm has the ability to stop increasing semimajor axis based on several criteria, including signal-to-noise ratio.
See the
Isophote
documentation for the meaning of the stop code reported after each fit.The fit algorithm provides a k-sigma clipping algorithm for cleaning deviant sample points at each isophote, thus improving convergence stability against any non-elliptical structure such as stars, spiral arms, HII regions, defects, etc.
The fit algorithm has no way of finding where, in the input image frame, the galaxy to be measured is located. The center (x, y) coordinates need to be close to the actual center for the fit to work. An “object centerer” function helps to verify that the selected position can be used as starting point. This function scans a 10x10 window centered either on the (x, y) coordinates in the
EllipseGeometry
instance passed to the constructor of theEllipse
class, or, if any one of them, or both, are set toNone
, on the input image frame center. In case a successful acquisition takes place, theEllipseGeometry
instance is modified in place to reflect the solution of the object centerer algorithm.In some cases the object centerer algorithm may fail, even though there is enough signal-to-noise to start a fit (e.g., in objects with very high ellipticity). In those cases the sensitivity of the algorithm can be decreased by decreasing the value of the object centerer threshold parameter. The centerer works by looking to where a quantity akin to a signal-to-noise ratio is maximized within the 10x10 window. The centerer can thus be shut off entirely by setting the threshold to a large value >> 1 (meaning, no location inside the search window will achieve that signal-to-noise ratio).
A note of caution: the ellipse fitting algorithm was designed explicitly with an elliptical galaxy brightness distribution in mind. In particular, a well defined negative radial intensity gradient across the region being fitted is paramount for the achievement of stable solutions. Use of the algorithm in other types of images (e.g., planetary nebulae) may lead to inability to converge to any acceptable solution.
Methods Summary
fit_image
([sma0, minsma, maxsma, step, ...])Fit multiple isophotes to the image array.
fit_isophote
(sma[, step, conver, minit, ...])Fit a single isophote with a given semimajor axis length.
set_threshold
(threshold)Modify the threshold value used by the centerer.
Methods Documentation
- fit_image(sma0=None, minsma=0.0, maxsma=None, step=0.1, conver=0.05, minit=10, maxit=50, fflag=0.7, maxgerr=0.5, sclip=3.0, nclip=0, integrmode='bilinear', linear=None, maxrit=None, fix_center=False, fix_pa=False, fix_eps=False)[source]¶
Fit multiple isophotes to the image array.
This method loops over each value of the semimajor axis (sma) length (constructed from the input parameters), fitting a single isophote at each sma. The entire set of isophotes is returned in an
IsophoteList
instance.Note that the fix_XXX parameters act in unison. Meaning, if one of them is set via this call, the others will assume their default (False) values. This effectively overrides any settings that are present in the internal
EllipseGeometry
instance that is carried along as a property of this class. If an instance ofEllipseGeometry
was passed to this class’ constructor, that instance will be effectively overridden by the fix_XXX parameters in this call.- Parameters:
- sma0float, optional
The starting value for the semimajor axis length (pixels). This value must not be the minimum or maximum semimajor axis length, but something in between. The algorithm can’t start from the very center of the galaxy image because the modelling of elliptical isophotes on that region is poor and it will diverge very easily if not tied to other previously fit isophotes. It can’t start from the maximum value either because the maximum is not known beforehand, depending on signal-to-noise. The
sma0
value should be selected such that the corresponding isophote has a good signal-to-noise ratio and a clearly defined geometry. If set toNone
(the default), one of two actions will be taken: if aEllipseGeometry
instance was input to theEllipse
constructor, itssma
value will be used. Otherwise, a default value of 10. will be used.- minsmafloat, optional
The minimum value for the semimajor axis length (pixels). The default is 0.
- maxsmafloat or
None
, optional The maximum value for the semimajor axis length (pixels). When set to
None
(default), the algorithm will increase the semimajor axis until one of several conditions will cause it to stop and revert to fit ellipses with sma <sma0
.- stepfloat, optional
The step value used to grow/shrink the semimajor axis length (pixels if
linear=True
, or a relative value iflinear=False
). See thelinear
parameter. The default is 0.1.- converfloat, optional
The main convergence criterion. Iterations stop when the largest harmonic amplitude becomes smaller (in absolute value) than
conver
times the harmonic fit rms. The default is 0.05.- minitint, optional
The minimum number of iterations to perform. A minimum of 10 (the default) iterations guarantees that, on average, 2 iterations will be available for fitting each independent parameter (the four harmonic amplitudes and the intensity level). For the first isophote, the minimum number of iterations is 2 *
minit
to ensure that, even departing from not-so-good initial values, the algorithm has a better chance to converge to a sensible solution.- maxitint, optional
The maximum number of iterations to perform. The default is 50.
- fflagfloat, optional
The acceptable fraction of flagged data points in the sample. If the actual fraction of valid data points is smaller than this, the iterations will stop and the current
Isophote
will be returned. Flagged data points are points that either lie outside the image frame, are masked, or were rejected by sigma-clipping. The default is 0.7.- maxgerrfloat, optional
The maximum acceptable relative error in the local radial intensity gradient. This is the main control for preventing ellipses to grow to regions of too low signal-to-noise ratio. It specifies the maximum acceptable relative error in the local radial intensity gradient. Busko (1996; ASPC 101, 139) showed that the fitting precision relates to that relative error. The usual behavior of the gradient relative error is to increase with semimajor axis, being larger in outer, fainter regions of a galaxy image. In the current implementation, the
maxgerr
criterion is triggered only when two consecutive isophotes exceed the value specified by the parameter. This prevents premature stopping caused by contamination such as stars and HII regions.A number of actions may happen when the gradient error exceeds
maxgerr
(or becomes non-significant and is set toNone
). If the maximum semimajor axis specified bymaxsma
is set toNone
, semimajor axis growth is stopped and the algorithm proceeds inwards to the galaxy center. Ifmaxsma
is set to some finite value, and this value is larger than the current semimajor axis length, the algorithm enters non-iterative mode and proceeds outwards until reachingmaxsma
. The default is 0.5.- sclipfloat, optional
The sigma-clip sigma value. The default is 3.0.
- nclipint, optional
The number of sigma-clip iterations. The default is 0, which means sigma-clipping is skipped.
- integrmode{‘bilinear’, ‘nearest_neighbor’, ‘mean’, ‘median’}, optional
The area integration mode. The default is ‘bilinear’.
- linearbool, optional
The semimajor axis growing/shrinking mode. If
False
(default), the geometric growing mode is chosen, thus the semimajor axis length is increased by a factor of (1. +step
), and the process is repeated until either the semimajor axis value reaches the value of parametermaxsma
, or the last fitted ellipse has more than a given fraction of its sampled points flagged out (seefflag
). The process then resumes from the first fitted ellipse (atsma0
) inwards, in steps of (1./(1. +step
)), until the semimajor axis length reaches the valueminsma
. In case of linear growing, the increment or decrement value is given directly bystep
in pixels. Ifmaxsma
is set toNone
, the semimajor axis will grow until a low signal-to-noise criterion is met. Seemaxgerr
.- maxritfloat or
None
, optional The maximum value of semimajor axis to perform an actual fit. Whenever the current semimajor axis length is larger than
maxrit
, the isophotes will be extracted using the current geometry, without being fitted. This non-iterative mode may be useful for sampling regions of very low surface brightness, where the algorithm may become unstable and unable to recover reliable geometry information. Non-iterative mode can also be entered automatically whenever the ellipticity exceeds 1.0 or the ellipse center crosses the image boundaries. IfNone
(default), then no maximum value is used.- fix_centerbool, optional
Keep center of ellipse fixed during fit? The default is False.
- fix_pabool, optional
Keep position angle of semi-major axis of ellipse fixed during fit? The default is False.
- fix_epsbool, optional
Keep ellipticity of ellipse fixed during fit? The default is False.
- Returns:
- result
IsophoteList
instance A list-like object of
Isophote
instances, sorted by increasing semimajor axis length.
- result
- fit_isophote(sma, step=0.1, conver=0.05, minit=10, maxit=50, fflag=0.7, maxgerr=0.5, sclip=3.0, nclip=0, integrmode='bilinear', linear=False, maxrit=None, noniterate=False, going_inwards=False, isophote_list=None)[source]¶
Fit a single isophote with a given semimajor axis length.
The
step
andlinear
parameters are not used to actually grow or shrink the current fitting semimajor axis length. They are necessary so the sampling algorithm can know where to start the gradient computation and also how to compute the elliptical sector areas (when area integration mode is selected).- Parameters:
- smafloat
The semimajor axis length (pixels).
- stepfloat, optional
The step value used to grow/shrink the semimajor axis length (pixels if
linear=True
, or a relative value iflinear=False
). See thelinear
parameter. The default is 0.1.- converfloat, optional
The main convergence criterion. Iterations stop when the largest harmonic amplitude becomes smaller (in absolute value) than
conver
times the harmonic fit rms. The default is 0.05.- minitint, optional
The minimum number of iterations to perform. A minimum of 10 (the default) iterations guarantees that, on average, 2 iterations will be available for fitting each independent parameter (the four harmonic amplitudes and the intensity level). For the first isophote, the minimum number of iterations is 2 *
minit
to ensure that, even departing from not-so-good initial values, the algorithm has a better chance to converge to a sensible solution.- maxitint, optional
The maximum number of iterations to perform. The default is 50.
- fflagfloat, optional
The acceptable fraction of flagged data points in the sample. If the actual fraction of valid data points is smaller than this, the iterations will stop and the current
Isophote
will be returned. Flagged data points are points that either lie outside the image frame, are masked, or were rejected by sigma-clipping. The default is 0.7.- maxgerrfloat, optional
The maximum acceptable relative error in the local radial intensity gradient. When fitting a single isophote by itself this parameter doesn’t have any effect on the outcome.
- sclipfloat, optional
The sigma-clip sigma value. The default is 3.0.
- nclipint, optional
The number of sigma-clip iterations. The default is 0, which means sigma-clipping is skipped.
- integrmode{‘bilinear’, ‘nearest_neighbor’, ‘mean’, ‘median’}, optional
The area integration mode. The default is ‘bilinear’.
- linearbool, optional
The semimajor axis growing/shrinking mode. When fitting just one isophote, this parameter is used only by the code that define the details of how elliptical arc segments (“sectors”) are extracted from the image when using area extraction modes (see the
integrmode
parameter).- maxritfloat or
None
, optional The maximum value of semimajor axis to perform an actual fit. Whenever the current semimajor axis length is larger than
maxrit
, the isophotes will be extracted using the current geometry, without being fitted. This non-iterative mode may be useful for sampling regions of very low surface brightness, where the algorithm may become unstable and unable to recover reliable geometry information. Non-iterative mode can also be entered automatically whenever the ellipticity exceeds 1.0 or the ellipse center crosses the image boundaries. IfNone
(default), then no maximum value is used.- noniteratebool, optional
Whether the fitting algorithm should be bypassed and an isophote should be extracted with the geometry taken directly from the most recent
Isophote
instance stored in theisophote_list
parameter. This parameter is mainly used when running the method in a loop over different values of semimajor axis length, and we want to change from iterative to non-iterative mode somewhere along the sequence of isophotes. When set toTrue
, this parameter overrides the behavior associated with parametermaxrit
. The default isFalse
.- going_inwardsbool, optional
Parameter to define the sense of SMA growth. When fitting just one isophote, this parameter is used only by the code that defines the details of how elliptical arc segments (“sectors”) are extracted from the image, when using area extraction modes (see the
integrmode
parameter). The default isFalse
.- isophote_listlist or
None
, optional If not
None
(the default), the fittedIsophote
instance is appended to this list. It must be created and managed by the caller.
- Returns:
- result
Isophote
instance The fitted isophote. The fitted isophote is also appended to the input list input to the
isophote_list
parameter.
- result