STScI Logo

ellipse stsdas.analysis.isophote


NAME · USAGE · DESCRIPTION · PARAMETERS · EXAMPLES · BUGS · REFERENCES
SEE_ALSO

NAME

ellipse -- Fit elliptical isophotes to galaxy images.

USAGE

ellipse in_image out_table

DESCRIPTION

The ellipse task fits elliptical isophotes to galaxy images --- this task performs the basic isophotal analysis used by other tasks in this package.

The task reads one 2-dimensional image section and produces as main output one table which contains 40 or more columns with parameters for each fitted isophote, one table row for each isophote. Optional products include a family of tables that contain each individual elliptical sample extracted from the image at each isophote, in the form intensity versus position angle, as well as individual plots of these samples. During the fitting process, some of the isophote parameters can be displayed in tabular form on the user's terminal screen (i.e., they are sent to STDOUT); these parameters allow the user to monitor the fitting process. The task can also be run in interactive mode, where the user has greater control over its operation.

The main output table content is described in more detail near the end of this section. For galaxy brightness profile analysis (1-D), see task fitting.nfit1d. For a more detailed description of some internal features of this task, use `help ellipse opt=sys'.

The image is measured using an iterative method described by Jedrzejewski (Mon.Not.R.Astr.Soc., 226, 747, 1987). Each isophote is fitted at a pre-defined, fixed semi-major axis length. The task starts from a first guess elliptical isophote defined by approximate values for the X and Y center coordinates, ellipticity and position angle. Using these values, the image is sampled along an elliptical path (see samplepar pset) producing a 1-dimensional intensity distribution as a function of position angle E. The harmonic content of this distribution 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, B2 is related to a specific ellipse geometric parameter, in the sense that it conveys information regarding how much the current parameter value deviates from the "true" one. To compute this deviation, the local image 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:
(1)
The largest harmonic amplitude is less than a given fraction of the rms residual of the intensity data around the harmonic fit.
(2)
A user-specified maximum number of iterations is reached.
(3)
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 where flagged out from the fit (see below).

In any case, a minimum number of iterations is always performed. See controlpar pset for details. 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 amplitudes (A3, B3, A4, B4), divided by the semi-major axis length and local intensity gradient, measure the isophote's deviations from perfect ellipticity (the amplitudes divided by semi-major axis and gradient, are the actual quantities written at the output table).

The task 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 semi-major axis length. These parameters, some other associated parameters, and some auxiliary information, are written to the output table(s). See magpar pset.

Optionally, the user can explicitly define a list of upper harmonics to be fitted to the best-fit intensity sample. The output table will contain additional columns with these harmonic amplitudes and their errors.

It must be emphasized that the algorithm was designed explicitly with a 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.

After fitting the ellipse that corresponds to a given value of the semi-major axis (by the process described above), the axis length is incremented/decremented following a pre-defined rule. At each step, the starting ellipse parameters are taken from the previously fitted ellipse that has the closest semi-major axis length to the current one. On low surface brightness regions (i.e., those having large radii), the small values of the image radial gradient can induce large corrections and meaningless values for the ellipse parameters. The task has capabilities to stop increasing semi-major axis based on several criteria, including signal-to-noise ratio. See the geompar pset for details.

Errors in intensity, magnitude and local gradient are obtained directly from the rms scatter of intensity data along the fitted ellipse. Ellipse geometry parameter errors are obtained from the internal errors in the harmonic fit, after removal of the first and second fitted harmonics. Harmonic amplitude errors are obtained from the fit error after removal of all harmonics up to, and including, the one being considered. See error analysis in Busko, I., 1996, Proceedings of the Fifth Astronomical Data Analysis Software and Systems Conference, Tucson, PASP Conference Series v.101, ed. G.H. Jacoby and J. Barnes, p.139-142.

Interactive mode can be used with either an image server (Ximtool/SAOimage) or standard IRAF graphics (stdgraph). In interactive mode, the task begins by automatically displaying the input image and waiting for cursor commands. The device task parameter selects the color of the graphics overlay on the gray-scale display, or the standard graphics output. Frame 1 of the image server is used. Due to limitations in the current graphics-image interface in IRAF, screen updates during cursor processing take a time proportional to the display buffer size. Small sizes (up to 512 x 512) are recommended.

Using cursor commands, the user can, at any time, list or modify most of the algorithm control parameters, as well as the current ellipse geometry. Functions as zoom, roam, reset, and limited gray-scale control, are also available. Pixel masking/unmasking can be done as well. The cursor comes back after each isophote fit, until the user chooses to continue in non-interactive mode, or until the minimum fitting semi-major axis is reached. Type help elcursor for a description of all available cursor commands.

Bad pixel flagging can be accomplished in a number of ways:

o
If a HST-style Data Quality File (DQF) is associated with the input image, it can be read by the task and used to flag pixels out from the fit. If only the DQF name extension is provided, task assumes DQF has the same root name as the main input image.
o
The task can also read a Bad Pixel Mask image, which is stored in the IRAF "pixel list" format. It has the same root name as the main input image, but with extension .pl. The task reads the bad pixel mask automatically at task startup, if available, and its contents can be modified, or it can be created from scratch, by interactive cursor commands. This automatic recognition of the bad pixel mask only works when the input image name extension is three characters long, such as in "imh", "hhh" or "fit". The flagging of bad pixels in the mask file follows the same convention as the HST Data Quality Files: zeroed pixels in the bad pixel mask mean that the corresponding pixel in the science image is good; non-zero pixels in the mask mean that the corresponding science pixel should be rejected at fitting time.
o
The task provides also a k-sigma clipping algorithm for cleaning deviant sample points at each isophote, thus improving convergency stability against stars, defects, etc.

The task can be run in either memory-intensive or disk-intensive modes. Disk-intensive is not recommended unless as a last resort to overcome "Out of memory" problems, because it has a large penalty in execution speed. In memory-intensive mode the task reads the full input file image section as a real array in memory. If the object to be measured is small compared with the frame dimensions, the best approach to save memory is to directly input an appropriate subsection of the larger, original image. All input/output coordinate information can still be handled by the task in the original image's coordinate reference system. See the geompar pset for details.

Output directed to STDOUT is a table with one row for each isophote. Each row contains the following data: semi-major axis length, mean isophotal intensity and its rms, ellipticity and its error, position angle and its error, radial gradient relative error, number of valid data points used in the fit, number of flagged data points (either removed from the image or clipped out), number of iterations, and stop condition code. The stop code can have the following values:

     0 - normal.
     1 - less than pre-specified fraction of the extracted data 
         points are valid.
     2 - exceeded maximum number of iterations.
     3 - singular matrix in harmonic fit, results may not be valid.
         Also signals insufficient number of data points to fit.
     4 - small or wrong gradient, or ellipse diverged; subsequent
         ellipses at larger semi-major axis may have the same constant
         geometric parameters.
    -1 - isophote was saved before completion of fit (by a cursor 
         command in interactive mode).

The main output table also contains one row for each value of the semi-major axis length. The labeling of each column is as follows:

Column             -  Contents


SMA                -  semi-major axis length (pixel)
INTENS             -  mean isophotal intensity
INT_ERR            -  error in isophotal intensity (RMS / sqrt(NDATA))
PIX_VAR            -  estimate of pixel variance (RMS * sqrt(SAREA))
RMS                -  root-mean-square scatter around isophotal intensity
ELLIP              -  ellipticity
ELLIP_ERR          -  ellipticity error
PA                 -  position angle (degrees counterclokwise from +y)
PA_ERR             -  position angle error
X0, Y0             -  ellipse center (pixel)
X0_ERR, Y0_ERR     -  error of ellipse center
GRAD               -  local radial intensity gradient
GRAD_ERR           -  gradient error
GRAD_R_ERR         -  gradient relative error
RSMA               -  (semi-major axis length) ** 1/4
MAG                -  mean isophotal magnitude
MAG_LERR, MAG_UERR -  lower and upper magnitude errors
TFLUX_E            -  total flux enclosed by ellipse
TFLUX_C            -  total flux enclosed by circle
TMAG_E             -  total flux enclosed by ellipse, in magnitudes
TMAG_C             -  total flux enclosed by circle, in magnitudes
NPIX_E             -  total number of valid pixels inside ellipse
NPIX_C             -  total number of valid pixels inside circle
A3, B3             -  3rd harmonic deviations from ellipse
A4, B4             -  4th harmonic deviations from ellipse
A3_ERR, B3_ERR     -  3rd harmonic deviation errors
A4_ERR, B4_ERR     -  4th harmonic deviation errors
NDATA              -  number of valid data points on isophote
NFLAG              -  number of flagged data points on isophote
NITER              -  number of iterations
STOP               -  stop condition code
A_BIG              -  maximum (in abs. value ) among 1st and 2nd 
                      harmonic amplitudes
SAREA              -  average sector area on isophote (pixel)
AIn, BIn           -  optional n-th harmonic amplitudes
AIn_ERR, BIn_ERR   -  optional n-th harmonic amplitude errors

The input image name is written to the main output table header.

The task has also the capability to read in a table previously generated
by itself when applied to a given image, and use the ellipse geometry 
information in each table row to measure another (related) image. In
this mode the fitting algorithm is disabled and the task just extracts
photometry information from the image. This mode is activated by setting
task parameter 'inellip' to the name of the table that contains the
results of a former execution of the task. This feature is useful when
measuring paired images e.g. as in a multicolor set to derive color
indices and gradients.

PARAMETERS

input [file name]
Image section to be measured. If a .pl mask file exists in the same directory, a explicit extension should be provided in the input file name.
output [file name]
Main output table name.
(dqf = "") [file name]
Data Quality File name or extension. If set to "none", eventually existing DQF is ignored.
(inellip = "") [file name]
Input table in "ellipse" format, to be used in no-fit, photometry-only mode.
(geompar) [pset]
Pset with geometry-defining parameters.
(controlpar) [pset]
Pset with algorithm control parameters.
(samplepar) [pset]
Pset with sampling control parameters.
(magpar) [pset]
Pset with magnitude scale parameters.
(interactive = no) [boolean]
Run task in interactive mode ?
(device = "red") [string, allowed values: |stdgraph|white|red|green|blue|yellow]
Interactive device. For gray-scale image servers (Ximtool, SAOimage), use color of graphics overlay. Server process must be already activated at workstation. For standard IRAF line-graphics, use stdgraph.
(icommands = "") [*imcur]
Optional file with image cursor commands. If left empty, task will read standard "imcur" input when in interactive mode.
(gcommands = "") [*gcur]
Optional file with graphics cursor commands. If left empty, task will read standard "gcur" input when in interactive mode.
(masksz = 5) [int, min=1]
Size of pixel masking area when m cursor command not in region mode.
(region = no) [boolean]
Pixel masking by m cursor key is in region mode ?
(verbose = yes) [boolean]
List summary at STDOUT ?

EXAMPLES

BUGS

REFERENCES

This task was written by I.Busko

SEE ALSO

elcursor, geompar, controlpar, samplepar, magpar, nfit1d.

For a more detailed description of some internal features of this task, use `help ellipse option=sysdoc'.


Source Code · Package Help · Search Form · STSDAS