| ecidentify | noao.imred.echelle | ecidentify |
ecidentify -- Determine the dispersion relation in echelle spectra
ecidentify images
cl> help onedspec.package section=units
If no units are specified and a coordinate list is used then the units of the coordinate list are selected. If a database entry exists then the units defined there override both this parameter and the coordinate list.
The following parameters are used in determining feature positions.
The following default parameters are used when fitting a function to the user coordinates. If a previous solution is read from the database then the parameters from that solution override the defaults below.
The following parameters control the graphics input and output.
ECIDENTIFY CURSOR KEY AND COLON COMMAND SUMMARY
? Help a Affect all features c Center feature(s)
d Delete feature(s) f Fit dispersion g Fit zero point shift
i Initialize j Go to previous order k Go to next order
l Match coordinate list m Mark feature n Next feature
o Go to specified order p Pan graph q Quit
r Redraw graph s Shift feature t Reset position
u Enter user coordinate w Window graph x Crosscorrelate peaks
y Find peaks z Zoom graph . Nearest feature
+ Next feature - Previous feature I Interrupt
:show [file] :features [file] :coordlist [file]
:cradius [value] :threshold [value] :database [file]
:ftype [type] :fwidth [value] :image [image]
:labels [type] :match [value] :maxfeatures [value]
:minsep [value] :read [image] :write [image]
:zwidth [value]
ECHELLE DISPERSION FUNCTION FITTING COMMAND SUMMARY
? Help c Print coordinates d Delete point
f Fit dispersion o Fit with fixed order offset q Quit
r Redraw graph u Undelete point w Window graph
x Set ordinate y Set abscissa I Interrupt
:show :function [value] :highreject [value] :lowreject [value]
:niterate [value] :xorder [value] :yorder [value]
ECIDENTIFY CURSOR KEYS AND COLON COMMANDS
Parameters are shown or set with the following "colon commands", which may be abbreviated. To show the value of a parameter type the parameter name alone and to set a new value follow the parameter name by the value.
DISPERSION FUNCTION FITTING COMMANDS
Emission and absorption features in echelle format spectra (see apsum ) are identified interactively and from a line list and a dispersion function is determined. The results of the line identifications and dispersion function are stored in a database for further reference and for use with the tasks ecreidentify and ecdispcor . Also the reference spectrum keyword REFSPEC is added to the image header. This is used by refspectra and ecdispcor .
Each spectrum in the input list is identified in turn. Initially the order in the first image line is graphed. The user may change the displayed order with the j, k, and o keys. The initial feature list and dispersion function are read from the database if an entry exists. The features are marked on the graph. The image coordinates are in pixels unless a dispersion function is defined, in which case they are in user coordinate units (usually wavelength in Angstroms). The aperture number, pixel coordinate, coordinate function value, and user coordinate for the current feature are displayed on the status line.
For consistency the orders are always identified by their aperture numbers in this task and all other tasks. These are the identifications assigned when extracting the orders using the task apsum . If the user has assigned true order numbers as the aperture numbers then there is no distinction between aperture and order number. However, it is often the case that the aperture numbers are simply assigned sequentially and the true order numbers may not even be known. Initially the orders are the same as the apertures numbers but after fitting a dispersion function the true order numbers will be determined. This information is also recorded in the database and indicated in the graph titles but selecting an order to be graphed with o and the status line information is always in terms of the aperture number.
The graphics cursor is used to select features and perform various functions. A menu of the keystroke options and functions is printed with the key ?. The cursor keys and their functions are defined in the CURSOR KEYS sections and described further below. The standard cursor mode keys are also available to window and redraw the graph and to produce hardcopy "snaps".
There are two types of feature selection functions; defining new features and selecting previously defined features. The key m marks a new feature nearest the cursor position. The feature position is determined by the feature centering algorithm (see help for center1d ). The type of feature, emission or absorption, is set by the ftype parameter. If the new position is within a distance given by the parameter minsep of a previous feature it is considered to be the same feature and replaces the old feature (normally the position of the new feature will be exactly the same as the original feature). The coordinate list is searched for a match between the coordinate function value (when defined) and a user coordinate in the list. If a match is found it becomes the default user coordinate which the user may override. The new feature is marked on the graph and it becomes the current feature. The redefinition of a feature which is within the minimum separation may be used to set the user coordinate from the coordinate list. The key t allows setting the position of a feature to other than that found by the centering algorithm.
The y key applies a peak finding algorithm and up to the maximum number of features (maxfeatures ) are found. If there are more peaks only the strongest are kept. The peaks are then matched against the coordinate list to find user coordinate values.
To select a different feature as the current feature the keys ., n, +, and - are used. The . selects the feature nearest the cursor, the n and + select the next feature, and the - selects the previous feature relative to the current feature in the feature list as ordered by pixel coordinate. These keys are useful when redefining the user coordinate with the u key and when examining features in zoom mode. To change apertures (orders) the j, k, and o keys are used.
If four or more features are identified spanning the range of the data (in pixel coordinates and in order number) or if a coordinate function is defined then the l key may be used to identify additional features from a coordinate list. If a coordinate function is not defined the default function is fit to the user coordinates of the currently defined features. Then for each coordinate value in the coordinate list the pixel coordinate is determined and a search for a feature at that point is made. If a feature is found (based on the parameters ftype, fwidth , cradius , and threshold ) its user coordinate value based on the coordinate function is determined. If the coordinate function value matches the user coordinate from the coordinate list within the error limit set by the parameter match then the new feature is entered in the feature list. Up to a maximum number of features, set by the parameter maxfeatures , may be defined in this way. A new user coordinate function is fit to all the located features. Finally, the graph is redrawn in user coordinates with the additional features found from the coordinate list marked.
The f key fits a two dimensional function of the pixel coordinates and aperture number to the user coordinates. The type of function and the orders are initially set with the parameters function , xorder , and yorder . The value of the function for a particular pixel coordinate is called the function coordinate and each feature in the feature list has a function coordinate value. The fitted function also is used to convert pixel coordinates to user coordinates in the graph. Depending on the orders of the function four or more features are required covering at least two orders. A description of the dispersion function fitting is given the section ECHELLE DISPERSION FUNCTION FITTING.
If a zero point shift is desired without changing the coordinate function the user may specify the coordinate of a point in the spectrum with the s key from which a shift is determined. The g key also determines a shift by minimizing the difference between the user coordinates and the fitted coordinates. This is used when a previously determined coordinate function is applied to a new spectrum having fewer or poorer lines and only a zero point shift can reasonably be determined. Note that the zero point shift is in user coordinates for the fundamental order. The shift for any particular order is then the zero point shift divided by the order number.
Features may be delete with the key d. All features are deleted when the a key immediately precedes the delete key. Deleting the features does not delete the coordinate function. To delete both the features and the dispersion function the initialize key i is used. Note features deleted during dispersion function fitting also are removed from the feature list upon exiting the fitting package.
It is common to transfer the feature identifications and coordinate function from one image to another. When a new image without a database entry is examined, such as when going to the next image in the input list or selecting a new image with the ":image" command, the current feature list and coordinate function are kept. Alternatively, a database record from a different image may be read with the ":read" command. When transfering feature identifications between images the feature coordinates will not agree exactly with the new image feature positions and several options are available to reregister the feature positions. The key c centers the feature nearest the cursor using the current position as the starting point. When preceded with the a key all the features are recentered (the user must refit the coordinate function if desired). As an aside, the recentering function is also useful when the parameters governing the feature centering algorithm are changed.
The (c)entering function is applicable when the shift between the current and true feature positions is small. Larger shifts may be determined automatically with the x function which correlates features in the image with the feature list. The features are then recentered. A zero point shift may also be given interactively with the s key by using the cursor to indicate the coordinate of a point in the spectrum. If there are no features then the shift is exactly as marked by the cursor but if there are features the approximate shift is applied and then the features are recentered. The shift is then the mean shift of the features after recentering. The shift is used as a zero point offset added to the dispersion function. The shift is computed in user coordinates for the fundamental order. Shifts for each order are given by scaling of this shift.
In addition to the single keystroke commands there are commands initiated by the key : (colon commands). As with the keystroke commands there are a number of standard graphics features available begining with ":." (type ":.help" for these commands). The colon commands allow the task parameter values to be listed and to be reset within the task. A parameter is listed by typing its name. The colon command ":show" lists all the parameters. A parameter value is reset by typing the parameter name followed by the new value; for example ":match 10". Other colon commands display the feature list (:features), control reading and writing records to the database (:read and :write), and set the graph display format.
The feature identification process for an image is completed by typing q to quit. Attempting to quit an image without explicitly recording changes in the feature database produces a warning message and an opportunity to record the information in the database. As an immediate exit the I interrupt key may be used. This does not save the feature information.
If a minimum of four features over at least two orders, depending on the default function orders, have been identified a dispersion function relating the user coordinates to the extracted pixel coordinate and aperture number may be fit. However, more features are preferable to determine changes in the dispersion as a function of position and order.
The form of the function fit explicitly includes the basic order number dependence of echelle spectra; namely the wavelength of a particular point along the dispersion direction in different orders varies as the reciprocal of the order number. Because of distortions, the differing extraction paths through the two dimensional image, and rotations of the spectra relative to the axis of constant dispersion (i.e. aligning the orders with the image columns or lines instead of aligning the emission and absorption features) there will be residual dependences on the extracted pixel positions and orders. These residual dependences are fit by a two dimensional polynomial of arbitrary order including cross terms. Because the basic order number dependence has been removed the orders should be relatively low. Currently the functions are bi-dimensional chebyshev and legendre polynomials though other function may be added in the future.
Since the true order number may not be known initially a linear relation between the aperture numbers and the order numbers is also determined which minimizes the residuals. This relation allows an unknown offset and possible a reversed direction of increasing order. The fitted function is then represented as:
y = offset +/- aperture wavelength = f (x, y) / y
where y is the order number and x is the extracted pixel coordinate along the dispersion.
If the order offset is known initially or as a result of previous the o fit may be used. The dispersion minimization for the order offset is then not done. This will, therefore, be faster than using the full fit, key f, to also determine the order offset.
The fitting is done interactively as a submode of ecidentify with its own set of cursor commands. It is entered using the f key and exited using the q key. The list of commands is given the CURSOR KEY section and is available from the fitting mode with ?. The functionality of this fitting is fairly simple; the function and orders may be changed, points may be deleted and undeleted, and the results of the fit may be displayed in various formats by selecting quantities to be plotted along either axis. Generally one changes plotting of the pixel coordinate, order number, and wavelength along the x axis and residuals or radial velocity errors along the y axis. One switches between increasing the x order and the y order while switching between plotting verses x positions and order number until the residuals have been reduced to remove all systematic trends.
The database specified by the parameter database is a directory of simple text files. The text files have names beginning with ec followed by the entry name, usually the name of the image. The database text files consist of a number of records. A record begins with a line starting with the keyword "begin". The rest of the line is the record identifier. Records read and written by ecidentify have "ecidentify" as the first word of the identifier. Following this is a name which may be specified following the ":read" or ":write" commands. If no name is specified then the image name is used. The lines following the record identifier contain the feature information and dispersion function coefficients.
The fitted echelle dispersion functions are evaluated as described in this section. The basic equations are
(1) w = (f(x,o) + shift) / o
(2) o = ap * slope + offset
where w is the wavelength, x is the pixel coordinate along the order, o is the order, and ap is the aperture number. The database parameter "shift" provides a wavelength zero point shift and the parameters "slope" and "offset" provide the transformation between aperture number and order. Note that the function f(x,o) and the shift are in terms of first order wavelengths.
The database entries contain "parameter value" pairs. This includes the parameters "shift", "offset", and "slope" defined above. The default values for these if they are absent are 0, 0, and 1 respectively. The "coefficients" parameter specifies the number of coefficients that follow and define the first order wavelength dispersion function. The coefficients and functions are described below.
The numerical values following the "coefficients" parameter, shown in the order in which they appear, have the following meaning.
type Function type: 1=chebychev, 2=legendre
xpow Highest power of x
opow Highest power of o
xterms Type of cross terms: Always 1 for echelle functions
xmin Minimum x for normalization
xmax Maximum x for normalization
omin Minimum o for normalization
omax Maximum o for normalization
Cmn Coefficients: m=0-xpow, n=0-opow, m varies first
The functions are evaluated by a sum over m and n up to the specified highest powers.
(3) f(x,o) = sum {Cmn * Pm * Pn} m=0-xpow, n=0-opow
The Cmn are the coefficients of the polynomial terms Pm and Pn which are defined as follows.
Chebyshev:
xnorm = (2 * x - (xmax + xmin)) / (xmax - xmin)
P0 = 1.0
P1 = xnorm
Pm+1 = 2.0 * xnorm * Pm - Pm-1
onorm = (2 * o - (omax + omin)) / (omax - omin)
P0 = 1.0
P1 = onorm
Pn+1 = 2.0 * onorm * Pn - Pn-1
Legendre:
xnorm = (2 * x - (xmax + xmin)) / (xmax - xmin)
P0 = 1.0
P1 = xnorm
Pm+1 = ((2m + 1) * xnorm * Pm - m * Pm-1)/ (m + 1)
onorm = (2 * o - (omax + omin)) / (omax - omin)
P0 = 1.0
P1 = onorm
Pn+1 = ((2n + 1) * onorm * Pn - n * Pn-1)/ (n + 1)
Note that the polynomial terms are obtained by first normalizing the x and o values to the range -1 to 1 and then iteratively evaluating them.
Because this task is interactive it is difficult to provide an actual example. The following describes a typical usage on arc spectra.
cl> ecidentify arc1.ec,arc2.ec
apsum, center1d, gtools, ecreidentify, identify