path: root/noao/onedspec/doc/specplot.hlp

.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 @<file> where <file> 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 <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
.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