specplot spectra
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 sperated 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.
scale = 1., offset = 0.
Default intensity scaling and offset.
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.
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. 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.
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
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.
:showShow 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
EXAMPLES 1. To make a nice plot of a set of spectra with the default layout:
cl> specplot spec*
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.
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.
bplot, splot, onedspec, gtools, ranges,