| tabplot | xray.xplot | tabplot |
tabplot -- Graph one or more lists, image sections, or tables.
tabplot input
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.
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 = -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:
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.
Currently, only the PostScript kernel psikern plots in color through PostScript, to a printer or viewer.
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.