sddsplot supports various flavors of Postscript, various windows options, and numerous graphics terminals. For X-windows, a GUI interface is generated that supports zoom/pan, cursor readout, movie mode, and much more.
sddsplot has a very large number of options and is very flexible. In most cases, only a very few of these options are employed. In order to make best use of sddsplot, it helps to be familiar with certain concepts.
sddsplot supports multiple ``plot pages'' and multiple ``panels'' per page. In this context, a ``plot page'' is a separate sheet of paper for hardcopy devices, and the equivalent for interactive devices. For example, when using the X-windows interface just described, separate plot pages are held in memory so that the user may go back and forth between them rapidly, or run them as a movie. A plot page may contain several nonoverlapping panels, each displaying essentially independent graphics. Presently, sddsplot divides the plot page into an array of plot panels, each of equal size. The default is one plot panel per plot page.
Within each plot panel, sddsplot may display data from any number of ``plot requests''. A plot request is a specification to sddsplot of what data to plot from what files, and how to do it. A plot request must contain or indicate a list of names of columns and parameters to display, as well as the names of one or more files from which to extract the data. The data from plot requests are organized into plot panels and plot pages according to certain defaults or explicit instructions. One frequent choice is to move to a new panel for each plot request. However, one may also regroup data to display data from different plot requests together.
For each request, the names of columns and parameters are grouped to form sets of sets of data element names. For example, -columnNames=s,(betax,betay,etax) results in formation of three sets of pairs: (s, betax), (s, betay), and (s, etax). In a more complicated example, the sets of dataname sets might include names of error-bar data (e.g., (x, y, ySigma)) or vector components (e.g., (x, y, Ex, Ey)). To avoid confusion, a set of datanames like those just listed will be referred to as a ``name group''. Each name group for a request is given a sequential ``name index'', which can be used as shown in the last example above.
Each panel is divided into two regions, a ``plot space'' (or ``pspace'') and a ``label space''. The pspace is the region where data is displayed. Outside the pspace is the label space, where labels and legends normally appear.
Any point on any plot panel can be referenced by unit coordinates that start at zero in the lower left corner of the panel and end at unity in the upper right corner. The extent of the pspace is given in these coordinates. By default, the region the pspace occupies in these coordinates is [0.15, 0.90]x[0.15, 0.90]. The extent of the pspace may be changed explicitly, or it may be altered implicitly by certain switches (e.g., to make room for legends). The data or user's coordinates, referred to as (x, y), are mapped onto this space, as are the ``pspace coordinates'', (p, q). The latter are [0, 1]x[0, 1] coordinates.
When sddsplot reads data in from files, it collects it into internal data sets. By default, each of these internal data sets contains the all of the data for one name group from one file. That is, an internal data set normally contains all of the data for a name group from an SDDS data set. The phrase ``internal data set'' is used to maintain the distinction between the SDDS data set and the representation of data from an SDDS data set within sddsplot. Associated with each internal data set is the request number, the filename, the file number within the request, the y dataname, the name group index within the request, the starting page number from the file, and an optional user-specified tag value (from the commandline or a parameter in the file). These values may be used to sort and group the data in order to place on individual panels sets of similar data from multiple sources. An instance of this is shown in the last example above.
The sddsplot command line is organized into three categories. First, one may issue any of the standard X11 switches (e.g., -geometry). Second, one may give a set of switches, indicated by commonSwitches, that will apply to all subsequest plot requests.
Third, one gives a series of ``plot requests''. A plot request starts with one of several switches that give the names of data elements to be plotted. It continues with the names of one or more files from which this data is to be extracted. In addition, one may include various switches that apply only to current plot request. These may, for example, override any common switches that were set prior to the first plot request. In general, any switch may be given as a common switch (so that it applies to all plot requests unless overridden) or as a local switch.
In the examples above, only a single plot request is exhibited. There are no X11 switches and no common switches set. The plot request is initiated by the -columnNames switch. The -graphic and -legend switches are local switches.
Some types of plotting require additional data, such as error bars or vector components. These are specified with the x1Name and y1NameList. Each item in y1NameList is paired with the corresponding item in yNameList; the lists must have the same length. The interpretation of the additional data is specified with the -graphic=error or -arrow switches. For error bar plotting, one may give error bars for both x and y by giving x1Name and y1NameList, or for y only by giving y1NameList. For arrow plotting, giving y1NameList only is allowable for vectors perpendicular to the page. Giving both x1Name and y1NameList is required for vectors in the plane of the page.
One may give several -columnNames switches in a row in order to specify additional ``datanames'' for the request. This may be convenient if, for example, one wants several different x variables.
element may be one of line, symbol, errorBar, impulse, yimpulse, bar, ybar, dot, or continue. These are largely self-explanatory. continue specifies continuing whatever was done in the previous request. impulse is a line extending from y=0 to the data value, while bar is a line extending from the bottom of the plot region to the data value. yimpulse and ybar are analogous except that the line extends from x=0 or from the left-hand vertical border of the plot.
The type field for the graphic element has different meanings for different elements. For lines, impulses, bars, and dots, the type is the color or line style used, depending on the device. For most devices, values between 0 and 15 inclusive given unique lines. For symbols and error bars, the type specifies the style of symbol or error bar to use; the value is between 0 and 8 inclusive for symbols and between 0 and 1 inclusive for error bars.
The subtype field is meaningful only for symbols, error bars, and dots. It specifies the line style or color to be used in making a symbol or error bar, and the size for a dot. As for the type field for line plotting, the value may be between 0 and 15 inclusive. The connect qualifier is also valid for symbols and error bars only. It specifies that the symbols and error bars should be connected by lines. By default, the line type used is 0.
If one desires automatic variation of the line color, symbol type, and
so on, one may obtain this using the vary qualifier. By
default, the type is varied. The eachFile, eachPage,
eachRequest, or fixByName may be given to specify how to
assign type or subtype. For eachFile, variation is done
separately for data from different files. For eachPage,
variation is done separately for data from different pages (hence,
items from different pages would have the same line or symbol). For
eachRequest, variation is done separately for each request.
The fixByName qualifier in constrast assigns fixed graphic
attributes to items according to the y name.
autoScale specifies that the scale factor for the length of arrows should be chosen automatically; if several data pages are being plotted separately, the same scale is used for all of them. scale may be used instead of autoScale to set the factor manually; if both are given, then the factor given with scale multiplies that computed by autoScale.
linetype specifies the line type to use for the arrows, using the same mechanism as for lines in the -graphic switch. The default is 0.
cartesianData, polarData, and scalarData specify the type of data being provided. For the first two, one must have specified both x1Name and y1NameList in the plot request; for cartesianData, x1 and y1 are the x and y vector components, while for polarData x1 is the length and y1 is the angle in radians from the positive x direction.
centered specifies that arrows should be centered on the corresponding (x, y) point; by default, the arrow starts at the (x, y) point. singleBarb specifies that arrows should have only a single barb, rather than the default two barbs; this can be significantly faster for large amounts of data. barbLength and barbAngle specify the length and angle of arrow barbs; the barb length is a specified as a fraction of the arrow length, which the barb angle is specified in degrees.
The factor qualifiers specify factors to apply to the data values in producing the labels. For example, one might want to muliply small values by a power of ten in order to get labels that are of order units. The spacing values give the spacing of the ticks and labels with any factor included. I.e., to keep the same number of ticks, factor and spacing values must be increased together. Usually, giving the spacing qualifiers is unnecessary, since sddsplot chooses appropriate values.
The modulus qualifiers allow printing the modulus of the label value rather than the value itself; for example, one might use xmodulus=24 if x was the time in hours over many days. The size qualifiers permit specification of the size of the ticks as a fraction of the range in the opposing dimension; the default is 0.02. The linetype qualifiers specify the linetype to be used for ticks and grid lines, using integer values as for the -graph=line switch. The logarithmic qualifiers specify log-style ticks and labels; the implication is that the data being plotted is the base-ten logarithm of something.
tag is a quality of a dataset specified with the -tag option.
iNameString is the name string in inverse order (i.e., so that one compares namestrings
starting at the end rather than the beginning). These qualifiers are shared with the
groupBy and separate options.
yScalesGroup but for x axis scales.
The offset and scale qualifiers allow changing the position and size of the label. The offset is specified as a fraction of the vertical dimension of the plot region. The scale is simply a multiplicative factor.
Note that if the value of the parameter parameterName changes from page to page in a file, and if separate pages are plotted in different panels, then the label for each panel will be different. If the pages are plotted together, the value of the parameter from the first page will be used.
The coordinates of the string may be specified either in users coordinates (i.e., x and y), or unit coordinates (i.e., p and q); the unit coordinates are (0,0) at the lower left of the plot region and (1,1) at the upper right. scale permits changing the size of the letters by a specified factor. angle permits changing the angle of the string; a value of 90 gives upward vertical print.
Normally, text is ``left bottom'' justified, which means that the coordinates given are those of the left bottom corner of the first letter of the string. Justification may be changed with the justifyMode qualifier, which accepts a mode string of the form { l | r | c}{t | b | c}. The letters stand for Left, Right, Center, Top, and Bottom, respectively. The default justification would thus be specified as justify=lb.
The text is normally creating using line type 0. This may be changed with the linetype option. As with the other labels, the text may be edited using Toolkit editing commands (SDDS editing).
. The invert qualifiers cause the offset to be subtracted
rather than added.
If -factor is given together with -offset, then the offset is applied first.
Invokes one or more standard transformations of data, independently for x and y values. The linear mode is the default. normalize mode directs that data be displayed after independent normalization to the interval [-1, 1]; to do this, the data is divided by the maximum absolute value in the data. The offset, center, and meanCenter qualifiers result in shifting of the data: offset directs that data be shifted so that the first value plotted is zero; center directs that data be shifted the center of the range is zero; meanCenter directrs that the data be shifted so that the average plotted value is zero.
logarithmic mode implies that the base-ten logarithmic of the appropriate values is taken prior to plotting. Normally, this does not produce log-type scales; use of the specialScales keyword together with the logarithmic keyword will obtain this. One can also use the -tickSettings option for this, which is the preferred method.
enumerated value; the default is 1. Also, limit=M specifies displaying and making a tick for only 
enumerated values at equal
spacing; the default is unlimited. If one of these options is employed but one desires to see all
the ticks (even those without labels), the allTicks qualifier may be given. scale
specifies a factor by which to increase the size of the text. rotate specifies rotation of the
printed text from the normal orientation to the optional orientation; if enumerated data is displayed
along the x dimension, the normal (optional) orientation is vertical (horizontal) printing. These
are reversed if the enumerated data is displayed along the y dimension.
The overlay feature allows displaying data that has different scales on the same plot. In most cases, it is superseded by the -yScalesGroup and -xScalesGroup options. The only exception is when one wants to overlay data without having scales shown for the data. (An example is plotting magnet layouts for Twiss parameter plots using the magnets output from elegant.)
-overlay=[{x|y}mode=mode][,{x|y}factor=value] [,{x|y}offset=value] [,{x|y}center]--Normally, sddsplot displays all data on a single panel on the same scale. In some cases, one wants to overlay data that is on a different scale from other data on the panel. One way to do this is with the -overlay switch, which gives convenient control of how overlayed data is displayed. Any data in a plot request for which this switch is given will be overlayed as specified.
The xmode and ymode options allow two types of scaling for x and y independently. A mode of normal means that the indicated data is treated normally. The default mode is unit, which means that the data is scaled so that its full range is equal to the full coordinate range of the plot in the appropriate (x or y) dimension.
The data is further adjusted according to any additional qualifiers given. The center qualifiers offset the data so that the data is centered in the plot space; normally, zero in the data is mapped to zero in the user's coordinates. The factor qualifiers scale the data by the given factor about the center value. The offset qualifiers offset the data by specified amounts; if mode=normal, the offset is in user's coordinates, otherwise it is in pspace coordinates.
Users needing only the factor facility should consider the -factor switch, since it is easier to use.
The xgap and ygap qualifiers invoke a more sophisticated and more generally applicable form of severing. For each dimension for which severing is requested, the pen is lifted whenever the absolute difference of two successive values exceeds a defined limit. This limit is specified either in absolute or fractional terms using the value entry. If value is positive, the gap threshold is equal to value. If value is negative, the gap threshold is -value times the mean spacing between successive points; a value of -1.5 has been found to work well for data that is roughly equispaced with occasional missing points.
The order in which the qualifiers to -groupBy are given determines the priority of sorting by the various criteria. In the default ordering, data sets are sorted by request number, subsorted by tag (usually a null operation unless data is tagged by the user), subsubsorted by file index, subsubsubsorted by dataname index, etc. Each successive qualifier results in moving the indicated sort criterion to the next highest priority. Any qualifiers not given are retained in the default order.
If one wanted to bring together, for example, internal data sets with the same data name, one would give -groupby=nameString. In this case, the new sorting priority would be nameString, request, tag, etc.
If one of the other qualifiers is given, then panel separation occurs when the indicated criterion changes as the data sets are accessed in sorted order. Most commonly, one uses -groupby=criterion -separate=criterion. For example, one might want to group by filename and separate by filename.
The simplest and most commonly-used way of doing this is to split the data page boundaries; this is done using the -split=pages mode. The optional interval specifies spliting after a specified number of page boundaries. Splitting data does not imply that the data will appear on separate plot panels, but allows this and other possibilities. (To separate page-split data onto panels, one uses -separate=pages, as discussed above.)
One can also page-split based on the value of a parameter, using -split=parameterChange. This directs that a new internal data set will be started wheneven the named parameter changes. For numeric parameters, the width and start qualifiers may be used. If width is specified, the change must exceed the given value before a split occurs. If start is specified, the reference value for changes is set to the given value; otherwise, the first parameter value is used. (For example, one might wish to split when a parameter changed by 5 units referenced from 2.5 units, giving boundaries of 7.5, 12.5, etc.; this would be obtained with width=5,start=2.5.)
The columnBin mode is different from the other two modes. Rather than splitting data into internal data sets at page boundaries, it groups or bins data into subpages according to the value in a specified numeric column. (It is appropriate only for plotting column data.) columnBin mode may be used with pages mode to split and subsplit data into pages and subpages. For example, one might have a data file with many pages of time-series data. One might want to plot each page separately, but within each page one might want to color-code the points according to some value in the table (e.g., a valid-data indicator). This would be accomplished using -split=pages,columnBin=name,width=value -separate=pages -graph=dot,vary,eachPage.
The autoscaling qualifier specifies that sddsplot will not remove data outside the defined limits, but rather that it will ignore it for purposes of autoscaling. If lines are used to connect data points, this could result in lines being drawn to the boundary of the plot region, thus showing the presence of extreme points.
point will be used. If offset is not given, the first point in the internal data set is
the first taken; otherwise, the offset point is the first taken.
! signifies logical negation. A point passes a column-based filter if the value in the
named column is inside (or outside, if negation is given) the specified range, where the endpoints
are considered inside. parameter-based filters are similar, except that the point passes only
if the value of the named parameter for the page from which it comes is acceptable. One or more
range specifications may be combined to give a accept/reject status by employing the logic-operations, & (logical and) and SPMamp|& (logical or).
The use of several match tests and logic is done just as for -filter. For example, to match all the rows for which the column Name starts with 'A' or 'B', one could use -match=column,Name=A*,Name=B*,|. (This could also be done with -match=column,Name=[AB]*.)
motif device type and the following device argument:
-device=motif,''-movie true -keep 1''.
x0Value=1.7) or via a parameter (e.g., x0parameter=alpha). If a parameter is
given, the coordinate can change as the parameter value changes in the file.
$character, where character may be one of the following:
$g switches into Greek mode, while $r
switches back to Roman mode. The correspondance between Greek
characters and the alphabet is shown in Figure 1. For
example, to make a lower-case alpha, one would use $ga$r.
$s switches to special character mode,
which provides mathematical and other symbols. Figure 1
shows the correspondance between special characters and keyboard
characters. For example, to make a 
symbol, one would
employ $sa$e, while a right-pointing arrow would be obtained
with $s5$e.
![\includegraphics[width=\columnwidth,height=15cm]{charSet.eps}](img34.gif)
$i and $d are
inverses of each other. $i increases the size of subsequent
characters by 50%, while $d decreases the size of subsequent
characters by
%. These are seldom used, since
sddsplot provides other means of controlling the size of
characters in labels and strings.
$t makes characters twice as
tall while maintaining width, while $f makes characters half as tall while maintaining width.
The GUI X-windows program (mpl_motif) was written by K. Evans of ANL/APS.
The GIF drivers use the gd 1.2 library by Thomas Boutell. The latter is copyrighted by the Quest Protein Database Center, Cold Spring Harbor Labs.