specplot: Stack and plot multiple spectra

Package: irs

Usage

specplot spectra

Parameters

spectra: List of spectra to plot. The spectra are assigned index numbers increasing from one in the order of the list.

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 ranges for more.

bands = "1": List of bands to plot if the image is three dimensional. The list has the same syntax as for the apertures.

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 dispaxis parameter. These may be changed interactively.

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.

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.

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.

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 onedspec help for a further description and available units.

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.

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 @<file> where <file> is the filename, or an image header keyword whose value is to be used.

step = 0: The step separating spectra when not using the autolayout option. The value of this parameter depends on the range of the data.

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.

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 ulabels, which are matched with the list of spectra, and also added interactively.

ulabels = "": File containing user labels.

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.

sysid = yes: Include system banner and separation step label? This may be changed interactively using ":/sysid".

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.

title = "", xlabel = "", ylabel = "": Title, x axis label, and y axis label for graphs. These may be changed interactively using ":/title", ":/xlabel", and ":/ylabel".

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".

logfile = "": Logfile to record the final set of spectra and scale factors displayed.

graphics = "stdgraph": Output graphics device. One of "stdgraph", "stdplot", "stdvdm", @(enviroment variable), or actual device.

cursor = "": Graphics cursor input. When null the standard cursor is used otherwise the specified file is used.

Description

Specplot 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 apertures 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 apextract 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 bands 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 autolayout and works as follows. All spectra are scaled or shifted to a common mean (depending on the parameter autoscale) 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, fraction.

In nonautomatic mode the user specifies the intensity scale, offset, and separation step explicitly with the parameters, scale, offset and step. 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 labels. 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 xlpos and ylpos. 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 ptype. 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.

Cursor commands

The indicated spectrum is the one with a point closest to the cursor position.

? - 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

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.

:show <file>               Show spectrum parameters (file optional)
:vshow <file>              Show verbose parameters (file optional)
:step <value>              Set or show step
:fraction <value>          Set or show autolayout fraction
:label <value>             Set or show label type
                                (none|imtitle|imname|index|user)

:move[index] <to_index>    Move spectrum to new index position
:shift[index|*] <value>    Shift spectra by adding to index
:w0[index|*] <value>       Set or show zero point wavelength
:wpc[index|*] <value>      Set or show wavelength per channel
:velocity[index|*] <value> Set or show radial velocity (km/s)
:redshift[index|*] <value> Set or show redshift
:offset[index|*] <value>   Set or show intensity offset
:scale[index|*] <value>    Set or show intensity scale
:xlpos[index|*] <value>    Set or show X label position
:ylpos[index|*] <value>    Set or show Y label position
:ptype[index|*] <value>    Set or show plotting type
:color[index|*] <value>    Set or show color (1-9)
:ulabel[index|*] <value>   Set or show user labels
:units[index|*] <value>    Change coordinate units

:/title <value>            Set the title of the graph
:/xlabel <value>           Set the X label of the graph
:/ylabel <value>           Set the Y label of the graph
:/xwindow <min max>        Set the X graph range
                                (use INDEF for autoscaling)
:/ywindow <min max>        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

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.

Revisions

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.

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.

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 apextract), suppress the system ID banner, suppress the Y axis scale, output a logfile, and specify the plotting units. The ptype 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.

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.