Repatch (from linux) of OSX IRAF

1 files changed, 405 insertions, 0 deletions

diff --git a/noao/rv/doc/rvreidlines.hlp b/noao/rv/doc/rvreidlines.hlp
new file mode 100644
index 00000000..763e813a
--- /dev/null
+++ b/noao/rv/doc/rvreidlines.hlp
@@ -0,0 +1,405 @@
+.help rvreidlines Aug93 noao.rv
+.ih
+NAME
+rvreidlines -- Reidentify spectral lines and measure velocities
+.ih
+USAGE
+rvreidlines reference images
+.ih
+PARAMETERS
+.ls reference
+Spectrum with previously identified features to be used as reference for
+other spectra.  If there are multiple apertures, lines, or columns in the
+image a master reference is defined by the \fIsection\fR parameter.
+The other apertures, lines, or columns selected by \fIstep\fR are
+reidentified if needed.
+.le
+.ls images
+List of dispersion corrected spectral 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 and velocities 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 determination and the user may chose to enter the interactive
+\fBrvidlines\fR task.
+.le
+.ls section = "middle line"
+If the reference image is not one dimensional or given 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 3D data.  See the example section for \fBrvidlines\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 features will be added to the reference apertures.  All
+further identifications of the new aperture will then use this result.
+.le
+.ls override = no
+Override previous solutions?  If there are previous measurements for a
+particular image vector being identified, because of a previous
+\fBrvidlines\fR or \fBrvreidlines\fR, this parameter selects whether
+to simply skip the reidentification or do a reidentification and
+velocity measurement and overwrite the results in the logfile and database.
+.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 aperture, 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.  For
+multiaperture images the step is typically 1 while for long slit or
+Fabry-Perot images the step is large enough to map any significant changes
+in the feature positions.  If the step is zero then only the reference
+line, column, or band is used.
+.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.
+.le
+.ls shift = "0"
+Shift in user coordinates to be added to the reference features before
+centering when stepping to other lines, columns, or bands in the reference
+image.  Generally no shift is used by setting the value to zero.
+The shift is used as a slope with positive values increasing towards
+larger line or column numbers.  This parameter is not used for
+reidentifications from the reference image to other images.
+If the image is three dimensional then two numbers may be specified
+for the two axes.
+.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 logfile and 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 and \fBrvidlines\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 = 10.
+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 = ""
+User coordinate list consisting of an ordered list of rest spectral line
+coordinates.
+.le
+.ls match = 10.
+The maximum difference for a match between the feature coordinate function
+value and a coordinate in the coordinate list (after correction by the
+velocity).
+.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 file in which to record the velocity results and to keep a
+processing log.  If a null file, "", is given then no log is kept.
+.le
+.ls verbose = no
+Print reidentification and velocity information on the standard output?
+.le
+.ls keywpars = ""
+The image header keyword translation table as described in 
+the \fIkeywpars\fR named pset.  This defines the header keywords used
+to obtain the observation information needed for computing the
+heliocentric velocity.
+.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
+ADDTIONAL PARAMETERS
+The measured velocities are corrected to a heliocentric frame of reference
+if possible.  This requires determining various parameters about the
+observation.  The latitude, longitude, and altitude of the observation
+are determined from the observatory database.  The observatory is
+defined by either the OBSERVAT image header keyword or the "observatory"
+package parameter in that order.  See the help for \fBobservatory\fR
+for additional information.
+
+The date, universal time, right ascension, declination, and coordinate epoch
+for the observation are obtained from the image header.  The keywords
+for these parameters are defined in the \fBkeywpars\fR parameter set.
+.ih
+DESCRIPTION
+\fBRvreidlines\fR takes spectral lines previously identified in a reference
+image and recorded in a database and identifies them in other spectra and
+determines a radial velocity.  If the images are
+two or three dimensional or multiaperture format and a \fIstep\fR greater
+than zero is specified then additional vectors
+(lines/columns/bands/apertures) 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
+spectra images, called multiaperture, the step size is typically 1; i.e.
+reidentify features in all spectra.  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
+set of reference identifications is applied to other images in the same
+lines, columns, bands, or apertures.  In multiaperture images the same
+apertures are matched in the reference image regardless of actual line
+order; i.e.  the apertures need not be in the same order or even have all
+apertures present.
+
+The reidentification of other 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 reidentifying other vectors in the reference image the parameter
+\fBshift\fR may be used to add a shift(s) to the features positions
+before recentering.  The shift is added to lines, columns, or bands, greater
+than the current line, column, or band and subtracted if less.  If tracing
+the shifts are the same from step to step while if not tracing the
+shifts are added to the shifts from the previous step.  Thus, in both
+cases an approximation of a slope is used.  This allows large
+slopes in the features to be followed even when not tracing but the 
+shift value must be predetermined.
+
+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 aperture to be reidentified in other images.
+This is useful when specta with different aperture numbers are
+stored as one dimensional images.
+
+There are two centering algorithms; a flux bisecting algorithm called
+\fBcenter1d\fR and a gaussian fitting algorithm.  These algorithms
+are described in the help for \fBrvidlines\fR.  The algorithm used
+and whether the feature is emission or absorption is the same one used
+in the reference image.  The only caveat is that multiple gaussian
+fitting provided by the interactive 'b' key in \fBrvidlines\fR is
+not done by this task and those lines will be fit by gaussians
+independently.
+
+When recentering, if a feature position 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.
+
+In two and three dimensional images, though not multiaperture images, the
+number of lines, columns, or bands given by the parameter \fInsum\fR are summed
+to form the one dimensional image vector in which the features are
+identified.  This increases the accuracy for reidentifying weak
+features.
+
+If the parameter \fIaddfeatures\fR is set additional features may be added
+after the initial reidentification and velocity determination using a line
+list of rest wavelengths.  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
+\fBrvidlines\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 velocity determination (currently there is
+no rejection of lines) relative to the number found,  the
+mean pixel and user coordinate shfits relative to the reference
+coordinates, and the measured velocity and RMS in the velocity.
+The velocity is the heliocentric velocity if the necessary observation
+information in the image and observatory database are found.
+
+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 fit the lines and measure the velocity interactively.
+A response
+of yes or YES will put the user in the interactive graphical mode
+of \fBrvidlines\fR.  See the description of this task for more
+information.  The idea is that one can monitor the statistics information,
+particularly the velocity RMS, and select only those which may be
+questionable to examine interactively.  A response of no or NO will
+continue on to the next spectrum.  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.
+In addition the set of lines, the observatory information used,
+and the computed observed and heliocentric velocities and redshifts
+are recorded.  This is the same information as is produced
+by \fBrvidlines\fR.
+.ih
+DATABASE RECORDS
+The database specified by the parameter \fIdatabase\fR is a directory of
+simple text files.  The text files have names beginning with 'id' 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 \fBrvreidlines\fR have "identify" 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.  For 1D spectra the database entry includes the aperture number
+and so to read a solution from a aperture different than the current image
+and aperture number must be specified.  For 2D/3D images the entry name
+has the 1D image section which is what is specified to read the entry.
+The lines following the record identifier contain
+the feature information and redshift (without heliocentric correction).
+
+The database files have the name "identify" and the prefix "id" because
+these files may also be read by the \fBidentify\fR task for changing
+the dispersion function based on the rest wavelengths.
+.ih
+EXAMPLES
+1.  To generate a rotation curve for a long slit spectrum of a
+galaxy first use \fBrvidlines\fR to mark some lines at the center of the
+galaxy.  If the velocities are to be absolute then you give the rest
+wavelengths and do a fit.  However to get velocities relative to the center
+use the measured wavelengths by simply accepting the prompted measured
+wavelengths.  Then run \fBrvreidlines\fR.  The \fInsum\fR and \fIstep\fR
+parameters allow controlling the summing size and spacing.
+
+.nf
+    rv> rvid lsgal sec="mid col" nsum=5
+	    Mark lines and then quit.
+    Write velocity data to the logfile (yes)?
+    Write feature data to the database (yes)?
+    rv> rvreid lsgal "" sec="mid col" nsum=5 step=5 trace+ v+
+
+    RVREIDLINES: NOAO/IRAF V2.10.3 valdes Sat 14:47:55 21-Aug-93
+      Reference image = lsgal, New image = lsgal
+     Image Data  Found    Fit  Pix Shift  User Shift Velocity    RMS
+    lsgal[45,*]    7/7    7/7    -0.0181     -0.0212    -1.37   11.3
+    lsgal[40,*]    7/7    7/7     0.0147      0.0193     1.34   8.73
+    lsgal[35,*]    7/7    7/7     0.0931       0.116     8.01   9.16
+    lsgal[30,*]    7/7    7/7    -0.0224     -0.0265    -1.78   27.6
+    lsgal[25,*]    7/7    7/7     0.0558        0.07     4.83   33.7
+    lsgal[20,*]    7/7    7/7    -0.0317     -0.0379    -3.08   33.6
+    lsgal[15,*]    5/7    5/5      0.015      0.0201    0.799   43.7
+    lsgal[10,*]    7/7    7/7      0.395       0.489     33.7   54.9
+    lsgal[5,*]     4/7    4/4      -1.22       -1.51    -106.   84.3
+    lsgal[55,*]    7/7    7/7      0.014      0.0184     1.41   10.5
+    lsgal[60,*]    7/7    7/7    -0.0897      -0.109    -7.59   7.21
+    lsgal[65,*]    7/7    7/7    -0.0109     -0.0122   -0.957   10.9
+    lsgal[70,*]    7/7    7/7     -0.074     -0.0902    -6.55   14.6
+    lsgal[75,*]    7/7    7/7   -0.00203    -0.00136    0.227   54.3
+    lsgal[80,*]    6/7    6/6       0.08      0.0997     6.66   96.7
+    lsgal[85,*]    6/7    6/6      0.289       0.357     27.2   104.
+    lsgal[90,*]    6/7    6/6      0.459       0.568     40.5   33.2
+    lsgal[95,*]    6/7    6/6      0.926        1.14     78.5   65.5
+    lsgal[100,*    5/7    5/5      0.696        0.86     59.1   44.2
+    rv> match Vobs logfile | fields "" 2,6,11 | \
+    >>> graph point- mark=vebar szmark=-1
+.fi
+
+The last command extracts the Vobs results from the logfile using
+\fBmatch\fR, the column number, velocity, and mean error are extract
+using \fBfields\fR, and graphs the points with error bars.  One
+drawback to this method is that the nubmer of columns summed is
+constant and so the signal-to-noise decreases with the galaxy light.
+.ih
+REVISIONS
+.ls RVREIDLINES V2.11
+This task will now work in the units of the input spectra.
+.le
+.ls RVREIDLINES V2.10.3
+This task in new in the version.
+.le
+.ih
+SEE ALSO
+center1d, fxcor, keywpars, observatory, rvcorrect, rvidlines
+.endhelp