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

.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