From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001
From: Joe Hunkeler <jhunkeler@gmail.com>
Date: Tue, 11 Aug 2015 16:51:37 -0400
Subject: Repatch (from linux) of OSX IRAF

---
 noao/onedspec/doc/reidentify.hlp | 516 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 516 insertions(+)
 create mode 100644 noao/onedspec/doc/reidentify.hlp

(limited to 'noao/onedspec/doc/reidentify.hlp')

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
-- 
cgit 

