4.79 sddsplot

• description: sddsplot is a general purpose device-independent graphics program for displaying parameter and column data from SDDS files. The program is equally capable of quick-and-dirty plots and publication quality graphics. It allows organization of large amounts of data from multiple files into useful plots with minimal effort. It provides line, point, symbol, impulse, error-bar, and arrow plotting, with automatic variation of color, linetype, etc. It can do data winnowing using the data to be graphed or other data in the file. Parameters from a file can be designated for use as plot labels, legends, or for placement on the plot in specified locations. Data pages may be tagged and sorted by multiple criteria.

  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.

• examples: Plot the horizontal beta function for the APS design:
  sddsplot -columnNames=s,betax APS0.twi  
      

  Plot the Twiss functions for the APS design, using different line types for each quantity:

  sddsplot -columnNames=s,’(beta?,etax)’ APS0.twi -graph=line,vary  
      

  Plot the Twiss functions for APS lattices, one plotting page per lattice (i.e., per data page), with different linetypes and a legend:

  sddsplot -columnNames=s,’(beta?,etax)’ APS.twi -graphic=line,vary -legend  
          -split=page -separate=page  
      

  Plot the Twiss functions for APS lattices, one plotting page per function, with each data page shown with a different line type:

  sddsplot -columnNames=s,’(beta?,etax)’ APS.twi -graphic=line,vary  
          -split=page -groupby=nameIndex -separate=nameIndex  
      

  Plot the Twiss functions for the APS design, using a common scale for the beta functions and another for eta:

  sddsplot -graphic=line,vary APS0.twi -columnNames=s,beta? -yScalesGroup=id=beta  
  -columnNames=s,etax -yScalesGroup=id=eta  
      

• sddsplot concepts: 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.

• synopsis:
  sddsplot [X11Switches] [commonSwitches]  
  plotRequestSwitch fileNames localSwitches  
  [plotRequestSwitch fileNames localSwitches ...]  
    

  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.

• switches:
  • Initiating a plot request:
    
    • -columnNames=xName,yNameList[,{y1NameList | x1Name,y1NameList}] — Specifies the names of columns to be plotted. xName may be the name of a numeric or string column, which is normally plotted against the horizontal or x axis. yNameList gives the comma-separated, optionally wildcarded names of one or more columns of numeric data. Data for each item in yNameList will be paired with the x data for plotting.

      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.

    • -xExclude=xNameList— specifies the names of x columns to be excluded from the plot. xNameList gives the comma-separated, optionally wildcarded names of one or more columns.
    • -yExclude=yNameList— specifies the names of y columns to be excluded from the plot. yNameList gives the comma-separated, optionally wildcarded names of one or more columns.
    • -toPage=pagenumber— specifies the page number to which sddsplot plots.
    • -fromPage=pagenumber— specifies the page number from which sddsplot plots.
    • -parameterNames=xName,yNameList[,{y1NameList | x1Name,y1NameList}]— Identical to -columnNames, except it specifies parameter data to be plotted. As with -columnNames, several such options may be given in a row in order to add datanames.
    • -arrayNames=xName,yNameList[,{y1NameList | x1Name,y1NameList}]— Identical to -columnNames, except it specifies array data to be plotted. As with -columnNames, several such options may be given in a row in order to add datanames.
    • -keep[={names | files}] — Rarely used. Specifies starting a new plot request, but retaining certain information from the previous request. If given without qualifiers, the datanames (as specified by -columnNames or -parameterNames) and filenames from the previous request are kept; this allows plotting the same data again in a different way. If the names qualifier is given, the datanames from the previous request are retained. If the files qualifier is given, the filenames from the previous request are retained.
    • -mplfiles[=noTitle][,noTopline] — Provided for compatibility with an older type of data file and rarely used. Allows plotting of mpl data files with sddsplot. The x and y columns of the mpl file are used. The qualifiers may be employed to inhibit use of the mpl plot title and topline.
    • -namescan={all | first} — Specifies whether sddsplot should scan all input files when searching for matches to wildcard datanames, or only the first. The default is to scan all files, which may be slow for many files with large numbers of columns or parameters.
  • Controlling output type:
    • -listDevices—Lists the names of available graphics devices to the standard error output.
    • -device=deviceName[,deviceArguments]—Specifies the name of the graphics device, plus optional device-specific arguments. The default device is “motif”, unless the SDDS_DEVICE environment variable if defined, in which case the default device is the one named. Some commonly-used devices that have device-specific arguments are:
      • motif — The device arguments are a single string of space-separated entries of the form -resourceName value. These are passed directly to the MOTIF “outboard-driver” without any interpretation.For example,"-dashes 1" qualifier sets the line types with built-in dash styles; "-linetype linetypeFileName " forces MOTIF ”outboard-driver” to use the user-defined line types (color,dash,thickness) in a SDDS file intead of the default line types. Other resource names may be found in the help for the driver.
      • qt — The device arguments are given as a space-separated string passed to the Qt driver. Valid options include -dashes <0|1>, -linetype <file>, -movie 1 [-interval <sec>], -keep <number>, -share <name>, -timeoutHours <hours>, and -spectrum.
      • postscript,cpostscript — Four qualifiers are presently accepted. dash sets the cpostscript device to use built-in dash styles for the line drawing. linetypetable=linetypeFileName replaces the default line types with the customized line types defined in a SDDS file. onblack and onwhite set the background of the plot.
      • png — PNG devices accept rootname, template, onwhite, onblack, dash and linetypetable device arguments. rootname=string specifies a rootname for automatic filename generation; the resulting filenames are of the form rootname.DDD, where DDD is a three-digit integer. template=string provides a more general facility; one uses it to specify an sprintf-style format string to use in creating filenames. For example, the behavior obtained using rootname=name may be obtained using template=name.%03ld.
      • mif — Three qualifiers are presently accepted. linesizeDefault=size sets the default line thickness (normally 0.25). dashsizeDefault=size sets the default dash size (normally 1.0). lineIncrement=value sets the line thickness increment between different line types.
      • gif, tgif, sgif, mgif, lgif — No longer supported, use png, tpng, spng, mpng, lpng instead.
    • -output=filename—Specifies the name of a file to which graphics output will be sent. Used primarily for hardcopy devices (e.g., Postscript) where the data will be sent to a printer. By default, the data for such devices is printed to the standard output.
  • Controlling type of plotting:
    • -graphic=element[,type=integer][,fill][,subtype={integer | type}] [,connect[={linetype | type | subtype}]][,vary[={type | subtype}]][,modulus=integer] [,scale=factor][,{eachFile | eachPage | eachRequest | fixForName | ] fixForFile | fixForRequest}] — Specifies the type of graphic element to use for data in the present plot request.

      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. For symbols, one may give the fill qualifier to get filled-in symbols.

      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, fixForName, fixForFile, and fixForRequest qualifiers 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 fixForName qualifier in constrast assigns fixed graphic attributes to items according to the y name. The fixForFile qualifier assigns fixed graphic attributes for items according to which data file they are from. The fixForRequest qualifier assigns fixed graphic attributes according to the request in which the data originates.

    • -arrowSettings=[,autoScale][scale=factor][,linetype=integer] [,centered][,singleBarb][,barbLength=value][,barbAngle=value] [,{cartesianData | polarData | scalarData}] —Specifies parameters for plotting vectors using arrows.

      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.

    • -linetypeDefault=integer[,thickness=value]— Specifies the default line type for borders, legend text, labels, axes, and so on. If not given, 0 is used.
  • Controlling the plotting region:
    • -scales=xmin,xmax,ymin,ymax—Specifies the region of the plot in user’s coordinates. If xmin and xmax are equal, then autoscaling is used in x, and similarly for y. Note that data outside the specified region is still plotted, so that proper clipping of lines occurs.
    • -range=[{x|y}Minimum=value][,{x|y}Maximum=value][,{x|y}Center=value] — Constrains the extent and center of the plot in user’s coordinates. xminimum specifies the minimum allowable horizontal extent of the plot; if the autoscaled (or user-specified) range is less than this, the range is increased symmetrically to this value. Similarly, xmaximum specifies the maximum allowable horizontal extent of the plot. xcenter specifies the center of the horizontal range without affecting the extent. The y options are the same, but for the vertical coordinates.
    • -unsuppressZero[=x][,y]—Specifies that x=0 and/or y=0 should be within the region of the plot. If given without qualifiers, both x and y are “unsuppressed”.
    • -sameScale[=x][,y][,global]—Specifies that separate panels of data shall be displayed on the same scales. In other words, any autoscaling is done based on all of the data from a request, rather than simply the data on a particular plot panel. If given without these qualifiers, both x and y are affected. global forces sddsplot to impose the desired condition across all plot requests.
    • -zoom=[{x|y}Factor=value][,{x|p}Center=value][,{y|q}Center=value] — Specifies zoom and pan starting from the scales set by autoscaling or by -scales. A factor less than (greater than) unity zooms out (in). For each dimension, one may specify the center of the plot using either the
    • -aspectRatio=value — Specifies the y/x aspect ratio of the plot. The value must be nonzero. If it is positive, then the desired aspect ratio is obtained by altering the pspace. If it is negative, the desired aspect ratio (the absolute value of the value given) is obtained by altering the data coordinate range.
    • -pSpace=hMin,hMax,vMin,vMax—This option is seldom used, but allows control of the region of the panel that is mapped to data coordinates, said region being the “plot space” or “pspace”. The first two coordinates give the horizontal extent, while the second two give the vertical extent. The coordinate values are between 0 and 1. The defaults are [0.15, 0.9]x[0.15, 0.9].
  • Controlling axes, numeric labels, ticks, and grids:
    • -axes[=x][,y][,linetype=integer]—Specifies that axes will be placed on the plot, if they are visible. By default, both x and y axes are created, with the same linetype as the labels, scales, and plot border. One may select a given axis by supply the x or y qualifier. One may specify the line type to use for the axes using the linetype qualifier.
    • -tickSettings=[,[{x|y}]grid][[{x|y}]spacing=value] [,[{x|y}]factor=value][,[{x|y}]modulus=value] [,[{x|y}]size=fraction][,[{x|y}]linetype=integer] [,[{x|y}]logarithmic] — Specifies how to make ticks and numeric labels for the x and y dimensions. All of the qualifiers have an x and y variant, e.g., xgrid and ygrid. Some have a variant that includes both x and y (e.g., grid). In the case of the grid option, xgrid specifies grid lines rather than ticks for the x dimension, ygrid is similar for the y dimension, and grid specifies grid lines in both dimensions.

      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.

    • -subTickSettings=[[{x|y}]divisions=integer][,[{x|y}]grid] [,[{x|y}]linetype=integer][,[{x|y}]size=fraction][,xNoLogLabel][,yNoLogLabel]—Specifies whether and how to make subticks or subgrid lines for the x and y dimensions. All of the qualifiers have two or more variants, one that applies to x, one that applies to y, and (in some cases) one that applies to both. For example, xgrid requests grid lines for x, ygrid requests grid lines for y, and grid requests grid lines for both x and y. The divisions qualifiers specify the number of subdivisions of the major tick intervals; the default is none. The linetype qualifiers specify the line type to use for subticks or subgrid lines. The fraction qualifiers specify the size of the subticks as a fraction of the plotting region; the default is 0.01. xNoLogLabel and yNoLogLabel specify whether plot subtick labels for log scale axis, they are only valid if the axis uses log scale.
    • -yScalesGroup={ID=string | fileIndex | nameIndex | nameString | page | request | tag | subpage | iNameString} — Specifies multiple vertical scales. The most common form is -yscalesGroup=namestring, which uses a separate scale for every separately-named quantity. Otherwise, one specifies a separate scale for items from different files (by file index), with different name index, different page, and so on. The 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.
    • -xScalesGroup — Identical to yScalesGroup but for x axis scales.
    • alignZero[={xcenter|xfactor|pPin=value}][,{ycenter|yfactor|qPin=value}] — This option is provides a facility for lining up zeros on plots with multiple axes. You must give at least one of the qualifiers. The xfactor and yfactor qualifiers request multiplication of the upper and lower limits for each scale by the smallest factors that will line up the zeros. The xcenter and ycenter qualifiers position the zeros at the center of the plot space, which may result in empty regions on the plot. The pPin and qPin allow specifying the point at which to “pin” the zeros, in plot-space coordinates (0 to 1).
    • -grid[=x][,y]—This option is superseeded by the -tickSettings option. It permits specification that grids (rather than ticks) will be used for major divisions.
    • -noScales—Specifies that no scales (i.e., no ticks, subticks, or numeric labels) will be plotted.
    • -noBorder—Specifies that no border will be made around the plot region. Implies -noScales.
  • Controlling text labels:
    • -xLabel=[{@parameterName | string} | use={name | symbol | description}][,units][,offset=value][,scale=value][,edit=string]—Controls size, placement, and content of the x dimension label, which appears directly under the scale labels. The default text is of the form symbol (units), where the symbol and units are taken from the column or parameter definition fields in the SDDS header for the x data. If the symbol is blank, then the element name is used. Alternatively, the text may be taken from a named string parameter, or from a string that is given explicitly, or the user may specify with the use qualifier that the element name, symbol, or descrpition be used. The user may also force the appearance of the units on the label using the units qualifier. The label text may be edited using Toolkit editing commands (??).

      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.

    • -yLabel—This switch has identical usage to -xLabel. -yLabel controls the y dimension label. The default text contains the y data names of all the columns and parameters being displayed. If the data all have the same units, the units are displayed as well. This information is taken from the appropriate entries in the SDDS header. The offset qualifier gives the label offset as a fraction of the horizontal dimension of the plot region.
    • -verticalPrint={up | down}—Specifies the direction of print for the y dimension label. The default is up.
    • -title—This switch has identical usage to -xLabel. The default text is from the contents field of the description command in the first file from which data is displayed.
    • -topTitle—Normally, the title goes below the x dimension label. This switch directs that it be placed at the top of the plot, above the “topline label”.
    • -topline—This switch has identical usage to -xLabel. It is blank by default.
    • -filenamesOnTopline—Directs that the topline text contain the names of the files from which data is displayed.
    • -labelSize=fraction — Obsolete: Specifies a common size for all labels, including numeric labels. In the original version of sddsplot, the fraction was the horizontal size of the characters as a fraction of the horizontal size of the plot region. This meaning is no longer precisely true because the new version doesn’t used fixed character sizes. However, this option may still be used to scale character sizes up and down. The previous nominal value for fraction was 0.03, which is now used as the reference point for scaling. Hence, if you specify 0.06, the character sizes would be doubled.
    • -noLabels—Specifies that no labels (i.e., x and y dimension labels, title, and topline label) will be made.
    • -string={@parameterName | string},{x|p}Coordinate=value {y|q}Coordinate=value[,scale=factor][,angle=degrees] [,justifyMode=mode][,linetype=integer][,edit=string] — Specifies display of string data on the plot. The string may either be extracted from a named string parameter or given explicitly. 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 (??).

    • -dateStamp—Directs that a time and date stamp be placed on the plot. It appears in the upper left corner of the plot.
  • Altering or rearranging data prior to plotting:
    • -swap—Specifies that the x data will be plotted as y and vice-versa.
    • -transpose—Specifies that the data matrix be transposed prior to plotting. This means, for example, that if the plot request specified N columns of y data and if the table contained M rows, one would get a plot of M quantities as a function of the index of the column. The implicit assumption is that the N columns contain comparable quantities. This would allow one to display, for example, how the quantities changed from row to row in the data. Each row of data thus organized is marked as a separate “subpage” (see the -groupBy and -separate switches), so that one can for example split rows onto separate panels.
    • -factor=[{x|y}Multiplier=value] — Specifies that the x and/or y data for the present request will be multiplied by the given values. Note that it is the users responsibility to ensure that the units that are displayed are corrected, if required.
    • -offset=[{x|y}Change=value][,{x|y}Parameter=value][,{x|y}Invert] — Specifies that the x and/or the y data be offset by either specified values, qor by values in named numerical parameters. Normally, the offset is of the form x → x+x_o. 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.

    • -mode={x | y}={linear | logarithmic | autolog | normalize | offset | coffset | center | meanCenter | fractionalDeviation | specialScales}[,...] —

      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, coffset, center, and meanCenter qualifiers result in shifting of the data: offset directs that data be shifted so that the first value plotted is zero; coffset directs the data to use a common offset from the first plot; center directs that data be shifted the center of the range is zero; meanCenter directs 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. autolog mode results in choice of linear or log-scale plotting based on the range of the data. If the range of the data is more than a factor of 15, then log mode is used (with log scales). Otherwise, linear mode is used.

      fractionalDeviation plots the data after subtracting and then dividing by the mean value.

    • -stagger=[xIncrement=value][,yIncrement=value][,files][,datanames] — Directs that data displayed on the same panel will be incrementally offset for display. This is useful in order to make mountain range plots, or to offset similar data for clarity. xIncrement and yIncrement are used to specify the increments for each dimension; zero is the default. Normally, only data from the same column or parameter is staggered, with the stagger amount increasing with each page in the file. The files qualifier directs incrementing the offset when plotting proceeds to a new file on the same panel. The datanames qualifier directs incrementing the offset when plotting proceeds to a new dataname (i.e., column or parameter name) within the same file on the same panel.
    • -enumeratedScales=[interval=integer][,limit=integer][,scale=factor] [,allTicks][,rotate][,editCommand=string] — Allows control of the display of enumerated value strings when the x data is of string type. interval=N specifies displaying and making a tick for every Nth enumerated value; the default is 1. Also, limit=M specifies displaying and making a tick for only M 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.
  • Creating legends and data labels:
    • -legend[={ {x|y}Symbol | {x|y}Description | {x|y}Name | filename | specified=string | parameter=name}] [,editCommand=string] [,firstFileOnly][,scale=factor] — Specifies creation of a legend for the datanames in the current request. By default, the legend text is the symbol field for the y data; if the symbol is blank, the dataname is used. xSymbol and ySymbol specify use of the x or y data symbols, or the datanames if the requested symbol is blank. xDescription and yDescription specify use of the indicated description fields. xName and yName specify use of the indicated datanames. filename specifies use of the name of the file from which the data comes. specified=string specifies use of the given string. parameter=name specifies use of the contents of the named string parameter. Any legend text may be editing using SDDS editing commands?? via the editCommand qualifier. If firstFileOnly is given, only the first file in the request will have legends generated. If scale=factor is given, the legend text size is scaled by the given factor.
    • -lSpace=qmin,qmax,pmin,pmax—Specifies the region in which legends will be placed. The coordinates are pspace coordinates. Since the legends are typically outside the pspace, the coordinates may be greater than unity. For example, the default values are [1.02, 1.18]x[0.0, 1.0]. This option is usually used to place the legend inside the pspace, or to extend the size of the lspace to accomodate long legend text.
    • -pointLabel=name[,edit=editCommand][,scale=number] [,justifyMode={rcl}{bct}] — Specifies labeling of individual data points using data from column or parameter name. The labels may be edited by specifying an editCommand with the edit qualifier. The scale qualifier may be used to scale the label size. The justifyMode qualifer is used to change the location of the label relative to the point; the first letter gives the horizontal justification (right, center, or left) and the second gives the vertical justification (bottom, center, or top). The justification mode may also be embedded in the string; if the string ends with $jXY, then X and Y are the horizontal and vertical justification, respectively, for that string.
  • Creating overlays:

    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.

  • Controlling plot panels:
    • -newPanel—Specifies that the current plot request will start a new plot panel.
    • -endPanel—Specifies that the current plot request will end the current plot panel.
    • -layout=hNumber,vNumber[,limitPerPage=integer]—Specifies the layout of panels on each plot page. The maximum number of panels on any page is the product of hNumber and vNumber, which are the number of panels horizontally and vertically, respectively. The default is hNumber=1 and vNumber=1. If limitPerPage is given, then only the specified number of panels will appear on any page; for example, -layout=2,2,limit=3 would imply three panel spaces per page, with one left blank.
  • Grouping, sorting, and separating data:
    • -sever[=xGap=value][,yGap=value]—For line plotting, sddsplot will normally connect points sequentially without regard for gaps in the data. The -sever switch specifies various means of locating gaps in data and directs lifting the “pen” whenever a gap occurs. If -sever is given without qualifiers, the pen is lifted whenever the x value decreases; this is useful for plotting data where the x value is expected to increase monotonically for each group of points.

      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.

    • -tagRequest={number | @parameterName}—Specifies that data from the current requested will be tagged with either the given (generally floating-point) number, or with the values from the numeric parameter parameterName. Using the -groupBy and -separate options permits grouping and sorting of data by tag values. If a data set has multiple pages in the file, and if pages are split (see -split below), then parameter-tagged data will have the parameter value from the first page in each group of pages.
    • -groupBy[=request][,tag][,fileIndex][,nameIndex][,page][,subpage] [,fileString][,nameString][,iNameString] — Specifies how internal data sets will be ordered. -sortBy might have been a more appropriate name for this switch. The qualifiers that appear in the list are shown in the order that corresponds to the default sorting. The file index is the sequential number within the request of the file from which the internal data set is taken; the file string is the name of the file. The name index is the sequential index within the request of the dataname group for the internal data set, while the name string is the name of the y data. The page is the sequential number in the file of the first SDDS data page from which data appears in the internal data set. The subpage is a sequential number within each internal data set, which allows subdivision of the internal data set. The request is the sequential number of the plot request that resulted in generation of the internal data set. The tag is a single user-supplied value or a value read from a parameter that is associated with each internal data set; by default, all data sets are tagged with the value 0. If a file is split into several internal data sets, each may have a different tag value if the tag is read from a parameter; in this case, the data sets are eached tagged with the value for the first included data page.

      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.

    • -separate[={numberToGroup | groupsOf=number | fileIndex | fileString | nameIndex | nameString | page | subpage | request | tag | iNameString}] — Specifies how to separate internal data sets onto panels. If given with no qualifiers, each internal data set is placed on a separate panel. If given with a single integer argument, or with the groupsOf qualifier, then the specified number of data sets appear on each panel; the data sets are assign to panels in the order determined by -groupBy or the default thereof.

      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.

    • -split={pages[,interval=integer] | parameterChange=name[,width=value][,offset=value] | columnBin=name,width=name[,start=value][,completely]}—As discussed in the introductory sections, when sddsplot reads data for one dataname group from a file, it normally concatenates data from successive pages to form a single internal data set. This would mean, for example, that all of the data from the file would be displayed with the same linetype or symbol. The -split switch overrides this behavior, splitting the data into multiple internal data sets.

      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.

    • -omniPresent—Specifies that the data sets from the current request will appear on all plot panels.
    • -replicate={number=integer | match={names | pages | requests| files}}{,scroll} — Specifies replication of a dataset so that it can be plotted several times. This is similar to -omniPresent, but more flexible. When a dataset is replicated, each replicant appears to have come from a different page of the original file. The number of replications is controlled by the first option: a specific number of replications can be requested, or it can be asked to replicate a number of times equal to the maximum number of pages in any file, data names in any request, plot requests, or files in any request. If the scroll qualifier is given, then the replicants do not have the same number of data points. Instead, successive copies are more and more complete until the final replicant has the full dataset.
  • Winnowing data:
    • -limit=[{x|y}Minimum=value][,{x|y}Maximum=value][,autoscaling]— Specifies limits to be placed on x and y values prior to plotting. Points beyond the indicated limits are eliminated from the data prior to plotting. This complements the facility available from -filter and -match in that one need not specify the name of the data one is winnowing with. This permits easier filtering of data from many columns or parameters.

      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.

    • -sparse=interval[,offset]—Specifies that only every intervalth point will be used. If offset is not given, the first point in the internal data set is the first taken; otherwise, the offsetth point is the first taken.
    • -sample=fraction—Specifies random sampling of data to retain only the indicated fraction of the points. fraction gives the probability that any point will be used. Hence, the data actually used may vary from run to run since the random number generator is seeded with the system clock.
    • -clip=head,tail[,invert]—Specifies removal of head points from the beginning and tail points from the end of each internal data set. If invert is given, the points that would have been removed are instead the only ones used.
    • -presparse=interval[,offset]—Similar to -sparse, except that sparsing is done at the time the data page is read and only once for all requests and datanames that draw data from the data page. This is faster, and is usually what is desired. However, if one wants to plot sparsed and unsparsed data from the same file at the same time, -presparse cannot be used. If both presparse and sparse are given, both are applied.
    • -filter={column | parameter},rangeSpec[,rangeSpec,logicOp...] — Specifies winnowing each internal data set based on numerical data in parameters or columns. A range-spec is of the form name,lower-value,upper-value[,!] , where ! 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 | (logical or).
    • -timeFilter={column | parameter},[before=YYYY/MM/DD@HH:MM:SS] [,after=YYYY/MM/DD@HH:MM:SS][,invert] — Specifies date range in YYYY/MM/DD@HH:MM:SS format in time parameters or columns. The invert option cause the filter to be inverted, so that the data that would otherwise be kept is removed and vice-versa. For example, if one want to keep data between 8:30AM on Januaray 2, 2003 and 9:20PM on February 6,2003, the option woould be -timeFilter=column,Time,before=2003/2/6@21:20,after=2003/1/2@8:30 assume that the time data is in the column Time.
    • -match={column | parameter},matchTest[,matchTest,logicOp] — Specifies winnowing based on data in string parameters or columns. A matchTest is of the form name=matchingString[,!], where the matching string may include wildcards. If the first character of matchingString is ’@’, then the remainder of the string is taken to be the name of a parameter or column. In this case, the match is performed to the data in the named entity.

      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]*.)

  • Miscellaneous:
    • -repeat[=checkSeconds=number][,timeOut=seconds] — Specifies repeated plotting of data from the files, with replotting occuring when any file is modified. By default, sddsplot checks the files every second and times out after 900s of no change. This is available on UNIX systems only. It is best used with the motif device type and the following device argument: -device=motif,’’-movie true -keep 1’’.
    • -drawLine= {x0Value=value|p0Value=value|x0parameter=name|p0parameter=name} {x1Value=value|p1Value=value|x1parameter=name|p1parameter=name} {y0Value=value|q0Value=value|y0parameter=name|q0parameter=name} {y1Value=value|q1Value=value|y1parameter=name|q1parameter=name} — Specifies drawing of lines on the plot by giving the two endpoints of the line. For each endpoint (labeled ’0’ and ’1’), one must specify the x or p coordinate (for horizontal) and the y or q coordinate (for vertical). Each coordinate name be specified explicitly (e.g., 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.
• special characters: sddsplot supports Greek and mathematical characters in labels and strings through special sequences embedded in text strings. A similar mechanism is used to allow character-by-character control over size and positioning. The special sequences are of the form $character, where character may be one of the following:
  • a, b, n: provide subscript and superscript control. a puts the character Above the normal position (superscript), b puts the character Below the normal position (subscript), and n returns to Normal.
  • g, r: provide for switching between Greek and Roman character sets. $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, e: provide for switching between Special and normal characters. $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.

    ---

    
    

    Figure 1: Special character set

    ---

  • i, d: provide for Increasing and Decreasing the character size. The two sequences $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 33%. These are seldom used, since sddsplot provides other means of controlling the size of characters in labels and strings.
  • u, v: provide for motion of the baseline Up and down by one half character height.
  • t, f: provide for making Taller and Fatter characters. $t makes characters twice as tall while maintaining width, while $f makes characters half as tall while maintaining width.
  • h: specifies moving back one half space.
• environment variables:
  • SDDS_DEVICE — Gives the name of the device type to use as the default.
• see also:
  • Data for Examples
  • ??
  • SDDS Wildcard Conventions()
• author: M. Borland, H. Shang and R. Soliday ANL/APS.
• acknowledgements: sddsplot uses device driver code from the program GNUPLOT, with modifications and enhancements made at Argonne. The GNUPLOT code is covered by a separate copyright, and is used by permission of the authors. See the GNUPLOT_README file included with the distribution for restrictions associated with this code.

  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.