tabplot -- Graph one or more lists, image sections, or tables.
Tabplot is a macro task that calls the task sgraph in the Tables package.
This task will graph one or more lists, image sections, or table columns. 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 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.
- 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 tabplot command to edit tabplot 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 tabplot 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 tabplot. 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)
Note that you need to run tabplot more than once to draw a curve or symbols as well as error bars. The tabplot 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 = -3That 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:
tabplot.input = "ebt3.dat" dvpar.device = "stdgraph" dvpar.append = yes tabplot.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:
tabplot.input = "ebt4 a b" dvpar.device = "stdgraph" dvpar.append = yes tabplot.pltpar = "" pltpar.pointmode = no pltpar.erraxis = 1 tabplot.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 tabplot. 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 tabplot. 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 tabplot will appear extended in the X dimension unless fill = no.
- The tabplot 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.
- input [string]
- List of operands to graph. Input can be interactively entered by specifying STDIN for input. The input source can also be one or more image sections, tables and columns, or lists.
- 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 tabplot 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 tabplot 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 tabplot or from the cl, eparam pltpar or simply pltpar. Details about these parameters are available by typing "help axispar".
1. Plot the output of a list processing filter.
cl> ... list_filter | tabplot
2. Plot a graph using data entered interactively from the terminal.
cl> tabplot STDIN
3. Overplot two lists.
cl> tabplot list1,list2
4. Graph line 128 of image "pix".
cl> tabplot pix[*,128]
5. Graph the average of columns 50 through 100.
cl> tabplot pix[50:100,*] axis=2
6. Graph two columns from a table against each other.
cl> tabplot "table xcol ycol"
7. Graph a list in point plot mode.
cl> tabplot list po+
8. Annotate a graph.
cl> tabplot pix[*,10],pix[*,20] xlabel=column\ >>> ylabel=intensity title="lines 10 and 20 of pix"
9. Direct the graph to the standard plotter device.
cl> tabplot list device=stdplot
10. Draw a set of points with superimposed error bars. The data are from columns "x" and "y" in the STSDAS table mydata. Upper and lower errors are in the columns "upper" and "lower", respectively.
cl> tabplot "mydata x y" point+ marker=cross cl> tabplot "mydata x y" point- errax=2 errcol="lower upper" append+
INDEF values are not recognized when computing image projections.
STSDAS images that are specified with an extension (including those whose extension is not .hhh and .hhd) will be treated as text files, causing an error. The workaround is to include an image section specification, e.g., set input to "image.abh".
There is an inherent ambiguity between image section notation and file name template notation. tabplot 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 tabplot thinks "[1-3]" is an invalid image section instead of a range specification.