sgraph: Graph one or more image sections or lists.

Package: stplot

Usage

sgraph input

Description

This task will graph one or more lists, image sections, table columns or array elements from tables with arrays for elements of a column. Lists (text files) and image sections can be mixed in the 'input' parameter. If the curves are of different lengths, the plot will be scaled to the longest curve and curves will be left justified. If an image section has more than one dimension, the average projection will be computed and plotted along a designated axis. A unique dash pattern (up to 4) is used for each curve (by default).

Text can be interactively entered from the terminal keyboard, or it can come from a file; text input consists of a sequence of Y values, X and Y values, or X, Y, and marker size values. One pair of coordinates can be entered on each input line. Blank lines, comment lines, and extra columns are ignored. The first element in the list determines whether the list is a Y list or an X,Y list. An error occurs if an X,Y list has less than two coordinates. 'INDEF' values appear as gaps in the plot.

STSDAS and FITS tables can be used as input; they must be specified by a table name and column name, a table and two columns, or a pair of table and column names. The table name may be a file name template. Tables can have arrays as elements of a column. In order to plot these arrays, a row selector must be added to the filename to specify which row should be chosen for plotting. The arrays to be plotted would then be pulled from the column specified but only from the row given in the row selector. This imposes a limit in that only one row can be selected in the row selector, however, you can always specify a pair of table and column names, with each table name having a different row specified in the selector. The syntax of the row selectors can be found using "help selectors" in the 'TABLES' package.

Plot attributes -- the 'pltpar' pset: Plot attributes are defined in the 'pltpar' parameter set (pset). These parameters can be modified by using the 'pltpar' command, by editing the pset from within 'eparam', or by assigning values from the command line. If you are using the 'eparam sgraph' command to edit 'sgraph' parameters, only the 'pltpar' pset name appears in the parameter list. Typing ":e" on the 'pltpar' line will bring up the 'pltpar' parameters for modification; from within this screen, press CTRL-Z to return to the 'sgraph' parameter screen. (For more information on modifying 'pltpar' parameters, type "help pltpar"). Parameter sets can be saved for future use; type ":w <name>" from within the 'eparam' screen to save the parameters ("<name>" is the name of the file in which parameters are to be saved).

Error Bars

There are several ways to draw error bars using 'sgraph'. Errors can be the same size for each data point or variable, different for each data point. In the latter case, they also may be asymmetric. That is, the upper and lower error may differ. Variable error values may be specified from a list (ASCII text) file or STSDAS (binary or text) table. Note that you need to run 'sgraph' more than once to draw a curve or symbols as well as error bars. The 'sgraph' parameter 'append' should be set to "yes" on the second and subsequent executions. In all cases, the input error values specify the width of a single side of an error bar, interpreted as a "sigma" value, as in value +/- error. So the full size of the plotted error bar is twice the specified width for symmetrical errors in plotted user coordinates or the sum of the errors for asymmetric errors. Constant error bars are specified using the 'pointmode', 'marker', and 'szmarker' parameters in the 'pltpar' pset. For example, the following relevant parameter values will specify drawing vertical (in the Y direction) error bars of three units amplitude.


pltpar.pointmode = yes
pltpar.marker = "vebar"
pltpar.szmarker = -3

That is, Y value + or - 3. Note that the marker size is specified as negative, to distinguish the WCS value from NDC. Positive marker sizes refer to a fraction of the display size rather than the scaled plot coordinates. Variable size error bars must have error values input from a list or table. In both cases, one or two additional values per data point must be specified. The normal X and Y or simply Y values specify the coordinate of the error bar and the additional value or values specify its size. In addition, 'pltpar.pointmode' is turned off, and 'pltpar.erraxis' must be set to 1 for horizontal error bars (parallel to the X direction) or 2 for vertical error bars (parallel to the Y direction). You may select an error bar style in the 'pltpar.errtype' parameter:


"bartck"  traditional error bars, a line with a
          perpendicular tick at each end.
"bar"     The bar only, no ticks.
"tick"    The ticks only, no bar.
"limit"   Arrows representing upper or lower limits, pointing
          away from the data coordinate.

If the input data coordinates are in a list file, then the error values are in additional columns of the same file, in a third column or a third and fourth column. If there are three columns in the file, the first two are X and Y coordinates and the third is the error value (half size of the error bar). If there are four columns, the first two are the X and Y coordinate, the third is the lower error (-X or -Y direction) and the last column is the upper error (+X or +Y direction). Note that because of the ambiguity it is not possible to specify only Y values to be plotted against element number with error values. However, if you are not plotting error bars ('erraxis=0'), a single column indicates plotting Y values against element number. For example, the following relevant parameters will plot vertical error bars from data in the file "ebt3.dat" appended to an existing plot:


sgraph.input = "ebt3.dat"
dvpar.device = "stdgraph"
dvpar.append = yes
sgraph.pltpar = ""
pltpar.pointmode = no
pltpar.erraxis = 2
pltpar.errtype = "bartck"

If the input data coordinates are in a table, the error values must be in the same table. The column name or names are specified in the 'pltpar.errcolumn' parameter. If this string parameter is a single word (no spaces) then it must be the name of a single column whose values are interpreted as the half-size of symmetrical error bars. If there two words, they specify the names of two columns whose values are interpreted as the lower and upper errors, respectively. For example, the following relevant parameters will plot horizontal limit symbols from X and Y data in columns "a" and "b" and error values in columns "c" and "d" in the table "ebt4.tab" appended to an existing plot:


sgraph.input = "ebt4 a b"
dvpar.device = "stdgraph"
dvpar.append = yes
sgraph.pltpar = ""
pltpar.pointmode = no
pltpar.erraxis = 1
sgraph.errcolumn = "c d"
pltpar.errtype = "limit"

Note that data plotted as points or a curve need not come from the same file or format as the errors since they are overplotted in separate executions of 'sgraph'. However, the coordinates of the error bars themselves must be in the same file as the error values.

Different line and curve styles can be selected. Line styles are specified with the 'pattern' parameter, curve styles with the 'crvstyle' parameter. The value passed to 'pattern' will designate a style for the first line drawn; subsequent lines will alternate among the styles.

If 'append=yes', previous values for the 'box', 'fill', 'round', and viewport ('vx1' through 'vy2') and window ('wx1' through 'wy2') parameters are used.

Plots will fill the output device's viewport unless a viewport is specified by the user or calculated by 'sgraph'. Setting 'fill = no' will cause the viewport to be adjusted so that the X and Y scales match; plots will appear square regardless of the device's aspect ratio. On devices with a non-square device viewport (e.g., the vt640), a plot drawn by 'sgraph' will appear extended in the X dimension unless 'fill = no'.

Color: The 'sgraph' task can plot in color, as long as you use the appropriate device and graphics kernel (driver). You may specify the color of the plotted curve or curves separately from the color of the axes and labels. Use the 'crvcolor' parameter to specify the curve color and the 'color' parameter to specify the color of everything else. In addition, if you plot several curves on the same viewport (set of axes), each curve may automatically plot in one of eight different colors, analagous to plotting curves using different line styles. Use the 'cycolor' parameter to select this option. Currently, only the PostScript kernel 'psikern' plots in color through PostScript, to a printer or viewer.

Parameters

input [string]

List of operands to graph. The input source can be one or more images (or image sections), tables and columns, or lists. Input can be interactively entered by specifying "STDIN" for 'input'. If text data are piped to 'sgraph', the 'input' parameter will automatically be set to "STDIN". As described in the DESCRIPTION section, the task determines the type of input by the number of "words" in 'input':

"image"
"text_file"
"table y_col"
"table x_col ycol"
"table1 x_col table2 ycol"

errcolumn [string]: The table column name containing values interpreted as error values. If the source of the data is an STSDAS table, 'errcolumn' specifies the name of the column containing the errors.

(dvpar = "") [pset]: Pset name for device parameters. Parameters can be individually changed from the command line or can be edited as a group using ':e' from 'eparam sgraph' or from the cl, 'eparam pltpar' or simply 'pltpar'. Details about these parameters are available by typing "help pltpar".

(pltpar = "") [pset]: Pset name for plot parameters. Parameters can be individually changed from the command line or can be edited as a group using ':e' from 'eparam sgraph' or from the cl, 'eparam pltpar' or simply 'pltpar'. Details about these parameters are available by typing "help pltpar".

(axispar = "") [pset]: Pset name for axis and scaling parameters. Parameters can be individually changed from the command line or can be edited as a group using ':e' from 'eparam sgraph' or from the cl, 'eparam pltpar' or simply 'pltpar'. Details about these parameters are available by typing "help axispar".

Examples

1. Plot the output of a list processing filter.

cl> ... list_filter | sgraph

2. Plot a graph using data entered interactively from the terminal.

cl> sgraph STDIN

3. Overplot two lists.

cl> sgraph list1,list2

4. Graph line 128 of image "pix.imh".

cl> sgraph pix.imh[*,128]

5. Graph the average of columns 50 through 100.

cl> sgraph pix.imh[50:100,*] pltpar.axis=2

6. Graph two columns from a table against each other.

cl> sgraph "table xcol ycol"

7. Graph a list in point plot mode.

cl> sgraph list pointmode+

8. Plot a row from a table in which the columns contain arrays.

        cl> sgraph "table.fits[sci,1][r:row=10] wavelength flux"
-or-
        cl> sgraph "table.fits[4][r:sporder=10] wavelength flux"

9. Annotate a graph of "pix.c0h".

cl> sgraph pix.c0h[*,10],pix.c0h[*,20] xlabel=column\
>>> ylabel=intensity title="lines 10 and 20 of pix.c0h"

10. Direct the graph to the standard plotter device.

cl> sgraph list device=stdplot

11. Draw a set of points with superimposed error bars. The data are from columns "x" and "y" in the STSDAS table 'mydata.tab'. Upper and lower errors are in the columns "upper" and "lower", respectively.


cl> sgraph "mydata.tab x y" point+ marker=cross
cl> sgraph "mydata.tab x y" point- erraxis=2 \
>>> errcol="lower upper" append+

Bugs

'INDEF' values are not recognized when computing image projections.

There is an inherent ambiguity between image section notation and file name template notation. 'sgraph' uses image name template expansion to parse the input list. Therefore, it will not recognize some file name templates, for example: "file[1-3]" will fail because 'sgraph' thinks "[1-3]" is an invalid image section instead of a range specification.

References

The 'sgraph' task was developed primarily by Zolt Levay (STScI) as an enhancement and revision to the 'graph' task in the IRAF 'plot' package. The modifications to work with cell arrays were performed by Warren Hack.