From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- noao/onedspec/doc/splot.hlp | 1118 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1118 insertions(+) create mode 100644 noao/onedspec/doc/splot.hlp (limited to 'noao/onedspec/doc/splot.hlp') diff --git a/noao/onedspec/doc/splot.hlp b/noao/onedspec/doc/splot.hlp new file mode 100644 index 00000000..a5bc3b96 --- /dev/null +++ b/noao/onedspec/doc/splot.hlp @@ -0,0 +1,1118 @@ +.help splot Jul95 noao.onedspec +.ih +NAME +splot -- plot and analyze spectra +.ih +USAGE +splot images [line [band]] +.ih +PARAMETERS +.ls images +List of images (spectra) to plot. If the image is 2D or 3D the line +and band parameters are used. Successive images are plotted +following each 'q' cursor command. One may use an image section +to select a desired column, line, or band but the full image will +be in memory and any updates to the spectrum will be part of the +full image. +.le +.ls line, band +The image line/aperture and band to plot in two or three dimensional +images. For multiaperture spectra the aperture specified by the line +parameter is first sought and if not found the specified image line is +selected. For other two dimensional images, such as long slit spectra, the +line parameter specifies a line or column. Note that if +the line and band parameters are specified on the command line it will not +be possible to change them interactively. +.le +.ls units = "" +Dispersion coordinate units for the plot. If the spectra have known units, +currently this is generally Angstroms, the units may be converted +to other units for plotting as specified by this task parameter. +If this parameter is the null string and the world coordinate system +attribute "units_display" is defined then that will +be used. If both this task parameters and "units_display" are not +given then the spectrum dispersion units will be used. +The units +may also be changed interactively. See the units section of the +\fBpackage\fR help for a further description and available units. +.le +.ls options = "auto" [auto,zero,xydraw,histogram,nosysid,wcreset,flip,overplot] +A list of zero or more, possibly abbreviated, options. The options can +also be toggled with colon commands. The currently defined options are +"auto", "zero", "xydraw", "histogram", "nosysid", "wreset", "flip", and +"overplot". Option "auto" automatically replots the graph whenever changes +are made. Otherwise the graph is replotted with keystrokes 'c' or 'r'. +Option "zero" makes the initial minimum y of the graphs occur at zero. +Otherwise the limits are set automatically from the range of the data or +the \fIymin\fR parameter. Option "xydraw" changes the 'x' draw key to use +both x and y cursor values for drawing rather than the nearest pixel value +for the y value. Option "histogram" plots the spectra in a histogram style +rather than connecting the pixel centers. Option "nosysid" excludes the +system banner from the graph title. Option "wreset" resets the graph +limits to those specified by the \fIxmin, xmax, ymin, ymax\fR parameters +whenever a new spectrum is plotted. The "flip" option selects that +initially the spectra be plotted with decreasing wavelengths. The options +may be queried and changed interactively. The "overplot" options overplots +all graphs and a screen erase only occurs with the redraw key. +.le +.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF +The default limits for the initial graph. If INDEF then the limit is +determined from the range of the data (autoscaling). These values can +be changed interactively with 'w' window key options or the cursor commands +":/xwindow" and ":/ywindow" (see \fBgtools\fR). +.le +.ls save_file = "splot.log" +The file to contain any results generated by the equivalent width or +deblending functions. Results are added to this file until the file is +deleted. If the filename is null (""), then no results are saved. +.le +.ls graphics = "stdgraph" +Output graphics device: one of "stdgraph", "stdplot", "stdvdm", or device +name. +.le +.ls cursor = "" +Graphics cursor input. When null the standard cursor is used otherwise +the specified file is used. +.le + +The following parameters are used for error estimates in the 'd', +'k', and 'e' key measurements. See the ERROR ESTIMATES section for a +discussion of the error estimates. +.ls nerrsample = 0 +Number of samples for the error computation. A value less than 10 turns +off the error computation. A value of ~10 does a rough error analysis, a +value of ~50 does a reasonable error analysis, and a value >100 does a +detailed error analysis. The larger this value the longer the analysis +takes. +.le +.ls sigma0 = INDEF, invgain = INDEF +The pixel sigmas are modeled by the formula: + +.nf + sigma**2 = sigma0**2 + invgain * I +.fi + +where I is the pixel value and "**2" means the square of the quantity. If +either parameter is specified as INDEF or with a value less than zero then +no sigma estimates are made and so no error estimates for the measured +parameters are made. +.le + +The following parameters are for the interactive curve fitting function +entered with the 't' key. This function is usually used for continuum +fitting. The values of these parameters are updated during the fitting. +See \fBicfit\fR for additional details on interactive curve fitting. +.ls function = "spline3" +Function to be fit to the spectra. The functions are +"legendre" (legendre polynomial), "chebyshev" (chebyshev polynomial), +"spline1" (linear spline), and "spline3" (cubic spline). The functions +may be abbreviated. +.le +.ls order = 1 +The order of the polynomials or the number of spline pieces. +.le +.ls low_reject = 2., high_reject = 4. +Rejection limits below and above the fit in units of the residual sigma. +Unequal limits are used to reject spectral lines on one side of the continuum +during continuum fitting. +.le +.ls niterate = 10 +Number of rejection iterations. +.le +.ls grow = 1. +When a pixel is rejected, pixels within this distance of the rejected pixel +are also rejected. +.le +.ls markrej = yes +Mark rejected points? If there are many rejected points it might be +desired to not mark rejected points. +.le + +The following parameters are used to overplot standard star fluxes with +the 'y' key. See \fBstandard\fR for more information about these parameters. +.ls star_name +Query parameter for the standard star fluxes to be overplotted. +Unrecognized names or a "?" will print a list of the available stars +in the specified calibration directory. +.le +.ls mag +The magnitude of the observed star in the band given by the +\fImagband\fR parameter. If the magnitude is not in the same band as +the blackbody calibration file then the magnitude may be converted to +the calibration band provided the "params.dat" file containing relative +magnitudes between the two bands is in the calibration directory +.le +.ls magband +The standard band name for the input magnitude. This should generally +be the same band as the blackbody calibration file. If it is +not the magnitude will be converted to the calibration band. +.le +.ls teff +The effective temperature (deg K) or the spectral type of the star being +calibrated. If a spectral type is specified a "params.dat" file must exist +in the calibration directory. The spectral types are specified in the same +form as in the "params.dat" file. For the standard blackbody calibration +directory the spectral types are specified as A0I, A0III, or A0V, where A +can be any letter OBAFGKM, the single digit subclass is between 0 and 9, +and the luminousity class is one of I, III, or V. If no luminousity class +is given it defaults to dwarf. +.le +.ls caldir = ")_.caldir" +The standard star calibration directory. The default value redirects the +value to the parameter of the same name in the package parameters. +.le +.ls fnuzero = 3.68e-20 +The absolute flux per unit frequency at a magnitude of zero used to +to convert the calibration magnitudes to absolute flux. +.le + +The following parameters are used for queries in response to particular +keystrokes. +.ls next_image +In response to 'g' (get next image) this parameter specifies the image. +.le +.ls new_image +In response to 'i' (write current spectrum) this parameter specifies the +name of a new image to create or existing image to overwrite. +.le +.ls overwrite = no +Overwrite an existing output image? If set to yes it is possible to write +back into the input spectrum or to some other existing image. Otherwise +the user is queried again for a new image name. +.le +.ls spec2 +When adding, subtracting, multiplying, or dividing by a second spectrum +('+', '-', '*', '/' keys in the 'f' mode) this parameter is used to get +the name of the second spectrum. +.le +.ls constant +When adding or multiplying by a constant ('p' or 'm' keys in the 'f' mode) +the parameter is used to get the constant. +.le +.ls wavelength +This parameter is used to get a dispersion coordinate value during deblending or +when changing the dispersion coordinates with 'u'. +.le +.ls linelist +During deblending this parameter is used to get a list of line positions, +peak values, profile types, and widths. +.le +.ls wstart, wend, dw +In response to 'p' (convert to a linear wavelength scale) these parameters +specify the starting wavelength, ending wavelength, and wavelength per pixel. +.le +.ls boxsize +In response to 's' (smooth) this parameter specifies the box size in pixels +to be used for the boxcar smooth. The value must be odd. If an even +value is specified the next larger odd value is actually used. +.le +.ih +DESCRIPTION +\fBSplot\fR provides an interactive facility to display and analyze +spectra. See also \fBbplot\fR for a version of this task useful for making +many plots noninteractively. Each spectrum in the image list is displayed +successively. To quit the current image and go on to the next the 'q' +cursor command is used. If an image is two-dimensional, such as with +multiple aperture or long slit spectra, the aperture or image column/line +to be displayed is needed. If the image is three-dimensional, such as with +the extra information produced by \fBapextract\fR, the band is needed. +These parameters are queried unless specified on the command line. If +given on the command line it will not be possible to change them +interactively. + +The plots are made on the specfied graphics device which is usually to +the graphics terminal. The initial plot limits are set with the parameters +\fIxmin, xmax, ymin\fR, and \fIymax\fR. If a limit is INDEF then that limit +is determined from the range of the data. The "zero" option may also +be set in the \fIoptions\fR parameter to set the lower intensity limit +to zero. Other options that may be set to control the initial plot +are to exclude the system identification banner, and to select a +histogram line type instead of connecting the pixel centers. +The dispersion units used in the plot are set by the \fIunits\fR +parameter. This allows converting to units other than those in which the +dispersion coordinates are defined in the spectra. + +The \fIoption\fR parameter, mentioned in the previous paragraph, is a +a list of zero or more options. As previously noted, some of the options +control the initial appearance of the plots. The "auto" option determines +how frequently plots are redrawn. For slow terminals or via modems one +might wish to minimize the redrawing. The default, however, is to redraw +when changes are made. The "xydraw" parameter is specific to the 'x' +key. + +After the initial graph is made an interactive cursor loop is entered. +The \fIcursor\fR parameter may be reset to read from a file but generally +the graphics device cursor is read. The cursor loop takes single +keystroke commands and typed in commands begun with a colon, called +colon commands. These commands are described below and a summary of +the commands may be produced interactively with the '?' key or +a scrolling help on the status line with the '/' key. + +Modifications to the spectra being analyzed may be saved using the 'i' key +in a new, the current, or other existing spectra. A new image is created +as a new copy of the current spectrum and so if the current spectrum is +part of a multiple spectrum image (including a long slit spectrum) the +other spectra are copied. If other spectra in the same image are then +modified and saved use the overwrite option to replace then in the new +output image. If the output spectrum already exists then the +\fIoverwrite\fR flag must be set to allow modifying the data. This +includes the case when the output spectrum is the same as the input +spectrum. The only odd case here is when the input spectrum is one +dimensional and the output spectrum is two dimensional. In this case the +user is queried for the line to be written. + +The other form of output, apart from that produced on the terminal, are +measurements of equivalent widths, and other analysis functions. This +information will be recorded in the \fIsave_file\fR if specified. + +The following keystrokes are active in addition to the normal IRAF +cursor facilities (available with ":.help"): + +.ls ? +Page help information. +.le +.ls / +Cycle through short status line help. +.le +.ls +The space bar prints the cursor position and value of the nearest +pixel. +.le +.ls a +Expand and autoscale to the data range between two cursor positions. +See also 'w', and 'z'. Selecting no range, that is the two +cursor positions the same, produces an autoscale of the whole spectrum. +.le +.ls b +Set the plot base level to zero rather than autoscaling. +.le +.ls c +Clear all windowing and redraw the full current spectrum. This redraws the +spectrum and cancels any effects of the 'a', 'z', and 'w' keys. The 'r' +key is used to redraw the spectrum with the current windowing. +.le +.ls d +Mark two continuum points and fit (deblend) multiple line profiles. +The center, continuum at the center, core intensity, integrated flux, +equivalent width, FWHMs for each profile are printed and saved +in the log file. See 'k' for fitting a single profile and +'-' to subtract the fitted profiles. +.le +.ls e +Measure equivalent width by marking two continuum points around the line +to be measured. The linear continuum is subtracted and the flux is +determined by simply summing the pixels with partial pixels at the ends. +Returned values are the line center, continuum at the region center, +flux above or below the continuum, and the equivalent width. +.le +.ls f +Enter arithmetic function mode. This mode allows arithmetic functions to be +applied to the spectrum. The pixel values are modified according to the +function request and may be saved as a new spectrum with the 'i' +command. Operations with a second spectrum are done in wavelength +space and the second spectrum is automatically resampled if necessary. +If one spectrum is longer than the other, only the smaller number of +pixels are affected. To exit this mode type 'q'. + +The following keystrokes are available in the function mode. Binary +operations with a constant or a second spectrum produce a query for the +constant value or spectrum name. +.ls a +Absolute value +.le +.ls d +Power of base 10 (inverse log base 10) +.le +.ls e +Power of base e (inverse log base e) +.le +.ls i +Inverse/reciprocal (values equal to zero are set to 0.0 in the inverse) +.le +.ls l +Log base 10 (values less than or equal to 0.0 are set to -0.5) +.le +.ls m +Multiply by a constant (constant is queried) +.le +.ls n +Log base e (values less than or equal to 0.0 are set to -0.5) +.le +.ls p +Add by a constant (constant is queried) +.le +.ls q +Quit Function mode +.le +.ls s +Square root (values less than 0.0 are set to 0.0) +.le +.ls + +Add another spectrum +.le +.ls -3 - +Subtract another spectrum +.le +.ls * +Multiply by another spectrum +.le +.ls / +Divide by another spectrum +.le +.le +.ls g +Get another spectrum. The current spectrum is replaced by the new spectrum. +The aperture/line and band are queried is necessary. +.le +.ls h +Measure equivalent widths assuming a gaussian profile with the width +measured at a specified point. Note that this is not a gaussian fit (see +'k' to fit a gaussian)! The gaussian profile determined here may be +subtracted with the '-' key. A second cursor key is requested with one of +the following values: +.ls a +Mark the continuum level at the line center and use the LEFT half width +at the half flux point. +.le +.ls b +Mark the continuum level at the line center and use the RIGHT half width +at the half flux point. +.le +.ls c +Mark the continuum level at the line center and use the FULL width +at the half flux point. +.le +.ls l +Mark a flux level at the line center relative to a normalized continuum +and use the LEFT width at that flux point. +.le +.ls r +Mark a flux level at the line center relative to a normalized continuum +and use the RIGHT width at that flux point. +.le +.ls k +Mark a flux level at the line center relative to a normalized continuum +and use the FULL width at that flux point. +.le +.le +.ls i +Write the current spectrum out to a new or existing image. The image +name is queried and overwriting must be confirmed. +.le +.ls j +Set the value of the nearest pixel to the x cursor to the y cursor position. +.le +.ls k + (g, l or v) +Mark two continuum points and fit a single line profile. The second key +selects the type of profile: g for gaussian, l for lorentzian, and v for +voigt. Any other second key defaults to gaussian. The center, continuum +at the center, core intensity, integrated flux, equivalent width, and FWHMs +are printed and saved in the log file. See 'd' for fitting multiple +profiles and '-' to subtract the fit. +.le +.ls l +Convert to flux per unit wavelength (f-lambda). The spectrum is assumed +to be flux calibrated in flux per unit frequency (f-nu). See also 'n'. +.le +.ls m +Compute the mean, RMS, and signal-to-noise over a region marked with two +x cursor positions. +.le +.ls n +Convert to flux per unit frequency (f-nu). The spectrum is assumed +to be flux calibrated in flux per unit wavelength (f-lambda). See also 'l'. +.le +.ls o +Set overplot flag. The next plot will overplot the current plot. +Normally this key is immediately followed by one of 'g', '#', '%', '(', or ')'. +The ":overplot" colon command and overplot parameter option may be +used to set overplotting to be permanently on. +.le +.ls p +Define a linear wavelength scale. The user is queried for a starting +wavelength and an ending wavelength. If either (though not both) +are specified as INDEF a dispersion is queried for and used to compute +an endpoint. A wavelength scale set this way will be used for +other spectra which are not dispersion corrected. +.le +.ls q +Quit and go on to next input spectrum. After the last spectrum exit. +.le +.ls r +Redraw the spectrum with the current windowing. To redraw the full +spectrum and cancel any windowing use the 'c' key. +.le +.ls s +Smooth via a boxcar. The user is prompted for the box size. +.le +.ls t +Fit a function to the spectrum using the ICFIT mode. Typically +interactive rejection is used to exclude spectra lines from the fit +in order to fit a smooth continuum. A second keystroke +selects what to do with the fit. +.ls / +Normalize by the fit. When fitting the continuum this continuum +normalizes the spectrum. +.le +.ls -3 - +Subtract the fit. When fitting the continuum this continuum subtracts +the spectrum. +.le +.ls f +Replace the spectrum by the fit. +.le +.ls c +Clean the spectrum by replacing any rejected points by the fit. +.le +.ls n +Do the fitting but leave the spectrum unchanged (a NOP on the spectrum). +This is useful to play with the spectrum using the capabilities of ICFIT. +.le +.ls q +Quit and don't do any fitting. The spectrum is not modified. +.le +.le +.ls u +Adjust the user coordinate scale. There are three options, 'd' mark a +position with the cursor and doppler shift it to a specified value, +'z' mark a position with the cursor and zeropoint shift it to a specified +value, or 'l' mark two postions and enter two values to define a linear +(in wavelength) dispersion scale. The units used for input are those +currently displayed. A wavelength scale set this way will be used for +other spectra which are not dispersion corrected. +.le +.ls v +Toggle to a velocity scale using the position of the cursor as the +velocity origin and back. +.le +.ls w +Window the graph. For further help type '?' to the "window:" prompt or +see help under \fBgtools\fR. To cancel the windowing use 'a'. +.le +.ls x +"Etch-a-sketch" mode. Straight lines are drawn between successive +positions of the cursor. Requires 2 cursor settings in x. The nearest pixels +are used as the endpoints. To draw a line between arbitrary y values first +use 'j' to adjust the endpoints or set the "xydraw" option. +.le +.ls y +Overplot standard star values from a calibration file. +.le +.ls z +Zoom the graph by a factor of 2 in x. +.le +.ls ( +In multiaperture spectra go to the spectrum in the preceding image line. +If there is only one line go to the spectrum in the preceding band. +.le +.ls ) +In multiaperture spectra go to the spectrum in the following image line. +If there is only one line go to the spectrum in the following band. +.le +.ls # +Get a different line in multiaperture spectra or two dimensional images. +The aperture/line/column is queried. +.le +.ls % +Get a different band in a three dimensional image. +.le +.ls $ +Switch between physical pixel coordinates and world (dispersion) coordinates. +.le +.ls -4 - +Subtract the fits generated by the 'd' (deblend), 'k' (single profile fit), +and 'h' (gaussian of specified width). The region to be subtracted is +marked with two cursor positions. +.le +.ls -4 ',' +Shift the graph window to the left. +.le +.ls . +Shift the graph window to the right. +.le +.ls I +Force a fatal error interupt to leave the graph. This is used because +the normal interupt character is ignored in graphics mode. +.le + +.ls :show +Page the full output of the previous deblend and equivalent width +measurements. +.le +.ls :log +Enable logging of measurements to the file specified by the parameter +\fIsave_file\fR. When the program is first entered logging is enabled +(provided a log file is specified). There is no way to change the file +name from within the program. +.le +.ls :nolog +Disable logging of measurements. +.le +.ls :dispaxis +Show or change dispersion axis for 2D images. +.le +.ls :nsum +Show or change summing for 2D images. +.le +.ls :units +Change the coordinate units in the plot. See below for more information. +.le +.ls :# +Add comment to logfile. +.le +.ls Labels: +.ls :label