diff options
Diffstat (limited to 'noao/rv/doc/rvidlines.hlp')
| -rw-r--r-- | noao/rv/doc/rvidlines.hlp | 530 |
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 |