Initial commit

1 files changed, 530 insertions, 0 deletions

diff --git a/noao/rv/doc/rvidlines.hlp b/noao/rv/doc/rvidlines.hlp
new file mode 100644
index 00000000..2e87a412
--- /dev/null
+++ b/noao/rv/doc/rvidlines.hlp
@@ -0,0 +1,530 @@
+.help rvidlines Aug93 noao.rv
+.ih
+NAME
+rvidlines -- Measure radial velocities from spectral lines
+.ih
+USAGE
+rvidlines images
+.ih
+PARAMETERS
+.ls images
+List of spectral images in which to identify spectral lines and measure a
+velocity.  The spectra must be dispersion calibrated in Angstroms.
+.le
+.ls section = "middle line"
+If an image is not one dimensional or given as a one dimensional image
+section then the image section given by this parameter is used.  The
+section is used to define the initial vector and the direction (columns,
+lines, or "z") of the image vectors to be fit.  The image is still considered
+to be two or three dimensional and it is possible to change the data vector
+within the program.
+
+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 examples of
+this syntax.  Abbreviations are allowed though beware
+that 'l' is not a sufficient abbreviation.
+.le
+.ls database = "database"
+Database in which the feature data and redshifts are recorded.
+.le
+.ls coordlist = ""
+User coordinate list consisting of an ordered list of rest spectral line
+coordinates.  If a line list is defined lines from the list may be
+automatically found and added to the lines being measured.
+.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 match = 5.
+The maximum difference for a match between the measured line coordinate
+and a coordinate in the coordinate list.  The units of this parameter
+is that of the user coordinates.
+.le
+.ls maxfeatures = 50
+Maximum number of the strongest features to be selected automatically from
+the coordinate list (function 'l') or from the image data (function 'y').
+.le
+.ls zwidth = 100.
+Width of graphs, in user coordinates, when in zoom mode (function 'z').
+.le
+
+The following parameters are used in determining feature positions.
+.ls ftype = "absorption" (emission|absorption|gemission|gabsorption)
+Type of features to be identified.  The possibly abbreviated choices are
+"emission", "absorption", "gemission", and "gabsorption".  The first two
+select the \fBcenter1d\fR centering algorithm while the last two
+select the Gaussian fitting centering algorithm.
+.le
+.ls fwidth = 4.
+Width in pixels of features to be identified.
+.le
+.ls cradius = 5.
+The maximum distance, in pixels, allowed between a feature position
+and the initial estimate when defining a new feature.
+.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.
+.le
+.ls minsep = 2.
+The minimum separation, in pixels, allowed between feature positions
+when defining a new feature.
+.le
+
+The following parameters control the input and output.
+.ls logfile = "logfile"
+Log file for recording the results of the velocity measurements.  The
+results are written when exiting or changing input images.  The
+results can be previewed with the ":features" command.  If no log file
+is specified then the results are not saved.
+.le
+.ls autowrite = no
+Automatically write or update the logfile and database?  If no then a query
+is given for writing results to the logfile.  A query for writing to the
+database is also given if the feature data have been modified.  If yes
+exiting the program automatically writes to the logfile and updates the
+database.
+.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
+.ih
+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.
+Note that the parameters used are "ra", "dec", "ut", and "date-obs".
+The "utmiddle" parameter is not used so if you have a keyword for the
+middle of the exposure that you want to use then you must set the
+"ut" parameter to reference that keyword.
+
+Before IRAF V2.12, if the date keyword included a time then that time was
+used and the "ut" keyword was not used.  In V2.12 this was changed and the
+time is always taken from the keyword specified by "ut".  However, the
+value can be in either a single time or a date/time string.  So if you
+want to use both the date and time from the same keyword, say DATE-OBS,
+then point the "date_obs" and "ut" parameters in KEYWPARS to the same
+keyword.
+.ih
+CURSOR KEYS
+
+.nf
+?  Clear the screen and print menu of options
+a  Apply next (c)enter or (d)elete operation to (a)ll features
+b  Mark and de(b)lend features by Gaussian fitting
+c  (C)enter the feature nearest the cursor
+d  (D)elete the  feature nearest the cursor
+f  (F)it redshift and velocity from the fitted and user coordinates
+i  (I)nitialize (delete features and coordinate fit)
+j  Go to the preceding image line/column/band/aperture
+k  Go to the next image line/column/band/aperture
+l  Match coordinates in the coordinate (l)ist
+m  (M)ark new feature near the cursor and enter coord and label
+n  Move the cursor or zoom to the (n)ext feature (same as +)
+o  Go to the specified image line/column/band/aperture
+p  (P)an to user defined window after (z)ooming on a feature
+q  (Q)uit and continue with next image (also carriage return)
+r  (R)edraw the graph
+t  Reset the position of a feature without centering
+u  Enter a new (u)ser coordinate and label for the current feature
+w  (W)indow the graph.  Use '?' to window prompt for more help.
+y  Automatically find strongest peaks and identify them
+z  (Z)oom on the feature nearest the cursor
+.  Move the cursor or zoom to the feature nearest the cursor
++  Move the cursor or zoom to the next feature
+-  Move the cursor or zoom to the previous feature
+I  Interrupt task and exit immediately
+.fi
+
+The parameters are listed or set with the following commands which may be
+abbreviated.  To list the value of a parameter type the command alone.
+
+.nf
+:show file		Show the values of all the parameters
+:features file		Write feature list to file (default STDOUT)
+
+:coordlist file		Coordinate list file
+:cradius value		Centering radius in pixels
+:threshold value	Detection threshold for feature centering
+:database name		Database for recording feature records
+:ftype value		Feature type
+			  (emission|absorption|gemission|gabsorption)
+:fwidth value		Feature width in pixels
+:image imagename 	Set a new image or show the current image
+:labels value		Feature label type
+			    (none|index|pixel|coords|user|both)
+:match value		Coordinate list matching distance
+:maxfeatures value	Maximum number of features automatically found
+:minsep value		Minimum separation allowed between features
+:read name ap		Read a record from the database
+			  (name/ap default to the current spectrum)
+:write name ap		Write a record to the database
+			  (name/ap default to the current spectrum)
+:add name ap		Add features from the database
+			  (name/ap default to the current spectrum)
+:zwidth value		Zoom width in user units
+
+Labels:
+      none - No labels
+     index - Sequential numbers in increasing pixel position
+     pixel - Pixel coordinates
+    coords - User coordinates such as wavelength
+      user - User labels
+      both - Combination of coords and user
+.fi
+.ih
+DESCRIPTION
+\fBRvidlines\fR measures radial velocities from spectra by determining the
+wavelength shift in spectral lines relative to specified rest wavelengths.
+The basic usage consists of identifying one or more spectral lines (also
+called features), entering the rest wavelengths, and computing the average
+wavelength shift converted to a radial velocity.  Additional lines can then
+be automatically added from a coordinate list of rest wavelengths.
+
+Each dispersion calibrated image in the input list is examined in turn.  If
+the image is not one dimensional or a one dimensional section of an image
+then the image section given by the parameter \fIsection\fR is used.  This
+parameter may be specified in several ways as described in the parameter
+and examples sections.  The image section is used to select a starting
+vector and image axis.  The parameter \fInsum\fR determines the number
+of lines, columns, or bands to sum in a two or three dimensional image.
+
+Once a spectrum has been selected it is graphed.  The graph title includes
+the image name, spectrum title, and the current velocity and redshift if
+one has been determined.  An initial feature list is read from the database
+if an entry exists.  The features are marked on the graph by tick marks.
+The features may also be labeled using the ":label" option.  The graph has
+the observed wavelength scale along the bottom and the rest wavelength
+scale along the top (if a velocity has been determined).  The status line
+gives the pixel coordinate, observed wavelength, rest wavelength (as
+computed by the last velocity computation), the true rest wavelength, the
+velocity residual, and an optional identification string for the "current"
+feature.
+
+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 section 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 'm' key marks
+a new feature near the cursor position.  The feature position is
+determined by a centering algorithm.  There are two algorithms;
+a flux bisecting algorithm called \fBcenter1d\fR and a gaussian
+profile fitting algorithm.  The choice of fitting algorithm and whether the
+feature is an emission or absorption line is set by the \fIftype\fR
+parameter.
+
+The center1d algorithm is described in the help topic \fBcenter1d\fR.  The
+parameters which control it are \fIfwidth\fR, \fIftype\fR, \fIcradius\fR,
+and \fIthreshold\fR.
+
+The gaussian fitting algorithm estimates a linear local background by
+looking for the minimum or maximum, depending on whether the feature type
+is set to absorption or emission, within a distance of the entered cursor
+position of one-half the feature width specified by the \fIfwidth\fR
+parameter plus the centering error radius specified by the \fIcradius\fR
+parameters.  This background estimation is crude but generally is not
+critical for reasonably strong lines.  Once the sloped background is
+defined a non-linear Levenberg-Marquardt algorithm determines the gaussian
+center, peak strength, and sigma.  The initial estimates for these
+parameters are the starting center, the background subtracted pixel value
+at the starting center, and the \fIfwidth\fR value divided by six.  After
+fitting the gaussian model it is overplotted on the data for comparison.  The
+\fIthreshold\fR parameter also applies to this algorithm to check for a
+minimum data range and the \fIcradius\fR parameter checks for a maximum
+error in the center from the initial value.
+
+For a more critical setting of the background in the gaussian algorithm or
+for the simultaneous solution of multiple gaussian components (deblending)
+the 'b' key is available.  The 'b' key is used to mark the initial
+positions of up to ten features.  The feature marking ends with 'q'.  The
+user is then queried to mark two points for the linear background.  After
+doing the simultaneous fitting the user is queried sequentially for the
+rest wavelengths of each line.  Note that the 'b' key will do the gaussian
+fitting regardless of whether the \fIftype\fR setting is for a gaussian
+or not and can be used for fitting just a single line.
+
+When a feature is defined the value of \fIftype\fR and \fIfwidth\fR are
+associated with the feature.  Subsequent recentering will use these values
+even if the default values are changed.  This is how a combination of
+absorption and emission lines may be defined.  The only constraint to this
+is that the feature data does not record the combination of lines used in a
+deblending operation so automatic recentering will treat each line
+separately.
+
+When a new feature is marked if the wavelength is within a distance given
+by the parameter \fIminsep\fR of a previous feature it is considered to be
+the same feature and replaces the old feature.  The coordinate list is
+searched for a match between the measured wavelength, corrected to rest
+using the current velocity, and a user coordinate in the list.  The
+matching is based on the nearest line within a specified \fImatch\fR
+distance.  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 't' key allows setting the position of a feature to
+other than that found by the centering algorithms.
+
+If at least one feature is marked with it's rest wavelength specified then
+the 'l' key may be used to identify additional features from a coordinate
+list of rest wavelengths.  First a velocity is computed from the initial
+features.  Then each coordinate in the list is corrected to the
+observed velocity and a feature is sought in the data at that point.
+Up to a maximum number of features, set by the parameter \fImaxfeatures\fR,
+may be defined in this way.  A new velocity is computed using all the
+located features.
+
+The 'y' key provides another way to add features.  Rather than look for
+features at the coordinates of a list, a peak finding algorithm is used to
+find features up to the specified maximum number.  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.
+
+The key 'f' computes ("fits") a velocity to the defined features.
+This is done by taking a weighted average of the redshifts,
+
+.nf
+	z = (measured - true) / true
+.fi
+
+of the individual lines.  The default weights are always one but a different
+weight may be entered with the 'u' key.  The average redshift is
+converted to a Cz velocity (redshift times the speed of light) and
+corrected to a heliocentric frame if possible.
+
+The heliocentric correction requires observatory and observation information.
+The observatory is determined either from the OBSERVAT keyword in the
+image header or by the "rv.observatory" package parameter.  For a
+discussion of how an observatory is defined and used see the help
+for \fBobservatory\fR.  In addition to the observatory the right
+ascension, declination, coordinate epoch, and date and time of the
+observation are required.  If the time is in the date string it has
+precedence over the time keyword.  This information is sought in the image
+header using the keywords defined in the \fBkeywpars\fR parameter
+file.  If there is insufficient information for the heliocentric
+velocity correction only the observed velocity will be given.  The
+type of velocity (both velocity and redshift) is indicated by
+identifiers such as Vobs and Vhelio.
+
+Note that a new velocity is only computed after typing 'f', 'l',
+":features", or when exiting and writing the results to the database.
+In other words, adding new features or deleting existing features
+does not automatically update the velocity determination.
+
+Features may be deleted with the key 'd'.  All features are deleted
+when the 'a' key immediately precedes the delete key.  Deleting the
+features does not reset the velocity.  The 'i' key initializes
+everything by removing all features and reseting the velocity.
+
+It is common to transfer the feature identifications and velocities
+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,
+changing image lines or columns with 'j', 'k' and 'o', or selecting
+a new image with the ":image" command, the current feature list and
+velocity are kept.  Alternatively, a database record from a different
+image may be read with the ":read" command.  When transferring 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.  An additional options is the ":add"
+command to add features from a database record.  This does not overwrite
+previous features as does ":read".
+
+Note that when a set of spectra all have the same features in nearly
+the same location the task \fBrvreidlines\fR may be used to reidentify
+the lines and compute a new velocity.
+
+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 beginning with ":." (type
+":.help" for these commands).  The rvidlines 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 and velocities (: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 logging the
+results or recording changes in the feature database produces a warning
+message unless the \fIautowrite\fR parameter is set.  If this parameter is
+not set prompts are given asking whether to save the results to the log
+file and the database, otherwise the results are automatically saved.  As
+an immediate exit the 'I' interrupt key may be used.  This does not save
+the feature information and may leave the graphics in a confused state.
+
+The information recorded in the logfile, if one is specified, includes
+information about the observatory used for heliocentric corrections
+(to verify the correct observatory was used), the list of features
+used in the velocity computation, the wavelength and velocity RMS,
+and lines with the observed and heliocentric redshifts and velocities.
+These lines include an error in the mean derived from the weighted
+RMS and the number of lines used, and the number of lines.  This output
+format is designed so that if there are multiple velocities recorded
+in the same log file they can be easily extracted with the match command:
+
+.nf
+    cl> match Vhelio logfile
+    im1 45 : Vhelio = 15.06 km/s, Mean err = 4.593 km/s, Lines = 7
+    im1 40 : Vhelio = 17.77 km/s, Mean err = 3.565 km/s, Lines = 7
+    im2 45 : Vhelio = 24.44 km/s, Mean err = 3.741 km/s, Lines = 7
+    im2 40 : Vhelio = 14.65 km/s, Mean err =  11.2 km/s, Lines = 7
+    ...
+.fi
+.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 \fBrvidlines\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.  The radial velocity of the  spectrum, kstar1, is to be determined.
+The user creates a list of line features to be used in the file
+klines.dat.
+
+.nf
+    cl> rvidlines kstar1 coord=klines.dat
+	a. The spectrum is drawn
+	b. A line is marked with 'm'
+	c. Enter the rest wavelength
+	d. Compute a velocity with 'f'
+	e. Find other lines in the list with 'l'
+	f. Exit with 'q'
+    Write velocity data to the logfile (yes)? y
+    Write feature data to the database (yes)? y
+    cl> match Vhelio logfile
+    kstar1 1 : Vhelio = 25.1 km/s, Mean err = 1.123 km/s, Lines = 10
+.fi
+
+2.  For echelle or multispec spectra the keys 'o', 'j', and 'k' may
+be used to switch between spectra.  Note that the inheritance of features
+in echelle orders is not very useful.  So the 'i' can be used to
+initialize.  For similar spectra the 'a''c' key combination may
+be used to recenter all lines and the a new 'f' fit can be done.
+
+3.  For images which are two or three dimensional it is necessary to
+specify the image axis for the data vector and the number of pixels at each
+point across the vector direction to sum.  One way specify a vector is to
+use an image section to define a vector.  For example, to select column
+20:
+
+.nf
+    cl> rvidlines obj[20,*]
+.fi
+
+The alternative is to use the section parameter.  Below are some examples
+of the section parameter syntax for an image "im2d" which is 100x200
+and "im3d" which is 100x200x50.  On the left is the section string syntax
+and on the right is the image section
+
+.nf
+    Section parameter |  Image section      |  Description
+    ------------------|---------------------|---------------------
+    first line        |  im2d[*,1]          |  First image line
+    middle column     |  im2d[50,*]         |  Middle image column
+    last z            |  im3d[100,200,*]    |  Last image z vector
+    middle last y     |  im3d[50,*,50]      |  Image y vector
+    line 20           |  im2d[*,20]         |  Line 20
+    column 20         |  im2d[20,*]         |  Column 20
+    x 20              |  im2d[*,20]         |  Line 20
+    y 20              |  im2d[20,*]         |  Column 20
+    y 20 30           |  im2d[20,*,30]      |  Column 20
+    z 20 30	      |  im3d[20,30,*]      |  Image z vector
+    x middle          |  im3d[*,100,25]     |  Middle of image
+    y middle          |  im3d[50,*,25]      |  Middle of image
+    z middle          |  im3d[50,100,*]     |  Middle of image
+.fi
+
+The most common usage should be "middle line", "middle column" or "middle z".
+
+The summing factors apply to the axes across the specified vector.  For
+3D images there may be one or two values.  The following shows which axes
+are summed, the second and third columns, when the vector axis is that shown
+in the first column.
+
+.nf
+    Vector axis       |   Sum axis in 2D    |  Sum axes in 3D
+    ------------------|---------------------|--------------------
+         1            |         2           |      2 3                 
+         2            |         1           |      1 3                 
+         3            |         -           |      1 2                 
+.fi
+
+.ih
+REVISIONS
+.ls RVIDLINES V2.11
+This task will now work in the units of the input spectra.
+.le
+.ls RVIDLINES V2.10.3
+This is a new task in this version. 
+.le
+.ih
+SEE ALSO
+center1d, fxcor, gtools, identify, keywpars, observatory,
+rvcorrect, rvreidlines
+.endhelp