diff options
Diffstat (limited to 'noao/onedspec/doc/reidentify.hlp')
| -rw-r--r-- | noao/onedspec/doc/reidentify.hlp | 516 |
1 files changed, 516 insertions, 0 deletions
diff --git a/noao/onedspec/doc/reidentify.hlp b/noao/onedspec/doc/reidentify.hlp new file mode 100644 index 00000000..07eb2238 --- /dev/null +++ b/noao/onedspec/doc/reidentify.hlp @@ -0,0 +1,516 @@ +.help reidentify Jan96 noao.onedspec +.ih +NAME +reidentify -- Reidentify features +.ih +SUMMARY +Given a reference vector with identified features and (optionally) a +coordinate function find the same features in other elements of the +reference image and fit a new dispersion function or determine a +zero point shift. After all vectors of the reference image are +reidentified use the reference vectors to reidentify corresponding +vectors in other images. This task is used for transferring dispersion +solutions in arc calibration spectra and for mapping geometric and +dispersion distortion in two and three dimensional images. +.ih +USAGE +reidentify reference images +.ih +PARAMETERS +.ls reference +Image with previously identified features to be used as features reference for +other images. If there are multiple apertures, lines, or columns in the +image a master reference is defined by the \fIsection\fR parameter. +The other apertures in multispec images or other lines, or columns +(selected by \fIstep\fR) are reidentified as needed. +.le +.ls images +List of images in which the features in the reference image are to be +reidentified. In two and three dimensional images the reidentifications are +done by matching apertures, lines, columns, or bands with those in the reference +image. +.le +.ls interactive = no +Examine and fit features interactively? If the task is run interactively a +query (which may be turned off during execution) will be given for each +vector reidentified after printing the results of the automatic fit and the +user may chose to enter the interactive \fBidentify\fR task. +.le +.ls section = "middle line" +If the reference image is not one dimensional or specified as a one dimensional +image section then this parameter selects the master reference image +vector. The master reference is used when reidentifying other vectors in +the reference image or when other images contain apertures not present in +the reference image. This parameter also defines the direction +(columns, lines, or z) of the image vectors to be reidentified. + +The section parameter may be specified directly as an image section or +in one of the following forms + +.nf +line|column|x|y|z first|middle|last|# [first|middle|last|#]] +first|middle|last|# [first|middle|last|#] line|column|x|y|z +.fi + +where each field can be one of the strings separated by | except for # +which is an integer number. The field in [] is a second designator which +is used with three dimensional data. See the example section for +\fBidentify\fR for examples of this syntax. Abbreviations are allowed +though beware that 'l' is not a sufficient abbreviation. +.le +.ls newaps = yes +Reidentify new apertures in the images which are not in the reference +image? If no, only apertures found in the reference image will be +reidentified in the other images. If yes, the master reference spectrum +is used to reidentify features in the new aperture and then the +new aperture solution will be added to the reference apertures. All +further identifications of the new aperture will then use this solution. +.le +.ls override = no +Override previous solutions? If there are previous solutions for a +particular image vector being identified, because of a previous +\fBidentify\fR or \fBreidentify\fR, this parameter selects whether +to simply skip the reidentification or do a reidentification and +overwrite the solution in the database. +.le +.ls refit = yes +Refit the coordinate function? If yes and there is more than one feature +and a coordinate function was defined in the reference image database then a new +coordinate function of the same type as in the reference is fit +using the new pixel positions. Otherwise only a zero point shift is +determined for the revised coordinates without changing the +form of the coordinate function. +.le + +The following parameters are used for selecting and reidentifying additional +lines, columns, or apertures in two dimensional formats. +.ls trace = no +There are two methods for defining additional reference lines, columns, or +bands in two and three dimensional format images as selected by the +\fIstep\fR parameter. When \fItrace\fR is no the master reference line or +column is used for each new reference vector. When this parameter is yes +then as the reidentifications step across the image the last reidentified +features are used as the reference. This "tracing" is useful if there is a +coherent shift in the features such as with long slit spectra. However, +any features lost during the tracing will be lost for all subsequent lines +or columns while not using tracing always starts with the initial set of +reference features. +.le +.ls step = "10" +The step from the reference line, column, or band used for selecting and/or +reidentifying additional lines, columns, or bands in a two or three +dimensional reference image. For three dimensional images there may be two +numbers to allow independent steps along different axes. If the step is +zero then only the reference aperture, line, column, or band is used. For +multiaperture images if the step is zero then only the requested aperture +is reidentified and if it is non-zero (the value does not matter) then all +spectra are reidentified. For long slit or Fabry-Perot images the step is +used to sample the image and the step should be large enough to map any +significant changes in the feature positions. +.le +.ls nsum = "10" +Number of lines, columns, or bands across the designated vector axis to be +summed when the image is a two or three dimensional spatial spectrum. +It does not apply to multispec format spectra. If the image is three +dimensional an optional second number can be specified for the higher +dimensional axis (the first number applies to the lower axis number and +the second to the higher axis number). If a second number is not specified +the first number is used for both axes. This parameter is not used for +multispec type images. +.le +.ls shift = "0" +Shift in user coordinates to be added to the reference features before +centering. If the image is three dimensional then two numbers may be +specified for the two axes. Generally no shift is used by setting the +value to zero. When stepping to other lines, columns, or bands in the +reference image the shift is added to the primary reference spectrum if not +tracing. When tracing the shift is added to last spectrum when stepping to +higher lines and subtracted when stepping to lower lines. If a value +if INDEF is specified then an automatic algorithm is applied to find +a shift. +.le +.ls search = 0. +If the \fIshift\fR parameter is specified as INDEF then an automatic +search for a shift is made. There are two algorithms. If the search +value is INDEF then a cross-correlation of line peaks is done. Otherwise +if a non-zero value is given then a pattern matching algorithm (see +\fIautoidentify\fR) is used. A positive value specifies the search radius in +dispersion units and a negative value specifies a search radius as a +fraction of the reference dispersion range. +.le +.ls nlost = 0 +When reidentifying features by tracing, if the number of features not found +in the new image vector exceeds this number then the reidentification +record is not written to the database and the trace is terminated. A +warning is printed in the log and in the verbose output. +.le + +The following parameters define the finding and recentering of features. +See also \fBcenter1d\fR. +.ls cradius = 5. +Centering radius in pixels. If a reidentified feature falls further +than this distance from the previous line or column when tracing or +from the reference feature position when reidentifying a new image +then the feature is not reidentified. +.le +.ls threshold = 0. +In order for a feature center to be determined, the range of pixel +intensities around the feature must exceed this threshold. This parameter +is used to exclude noise peaks and terminate tracing when the signal +disappears. However, failure to properly set this parameter, particularly +when the data values are very small due to normalization or flux +calibration, is a common error leading to failure of the task. +.le + +The following parameters select and control the automatic addition of +new features during reidentification. +.ls addfeatures = no +Add new features from a line list during each reidentification? If +yes then the following parameters are used. This function can be used +to compensate for lost features from the reference solution, particularly +when tracing. Care should be exercised that misidentified features +are not introduced. +.le +.ls coordlist = "linelists$idhenear.dat" +User coordinate list consisting of a list of line coordinates. +Some standard line lists are available in the directory "linelists$". +The standard line lists are described under the topic \fIlinelists\fR. +.le +.ls match = -3. +The maximum difference for a match between the feature coordinate function +value and a coordinate in the coordinate list. Positive values +are in user coordinate units and negative values are in units of pixels. +.le +.ls maxfeatures = 50 +Maximum number of the strongest features to be selected automatically from +the coordinate list. +.le +.ls minsep = 2. +The minimum separation, in pixels, allowed between feature positions +when defining a new feature. +.le + +The following parameters determine the input and output of the task. +.ls database = "database" +Database containing the feature data for the reference image and in which +the features for the reidentified images are recorded. +.le +.ls logfiles = "logfile" +List of files in which to keep a processing log. If a null file, "", +is given then no log is kept. +.le +.ls plotfile = "" +Optional file to contain metacode plots of the residuals. +.le +.ls verbose = no +Print reidentification information on the standard output? +.le +.ls graphics = "stdgraph" +Graphics device. The default is the standard graphics device which is +generally a graphics terminal. +.le +.ls cursor = "" +Cursor input file. If a cursor file is not given then the standard graphics +cursor is read. +.le + +The following parameters are queried when the 'b' key is used in the +interactive review. +.ls crval, cdelt +These parameters specify an approximate coordinate value and coordinate +interval per pixel when the automatic line identification +algorithm ('b' key) is used. The coordinate value is for the +pixel specified by the \fIcrpix\fR parameter in the \fBaidpars\fR +parameter set. The default value of \fIcrpix\fR is INDEF which then +refers the coordinate value to the middle of the spectrum. By default +only the magnitude of the coordinate interval is used. Either value +may be given as INDEF. In this case the search for a solution will +be slower and more likely to fail. The values may also be given as +keywords in the image header whose values are to be used. +.le +.ls aidpars = "" (parameter set) +This parameter points to a parameter set for the automatic line +identification algorithm. See \fIaidpars\fR for further information. +.le +.ih +DESCRIPTION +Features (spectral lines, cross-dispersion profiles, etc.) identified in a +single reference vector (using the tasks \fBidentify\fR or +\fBautoidentify\fR) are reidentified in other reference vectors and the set +of reference vectors are reidentified in other images with the same type of +vectors. A vector may be a single one dimensional (1D) vector in a two or +three dimensional (2D or 3D) image, the sum of neighboring vectors to form +a 1D vector of higher signal, or 1D spectra in multiaperture images. The +number of vectors summed in 2D and 3D images is specified by the parameter +\fInsum\fR. This parameter does not apply to multiaperture images. + +As the previous paragraph indicates, there are two stages in this task. +The first stage is to identify the same features from a single reference +vector to a set of related reference vectors. This generally consists +of other vectors in the same reference image such as other lines or +columns in a long slit spectrum or the set of 1D aperture spectra in +a multiaperture image. In these cases the vectors are identified by +a line, column, band, or aperture number. The second stage is to +reidentify the features from the reference vectors in the matching +vectors of other images. For example the same lines in the reference +image and another image or the same apertures in several multiaperture +images. For multiaperture images the reference vector and target vector +will have the same aperture number but may be found in different image +lines. The first stage may be skipped if all the reference vectors +have been identified. + +If the images are 2D or 3D or multiaperture format and a \fIstep\fR greater +than zero is specified then additional vectors (lines/columns/bands) in the +reference image will be reidentified from the initial master reference +vector (as defined by an image section or \fIsection\fR parameter) provided +they have not been reidentified previously or the \fIoverride\fR flag is +set. For multiple aperture spectral images, called multiaperture, a step +size of zero means don't reidentify any other aperture and any other step +size reidentifies all apertures. For two and three dimensional images, +such as long slit and Fabry-Perot spectra, the step(s) should be large +enough to minimize execution time and storage requirements but small enough +to follow shifts in the features (see the discussion below on tracing). + +The reidentification of features in other reference image vectors +may be done in two ways selected by the parameter \fItrace\fR. If not +tracing, the initial reference vector is applied to the other selected +vectors. If tracing, the reidentifications are made with respect to the +last set of identifications as successive steps away from the reference +vector are made. The tracing method is appropriate for two and three +dimensional spatial images, such as long slit and Fabry-Perot spectra, in +which the positions of features traced vary smoothly. This allows +following large displacements from the initial reference by using suitably +small steps. It has the disadvantage that features lost during the +reidentifications will not propagate (unless the \fIaddfeatures\fR option +is used). By not tracing, the original set of features is used for every +other vector in the reference image. + +When tracing, the parameter \fInlost\fR is used to terminate the +tracing whenever this number of features has been lost. This parameter, +in conjunction with the other centering parameters which define +when a feature is not found, may be useful for tracing features +which disappear before reaching the limits of the image. + +When reidentifying features in other images, the reference +features are those from the same aperture, line, column, or band of the +reference image. However, if the \fInewaps\fR parameter is set +apertures in multiaperture spectra which are not in the reference +image may be reidentified against the master reference aperture and +added to the list of apertures to be reidentified in other images. +This is useful when spectra with different aperture numbers are +stored as one dimensional images. + +The reidentification of features between a reference vector and +a target vector is done as follows. First a mean shift between +the two vectors is determined. After correcting for the shift +the estimated pixel position of each reference feature in the +target vector is used as the starting point for determining +a feature center near this position. The centering fails the +feature is dropped and a check against the \fInlost\fR is made. +If it succeeds it is added to the list of features found in the +target spectrum. A zero point shift or new dispersion +function may be determined. New features may then be added from +a coordinate list. The details are given below. + +There may be a large shift between the two vectors such that the same +feature in the target vector is many pixels away from the pixel position in +the reference spectrum. A shift must then be determined. The \fIshift\fR +parameter may be used to specify a shift. The shift is in user coordinates +and is added to the reference user coordinates before trying to center +on a feature. For example if the reference spectrum has a feature at +5015A but in the new spectrum the feature is at 5025A when the reference +dispersion function is applied then the shift would be +10. Thus +a reference feature at 5015A would have the shift added to get 5025A, +then the centering would find the feature some pixel value and that +pixel value would be used with the true user coordinate of 5015A in the +new dispersion solution. + +When tracing a 2D/3D reference spectrum the shift is applied to the +previous reidentified spectrum rather than the initial reference spectrum. +The shift is added for increasing line or column values and subtracted for +decreasing line or column values. This allows "tracing" when there is a +rotation or tilt of the 2D or 3D spectrum. When not tracing the shift is +always added to the reference spectrum features as described previously. + +When reidentify other images with the reference spectrum the shift +parameter is always just added to the reference dispersion solution +matching the aperture, line, or column being reidentified. + +If the \fIshift\fR parameter is given as INDEF then an automatic +search algorithm is applied. There are two algorithms that may be +used. If the \fIsearch\fR parameter is INDEF then a cross-correlation +of the features list with the peaks found in the target spectrum is +performed. This algorithm can only find small shifts since otherwise +many lines may be missing off either end of the spectrum relative to +the reference spectrum. + +If the search parameter is non-zero then the pattern matching algorithm +described in \fIaidpars\fR is used. The search parameter specified a +search radius from the reference solution. If the value is positive the +search radius is a distance in dispersion units. If the value is negative +then the absolute value is used as a fraction of the dispersion range in +the reference solution. For example, a value of -0.1 applied to reference +dispersion solution with a range of 1000A would search for a new solution +within 100A of the reference dispersion solution. + +The pattern matching algorithm has to stages. First if there are +more than 10 features in the reference the pattern matching tries +to match the lines in the target spectrum to those features with +a dispersion per pixel having the same sign and a value within 2%. +If no solution is found then the \fIlinelist\fR is used to match +against the lines in the target spectrum, again with the dispersion +per pixel having the same sign and a value within 5%. The first +stage works when the set of features is nearly the same while the +second stage works when the shifts are large enough that many features +in the reference and target spectra are different. + +The centering algorithm is described under the topic \fIcenter1d\fR and +also in \fBidentify\fR. If a feature positions shifts by more than the +amount set by the parameter \fIcradius\fR from the starting position +(possibly after adding a shift) or the feature strength (peak to valley) is +less than the detection \fIthreshold\fR then the new feature is discarded. +The \fIcradius\fR parameter should be set large enough to find the correct +peak in the presence of any shifts but small enough to minimize incorrect +identifications. The \fIthreshold\fR parameter is used to eliminate +identifications with noise. Failure to set this parameter properly for the +data (say if data values are very small due to a calibration or +normalization operation) is the most common source of problems in using +this task. + +If a fitting function is defined for the features in the reference image, +say a dispersion function in arc lamp spectra, then the function is refit +at each reidentified line or column if the parameter \fIrefit\fR is yes. +If refitting is not selected then a zero point shift in the user +coordinates is determined without changing the form of the fitting +function. The latter may be desirable for tracking detector shifts through +a sequence of observation using low quality calibration spectra. When +refitting, the fitting parameters from the reference are used including +iterative rejection parameters to eliminate misidentifications. + +If the parameter \fIaddfeatures\fR is set additional features may be added +from a line list. If there are reference features then the new features +are added AFTER the initial reidentification and function fit. If the +reference consists only of a dispersion function, that is it has no +features, then new features will be added followed by a function fit and +then another pass of adding new features. A maximum number of added +features, a matching distance in user coordinates, and a minimum separation +from other features are additional parameters. This option is similar to +that available in \fBidentify\fR and is described more fully in the help +for that task. + +A statistics line is generated for each reidentified vector. The line +contains the name of the image being reidentified (which for two +dimensional images includes the image section and for multiaperture +spectra includes the aperture number), the number of features found +relative to the number of features in the reference, the number of +features used in the function fit relative to the number found, the +mean pixel, user coordinate, and fractional user coordinate shifts +relative to the reference coordinates, and the RMS relative to the +final coordinate system (whether refit or simply shifted) excluding any +iteratively rejected features from the calculation. + +If the task is run with the \fIinteractive\fR flag the statistics line +is printed to the standard output (the terminal) and a query is +made whether to examine and/or refit the features. A response +of yes or YES will put the user in the interactive graphical mode +of \fBidentify\fR. See the description of this task for more +information. The idea is that one can monitor the statistics information, +particularly the RMS if refitting, and select only those which may be +questionable to examine interactively. A response of no or NO will +continue on to the next reidentification. The capitalized responses +turn off the query and act as permanent response for all other +reidentifications. + +This statistics line, including headers, is written to any specified +log files. The log information includes the image being +reidentified and the reference image, and the initial shift. + +If an accessible file name is given for the plot file then a residual plot +of the reidentified lines is recorded in this file. The plot file can +be viewed with \fBgkimosaic, stdgraph\fR or reading the file +with ".read" when in cursor mode (for example with "=gcur"). + +The reidentification results for this task are recorded in a +\fIdatabase\fR. Currently the database is a directory and entries +in the database are text files with filenames formed by adding +the prefix "id" to the image name without an image extension. +.ih +EXAMPLES +1. Arc lines and a dispersion solution were defined for the middle +aperture in the multispec for arc spectrum a042.ms. To reidentify the +other apertures in the reference image and then another arc image: + +.nf + cl> reiden a042.ms a045.ms inter+ step=1 ver+ + REIDENTIFY: NOAO/IRAF V2.9 valdes@puppis Fri 29-Jun-90 + Reference image = a042.ms.imh, New image = a042.ms, Refit = yes + Image Data Found Fit Pix Shift User Shift RMS + a042.ms - Ap 24 48/48 47/48 -2.38E-4 -3.75E-6 0.699 + Fit dispersion function interactively? (no|yes|NO|YES) (yes): y + a042.ms - Ap 24 48/48 47/48 -2.38E-4 -3.75E-6 0.699 + a042.ms - Ap 23 48/48 47/48 0.216 1.32 0.754 + Fit dispersion function interactively? (no|yes|NO|YES) (yes): n + a042.ms - Ap 22 48/48 47/48 0.0627 0.383 0.749 + Fit dispersion function interactively? (no|yes|NO|YES) (yes): n + a042.ms - Ap 21 48/48 47/48 0.337 2.06 0.815 + <etc> + Reference image = a042.ms.imh, New image = a045.ms, Refit = yes + Image Data Found Fit Pix Shift User Shift RMS + a045.ms - Ap 24 48/48 47/48 -2.38E-4 -3.75E-6 0.699 + Fit dispersion function interactively? (no|yes|NO|YES) (yes): y + a045.ms - Ap 24 48/48 47/48 -2.38E-4 -3.75E-6 0.699 + a045.ms - Ap 23 48/48 47/48 0.216 1.32 0.754 + Fit dispersion function interactively? (no|yes|NO|YES) (yes): N + a045.ms - Ap 22 48/48 47/48 0.0627 0.383 0.749 + a042.ms - Ap 21 48/48 47/48 0.337 2.06 0.815 + a042.ms - Ap 20 48/48 47/48 -0.293 -1.79 0.726 + a042.ms - Ap 19 48/48 48/48 0.472 2.88 0.912 +.fi + +This example is verbose and includes interactive review of reidentifications. +The statistics lines have been shortened. + +2. To trace a stellar profile and arc lines in long slit images for the +purpose of making a distortion correction: + +.nf + cl> reiden rog022[135,*] "" trace+ + cl> reiden rog023 "" sec="mid line" trace+ +.fi +.ih +REVISIONS +.ls REIDENTIFY V2.11 +The \fIsearch\fR parameter and new searching algorithm has been added. + +The task will now work with only a warning if the reference image is absent; +i.e. it is possible to reidentify given only the database. + +The \fIaddfeatures\fR function will now add features before a fit if there +are no reference database features. Previously features could only be +added after an initial fit using the reference features and, so, required +the reference database to contain features for reidentification. This +new feature is useful if one wants to uses a dispersion function from one +type of calibration but wants to add features for a different kind of +calibration. +.le +.ls REIDENTIFY V2.10.3 +The section, nsum, step, and shift parameter syntax was extended to apply to 3D +images. The previous values and defaults may still be used. + +For multiaperture data a step of zero selects only the reference aperture +to be reidentified and any other step selects reidentifying all apertures. +.le +.ls REIDENTIFY V2.10 +This task is a new version with many new features. The new features +include an interactive options for reviewing identifications, iterative +rejection of features during fitting, automatic addition of new features +from a line list, and the choice of tracing or using a single master +reference when reidentifying features in other vectors of a reference +spectrum. Reidentifications from a reference image to another image is +done by matching apertures rather than tracing. New apertures not present +in the reference image may be added. +.le +.ih +SEE ALSO +autoidentify, identify, aidpars, center1d, linelists, fitcoords +.endhelp |