samplepar -- Set the image sampling parameters for the ellipse task.
This pset is used to set the image sampling parameters associated with the ellipse task. Sampling is performed at each iteration of the isophote fitting algorithm, both to extract a trial intensity sample along an elliptical path, and to estimate the local radial intensity gradient. In this text, the term "intensity sample" refers to a two-column table, one column containing values of position angle and the other containing the intensity extracted at each angle. This data is complemented by the ellipse geometry (semi-major axis length, center coordinates, ellipticity, position angle).
Three methods are available for sampling an image along the elliptical path: bi-linear interpolation, and either mean or median over elliptical annulus sectors. These modes are selected using task parameter integrmode. Bi-linear interpolation extracts a 1-pixel width sample from the image. When using this technique, and when the distance between successive ellipses exceeds 2 pixels, many pixels will never be sampled. Integration over elliptical annuli can be used to overcome this problem and extract all information from the image array. The width of a given annulus is set from halfway between the present and previous ellipse to halfway between the present and next ellipse. Annuli are divided into sectors, and the angular step between successive sectors is such as to make their areas approximately constant over a given annulus. The angular span of a given sector is, however, restricted to a maximum of 12 degrees and a minimum of 3 degrees. Individual image pixels are considered to be inside a sector if the pixel geometric center is inside that sector, otherwise they are not counted. The resulting sample point for that particular sector will be the arithmetic mean or the median of all the (non-flagged) pixels inside the sector. If all pixels in the sector are flagged, the sample point will be flagged as INDEF.
If any sector vertex is outside the image boundary, its corresponding sample point is flagged as INDEF. The value of integrmode is ignored when the distance between the present ellipse and the next one is less than 2 pixels, or when the semi-major axis is less than 20 pixels; in these cases bi-linear interpolation is always used. In the particular case of semi-major axis less than 20 pixels, the interpolation includes a sub-pixel integration procedure, that better handles the steep intensity gradient found near a galaxy nucleus. The mean and median methods execute 3-5 times slower than bi-linear interpolation.
The basic convergency criterion discussed in the controlpar pset help page relies on comparison with the fit rms. Since the averaging modes (mean and median) effectively smooth the extracted samples, the increased number of pixels counted inside each sector as the algorithm proceeds outwards will induce a decrease of the rms residual against which harmonic amplitudes are compared, which translates into a variable convergency criterion along the isophote sequence. To overcome this problem, the actual comparison takes into account the sector area (kept approximately constant along the elliptical path). This average sector area is included in the task's main output table. Notice that the equivalent sector area for bi-linear interpolation is 2.0 pixels.
To increase stability in the convergency process, discrepant points in each sample can be found and flagged by a standard k-sigma clipping routine before submitting them to the harmonic fitting routine. The clipping routine is driven by parameters usclip and lsclip, the "k" amplitude factor (upper and lower), and nclip, the number of passes (iterations) over the sample. If set to zero, no clipping is performed.
Parameter fflag defines the maximum fraction of flagged data points which is acceptable in any given sample. If exceeded, the fitting algorithm stops increasing the semi-major axis. This happens usually when most of the sample is extracted from outside image boundaries.
The best-fit sample at each fitted isophote can be optionally plotted immediately after fitting, at the graphics device specified by task parameter sdevice. This feature is turned off if the task is run in interactive mode and the graphics devices for both interaction and sample plotting are the same. The supported graphics devices are either the standard screen and plot devices, as well as the standard spool file stdvdm. This last one is useful for automatic keeping a graphics hard-copy of each fitting session.
Samples corresponding to individual fitted isophotes can be optionally stored as a set of tables, to be used e.g. in subsequent plotting and analysis steps. Parameter tsample defines the root name of the table file family. Each table contains two columns, one with the sample angles in degrees, and the other with the intensity points. Ellipse data is also included in the table header.
The angles output to tables can be expressed in two coordinate systems: the "natural" ellipse system, in which angle origin corresponds to the upper semi-major axis endpoint, and "absolute", in which angle origin is the +y direction in the image frame. Selection among these systems is done by task parameter absangle. In either case, angles increase counterclockwise.
Optionally, the user can explicitly define which harmonics are to be fitted to the best-fit intensity sample. Task parameter harmonics is used to specify the optional harmonic numbers. Harmonic numbers must be integer and separated by spaces. They must be entered in ascending order, as in harmonics = "5 6 7 8". The main output table will contain additional columns with the harmonic amplitudes and errors. Note that, in this case, the amplitudes are NOT converted to geometric deviations from a perfect ellipse. Instead, they are written in raw intensity units. Third and fourth harmonics, as explained above, will still be written at their standard columns. These amplitudes can be converted into deviations from an ellipse by using task ttools.tcalc. Just divide the respective columns by columns labeled SMA and GRAD.
- (integrmode = "bi-linear") [string, allowed values: bi-linear|mean|median]
- Method used to sample the image.
- (usclip = 3.0) [real, min=0.0]
- k-sigma clipping criterion applied to deviant points above the average.
- (lsclip = 3.0) [real, min=0.0]
- k-sigma clipping criterion applied to deviant points below the average.
- (nclip = 0) [int, min=0]
- Number of iterations in the k-sigma clipping algorithm.
- (fflag = 0.5) [real, min=0.0, max=1.0]
- Acceptable fraction of flagged data points in intensity sample.
- (sdevice = "none") [string, allowed values: |none|stdgraph|stdplot|stdvdm]
- Graphics device for plotting intensity samples.
- (tsample = "none") [string]
- Root name for tables with intensity samples.
- (absangle = yes) [boolean]
- Sample angles refer to image coordinate system ?
- (harmonics = "none") [string]
- List of optional upper harmonics to fit to each intensity sample.