path: root/noao/rv/doc/rvidlines.hlp

.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