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/specplot.hlp | 387 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 387 insertions(+) create mode 100644 noao/onedspec/doc/specplot.hlp (limited to 'noao/onedspec/doc/specplot.hlp') diff --git a/noao/onedspec/doc/specplot.hlp b/noao/onedspec/doc/specplot.hlp new file mode 100644 index 00000000..222d77ff --- /dev/null +++ b/noao/onedspec/doc/specplot.hlp @@ -0,0 +1,387 @@ +.help specplot Jan96 noao.onedspec +.ih +NAME +specplot -- stack and plot multiple spectra +.ih +USAGE +specplot spectra +.ih +PARAMETERS +.ls spectra +List of spectra to plot. The spectra are assigned index numbers increasing +from one in the order of the list. +.le +.ls apertures = "" +List of apertures to plot. An empty list selects all apertures. +An aperture list consists of a comma separated list of aperture numbers or +hyphen separated range of numbers. A step size may also be specified preceded +by 'x'. See \fBranges\fR for more. +.le +.ls bands = "1" +List of bands to plot if the image is three dimensional. The list has +the same syntax as for the apertures. +.le +.ls dispaxis = 1, nsum = 1 +Parameters for defining vectors in 2D images. The +dispersion axis is 1 for line vectors and 2 for column vectors. +A DISPAXIS parameter in the image header has precedence over the +\fIdispaxis\fR parameter. These may be changed interactively. +.le +.ls autolayout = yes +Automatically layout the spectra by shifting or scaling to a common mean +and determining a separation step which does overlaps the spectra +by the specified fraction? The algorithm uses the following parameters. +.ls autoscale = yes +Scale the spectra to a common mean? If no then the spectra are shifted +to a common mean and if yes they are scaled to a common mean. +.le +.ls fraction = 1. +The separation step which just avoids overlapping the spectra is multiplied +by this number. Numbers greater than 1 increase the separation while numbers +less than 1 decrease the separation and provide some amount of overlap. +.le +.le +.ls units = "" +Dispersion coordinate units. If the spectra have known units, currently +this is generally Angstroms, the plotted units may be converted +for plotting to other units as specified by this parameter. +If this parameter is the null string then the units specified by the +world coordinate system attribute "units_display" is used. If neither +is specified than the units of the coordinate system are used. +The units +may also be changed interactively. See the units section of the +\fBonedspec\fR help for a further description and available units. +.le +.ls transform = "none" (none|log) +Transform for the input pixel values. Currently only "log" is implemented. +If all pixels are negative the spectrum values will be unchanged and if +some pixels are negative they are mapped to the lowest non-negative value in +the spectrum. Note that this cannot be changed interactively or applied +independently for each spectrum. To change the setting one must exit +the task and execute it with the new value. +.le +.ls scale = 1., offset = 0. (value, @file, keyword) +The scale and offset to apply to each spectrum. The value of the parameter +may be a constant value applying to all spectra, a file containing the +values specified as @ where is the filename, or an image +header keyword whose value is to be used. +.le +.ls step = 0 +The step separating spectra when not using the autolayout option. +The value of this parameter depends on the range of the data. +.le +.ls ptype = "1" +Default plotting type for the spectra. A numeric value selects line plots +while marker type strings select marker plots. The sign of the line type +number selects histogram style lines when negative or connected pixel +values when positive. The absolute value selects the line type with 0 +being an invisible line, 1 being a solid line, and higher integers +different types of lines depending on the capabilities of the graphics +device. The marker type strings are "point", "box", "plus", "cross", +"diamond", "hline", "vline", "hebar", "vebar", and "circle". +The types for individual spectra may be changed interactively. +.le +.ls labels = "user" +Spectrum labels to be used. If the null string or the word "none" is +given then the spectra are not labeled. The word "imname" labels the +spectra with the image name, the word "imtitle" labels them wih the +image title, the word "index" labels them with the index number, and +the word "user" labels them with user defined labels. The user labels +may be given in the file specified by the parameter \fIulabels\fR, which +are matched with the list of spectra, and also added interactively. +.le +.ls ulabels = "" +File containing user labels. +.le +.ls xlpos = 1.02, ylpos = 0.0 +The starting position for the spectrum labels in fractions of the +graph limits. The horizontal (x) position is measured from the left +edge while the vertical position is measured from the mean value of the +spectrum. For vertical positions a negative value may be used to label +below the spectrum. The default is off the right edge of the graph at +the mean level of the spectrum. +.le +.ls sysid = yes +Include system banner and separation step label? This may be changed +interactively using ":/sysid". +.le +.ls yscale = no +Draw a Y axis scale? Since stacked plots are relative labeling the Y +axes may not be useful. This parameter allows adding the Y axis scale +if desired. The default is to not have a Y axis scale. +.le +.ls title = "", xlabel = "", ylabel = "" +Title, x axis label, and y axis label for graphs. These may be changed +interactively using ":/title", ":/xlabel", and ":/ylabel". +.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 with 'w' cursor key or the cursor commands ":/xwindow" and +":/ywindow". +.le +.ls logfile = "" +Logfile to record the final set of spectra and scale factors displayed. +.le +.ls graphics = "stdgraph" +Output graphics device. One of "stdgraph", "stdplot", "stdvdm", +@(enviroment variable), or actual device. +.le +.ls cursor = "" +Graphics cursor input. When null the standard cursor is used otherwise +the specified file is used. +.le +.ih +DESCRIPTION +\fBSpecplot\fR plots multiple spectra with provisions for scaling them, +separating them vertically, shifting them horizontally, and labeling them. +The layout can be defined by an automatic algorithm or explicitly and +adjusted noninteractively (with some limitations) or interactively. The +plotting units can be selected and the vertical axis scale can be shown or +not as desired. This task is used for compressing many spectra to a page +for review, intercomparison of spectra, classification against standards, +and final display. + +The input list of spectra consists of one, two, or three dimensional images. +The set of spectra may be restricted to specific apertures using the +\fIapertures\fR parameter. Note that for true 2D images, such as long slit +spectra, the aperture number corresponds to the line or column to be plotted +and the dispersion axis and nsum parameter are determined either from the +image header or the package parameters. Spectra extracted +with the \fBapextract\fR package may be three dimensional where the 3rd +dimension corresponds to related data. The higher dimensional data is +also plotted though it may be restricted with the \fIbands\fR +parameter. + +Each spectrum has a number of associated parameters which are initially +assigned default values but which may be changed interactively. First each +spectrum is assigned an index number. This is generally sequential +starting from 1. Spectra added interactively are assigned the next higher +or lower index relative to the spectrum being appended or inserted. The +index is used for refering to parameters of a particular spectrum and for +separating the spectra vertically. The spectra are scaled and shifted by +the equation + + I = value * scale + offset + (index - 1) * step + +where "I" is the final plotted value, "value" is the pixel value, "scale" +is a multiplicative scaling, "offset" is a additive offset, and "step" is +an additive separation step used to stack spectra vertically. + +The default values of the vertical scaling parameters may be set by an +automatic layout algorithm or with explicit constants (the same for all +spectra). The automatic mode is selected with the parameter +\fIautolayout\fR and works as follows. All spectra are scaled or shifted +to a common mean (depending on the parameter \fIautoscale\fR) relative to +the lowest indexed spectrum. A step size is then computed to just avoid +overlapping of the minimum of one spectrum with the maximum of another. +Note that this may not yield a good layout if the spectra have large +continuum slopes. Finally, to add some extra space between the spectra or +to allow some overlap, the minimum step is multiplied by a specified +overlap factor, \fIfraction\fR. + +In nonautomatic mode the user specifies the intensity scale, offset, +and separation step explicitly with the parameters, \fIscale, offset\fR +and \fIstep\fR. If the step is zero then spectra will be directly +overplotted while a positive or negative value will separate the +spectra either upward or downward with the index 1 spectrum having no +offset. The scale and offset parameters may be specified as either +constant values, the name of file containing the values (one per line) +preceded by the '@' character, or the name of an image header keyword. +This parameter as well as the scale and offset may be set or +changed interactively via colon commands and the "offset" may also be +set using the cursor to shift a spectrum vertically. + +In addition to shifting spectra vertically they may also be shifted +horizontally as a velocity/redshift or a zero point change with either +cursor or colon commands. The dispersion, inteval per pixel, may be +modified, either with the 't' key or the "wpc" command, in which case if +the dispersion is nonlinear the spectra will be linearized. + +Each spectrum may have a label associated with it. The label type may +be the image name, the image title, the index number, or a user defined +label. The default label type is specified by the parameter +\fIlabels\fR. For user labels the initial labels may be specified in a +file. Interactively the label type may be changed using the ":labels" +command and the user assigned labels may be defined by a colon command +or by using the cursor to mark the position for the label. The label +position is given relative to the range of the graph and the mean +intensity. The default values are set by the parameters \fIxlpos\fR +and \fIylpos\fR. The positions may be changed interactively for all +the spectra or individually. The latter may be done using the cursor +to mark exactly where the label is to go. + +Each spectrum has an associated plotting type. The default type which +applies to all spectra initially is specified by the parameter +\fIptype\fR. This parameter specifies both whether line mode or +marker mode is used and the line type, line style, or marker type to use. +The line +mode and types are given by a small integers with the style, connected +pixel centers or histogram style, chosed by the sign of the integer. +The type of lines produced depend on the capabilities of the terminal. In most +cases a zero line type is invisible. (This may be used interactively +to temporarily eliminate a spectrum from a plot instead of deleting the +spectrum from the list of spectra). A line type of 1 is a solid line +and additional line types are specified by higher numbers. +The marker types are given by name as described in the parameter +section. There is currently no combination of line and marker (such as +connected points with vertical bars) or histogram type plotting. The +plotting type may be changed interactively for individual spectra or +for all spectra using colon commands. + +The cursor and colon commands generally apply to the spectrum nearest +the cursor. This is determined by finding the nearest data point to +the cursor. For the colon commands the spectrum may also be specified +explicitly by the index number using an optional suffix "[index]", where +index is the index number for the spectrum. Also the special index "*" +may be specified to apply to all spectra. + +The operations of adding, deleting, moving, or shifting spectra affect +the index numbers of the other spectra. When deleting a spectrum the +index numbers of all spectra with greater index numbers are decreased +by one resulting in the plotted spectra moving down (positive step). +When adding a spectrum the index numbers above the inserted spectrum +are increased by one resulting in the spectra moving up. Moving a +spectrum to a new index number is equivalent to deleting the spectrum +and then inserting it at the new index position. Spectra may be +shifted to insert gaps in the plotted spectra. The specified value is +added to all spectra above and including the one indicated if the value +is positive to all spectra below and including the one indicated if the +value is negative. +.ih +CURSOR COMMANDS + +The indicated spectrum is the one with a point closest to the cursor position. +.nf + +? - Print help summary +a - Append a new spectrum following the indicated spectrum +i - Insert a new spectrum before the indicated spectrum +d - Delete the indicated spectrum +e - Insert last deleted spectrum before indicated spectrum +f - Toggle between world coordinates and logical pixel coordinates +l - Define the user label at the indicated position +p - Define the label position at the indicated position +o - Reorder the spectra to eliminate gaps +q - Quit +r - Redraw the plot +s - Repeatedly shift the indicated spectrum position with the cursor + q - Quit shift x - Shift horizontally in velocity + s - Shift vertically in scale y - Shift vertically in offset + t - Shift horizontally in velocity z - Shift horizontally in velocity + and vertically in scale and vertically in offset +t - Set a wavelength scale using the cursor +u - Set a wavelength point using the cursor +v - Set velocity plot with zero point at cursor +w - Window the plot +x - Cancel all scales and offsets +y - Automatically layout the spectra with offsets to common mean +z - Automatically layout the spectra scaled to common mean +.fi +.ih +COLON COMMANDS + +A command without a value generally shows the current value of the +parameter while with a value it sets the value of the parameter. The show +commands print to the terminal unless a file is given. For the spectrum +parameters the index specification, "[index]", is optional. If absent the +nearest spectrum to the cursor when the command is given is selected except +for the "units" command which selects all spectra. The index is either a +number or the character *. The latter applies the command to all the +spectra. + +.nf +:show Show spectrum parameters (file optional) +:vshow Show verbose parameters (file optional) +:step Set or show step +:fraction Set or show autolayout fraction +:label Set or show label type + (none|imtitle|imname|index|user) + +:move[index] Move spectrum to new index position +:shift[index|*] Shift spectra by adding to index +:w0[index|*] Set or show zero point wavelength +:wpc[index|*] Set or show wavelength per channel +:velocity[index|*] Set or show radial velocity (km/s) +:redshift[index|*] Set or show redshift +:offset[index|*] Set or show intensity offset +:scale[index|*] Set or show intensity scale +:xlpos[index|*] Set or show X label position +:ylpos[index|*] Set or show Y label position +:ptype[index|*] Set or show plotting type +:color[index|*] Set or show color (1-9) +:ulabel[index|*] Set or show user labels +:units[index|*] Change coordinate units + +:/title Set the title of the graph +:/xlabel Set the X label of the graph +:/ylabel Set the Y label of the graph +:/xwindow Set the X graph range + (use INDEF for autoscaling) +:/ywindow Set the X graph range + (use INDEF for autoscaling) + + +Examples: + w0 Print value of wavelength zero point + w0 4010 Set wavelength zero point of spectrum nearest the cursor + w0[3] 4010 Set wavelength zero point of spectrum with index 3 + w0[*] 4010 Set wavelength zero point of all spectra +.fi +.ih +EXAMPLES +1. To make a nice plot of a set of spectra with the default layout: + + cl> specplot spec* + +2. To set the colors or line types for multiple spectra in a batch +mode application create a cursor file like: + + cl> type cursor.dat + :color[1] 2 + :color[2] 3 + :color[3] 4 + r + cl> specplot im1,im2,im3 cursor=cursor.dat + +Note that the 'r' key is necessary redraw the graph with the changed +attributes. +.ih +REVISIONS +.ls SPECPLOT V2.11 +The scale and offset parameters may now be a value, a filename, or +and image header keyword. + +The 'f' key was added to toggle between world and logical pixel coordinates. +.le +.ls SPECPLOT V2.10.3 +A color parameter was added for graphics terminals supporting color. + +The :units command was extended to have an optional spectrum specifier. +This is primarily intended to plot different (or the same) spectra in +velocity but with different velocity zeros. + +The default task units parameter has been changed to "" to allow picking +up a "units_display" WCS attribute if defined. +.le +.ls SPECPLOT V2.10 +New parameters were added to select apertures and bands, plot +additional dimensions (for example the additional output from the extras +option in \fBapextract\fR), suppress the system ID banner, suppress the Y +axis scale, output a logfile, and specify the plotting units. The \fIptype\fR +parameter now allows negative numbers to select histogram style lines. +Interactively, the plotting units may be changed and the 'v' key allows +setting a velocity scale zero point with the cursor. The new version +supports the new spectral WCS features including nonlinear dispersion +functions. +.le +.ih +NOTES +The automatic layout algorithm is relatively simple and may not +provide visually satisfactory results in all cases. The fonts and Y axis +scale capabilities are not as good as might be desired for publication +quality plots. +.ih +SEE ALSO +bplot, splot, onedspec, gtools, ranges +.endhelp -- cgit