| sgraph | stsdas.graphics.stplot | sgraph |
sgraph -- Graph one or more lists, image sections, or tables.
sgraph input
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.
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.
Currently, only the PostScript kernel psikern plots in color through PostScript, to a printer or viewer.
"image" "text_file" "table y_col" "table x_col ycol" "table1 x_col table2 ycol"
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+
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.
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.
pcol, pcols, prow, prows, dvpar, pltpar, axispar, grplot, igi, stdgraph, psikern, sgikern