AT&T Home | AT&T Labs | Research
AT&T Labs, Inc. - Research

The Yoix® Scripting Language

Home | What's New | Grammar | Documentation | Download | License | YChart | YDAT | YWAIT | Byzgraf | FAQs

Yoix / Byzgraf, a Set of Yoix Business Graphics Functions

Yoix has a powerful set of 2D drawing primitives similar in scope and capability to those available in Adobe's PostScript™ language. Byzgraf is a substantive and useful example of those capabilities. Byzgraf is a Yoix script file that can add highly configurable, interactive business graphics to any Yoix application.

[Image: Byzgraf line plot sample]

Figure 1. A Sample Line Plot

[Image: Byzgraf histogram sample]

Figure 2. A Sample Histogram

[Image: Byzgraf stat plot sample]

Figure 3. A Sample Stat Plot

Summary

The Byzgraf functions are contained in a single Yoix script file called byzgraf.yx and so can be easily added to any Yoix application by means of the Yoix include directive. With byzgraf.yx included, Yoix applications can generate business graphics using the ByzPlotImage function, described below in the Documentation section. The ByzCheckPointInPlot function, also described below, can be used to determine if a MouseEvent occurred within a rendered graphic and identifies the plot entity in terms of supplied labeling information. It will also return the corresponding point information in terms of the underlying data.

The Byzgraf plots also support robust, interactive resizing. Resizing causes layout and scaling to be recomputed in a manner that maintains sharp resolution and well utilizes available drawing space. When used in conjunction with the Yoix encodeImage function, Byzgraf can be useful for generating images for inclusion in viewgraphs or web pages.

The byzgraf.yx file and a sample usage script (byzgraf_sampler.yx) are available for download from our download page, just look for the Byzgraf link.

Sampler

Byzgraf currently supports three basic plot types, though it is possible we may add other types in the future and, certainly, readers are invited to provide code for new types to be included in byzgraf.yx. The currently supported plot types are:
  • Line plot
  • Histogram
  • Stat plot
You can see examples of these plot types in Figures 1, 2 and 3, respectively. Since Byzgraf is highly configurable, the plots in the figures should be taken as illustrating only the general plot type and not the many variations supported by Byzgraf for each plot type.

The byzgraf_sampler.yx script, which is available for download from our download page, includes twenty-one different Byzgraf usage examples. In addition, the script source shows how to use event handling to allowing resizing of the plot as the containing JFrame is reszied. Moreover, the sampler code shows how a mousePressed handler can trigger actions based on the plot entity selected or the value of the associated data point. Finally, each of the examples displayed by the sampler includes menu options for generating JPEG or PNG images of the currently displayed graph.

Documentation

This page (and the source) currently serve as the available documentation. The byzgraf_sampler.yx script also provides twenty-one usage examples. We think users will find these sources of information sufficient since, in essence, there are only three functions of interest in Byzgraf:
  • ByzPlotImage - the function that actually renders the plot. It returns a Dictionary containing the rendered plot image and parameters, including defaults, supplied values and generated values, that were involved in rendering it. Dumping the content of this Dictionary using, for example, toString and referring to the documentation below is recommended as an informative exercise. ByzPlotImage takes at least five arguments and, often, more. These arguments, in order, are:
    1. an int indicating the type of the plot. Recognized values are one of the pre-defined constants:
      • BYZGRAF_HISTOGRAM,
      • BYZGRAF_LINEPLOT and
      • BYZGRAF_STATPLOT.
    2. an Array of numeric values giving the X data points.
    3. an Array defining the Y data points. Whether this argument is a simple array of numeric values or, as is more often the case, a nesting of arrays of numeric values depends on the plot type and the specific variation of the plot type. More information on the formats for this array is given below.
    4. a Dictionary of dictionaries that provide minimum and maximum bounding information for each of the axes. A NULL value indicates all bounding information should be derived from the data. Specific missing values in the dictionary indicate that just those values should be derived.
    5. a String specifying the main title of the plot.
    6. the remaining arguments, if any, are zero or more pairings of arguments consisting of a String name and some Object value followed, optionally, by a Dictionary of values. In either case, the supplied values override the default values in the plot description dictionary described below.
  • ByzCheckPointInPlot - this function takes two arguments:
    1. a Point, which is usually the location field in a MouseEvent.
    2. a Dictionary, which should be the dictionary returned by the ByzPlotImage function.
    It returns a Dictionary, containing three String values called descA, descB and descC and one Point value called pt. If the point occurred outside a rendered data element, for example one of the lines in a line plot, then all the values will be NULL. If the point occurred on a rendered data element, then at a minimum descA and pt will be non-NULL. Whether descB and descC are NULL or not depends on the plot variation rendered. For example, a grouped, stacked historgram plot will have all three values defined using legend labels (i.e., stack component labels), primary X-axis labels (i.e., bar labels) and secondary X-axis labels (i.e., bar group labels) to populate descA, descB and descC, respectively. In short, sufficent values will be returned (assuming sufficent labeling was provided) to uniquely identify the data represented by the rendered plot component containing the point. In addition, the pt provides the data value, in terms of the primary X and Y axis data values, that corresponds to the location of the supplied point. Incidentally, the X axis values of that point is only meaningful for line plots.
  • ByzMapPointToData - this function takes two arguments:
    1. a Point, which is usually the location field in a MouseEvent.
    2. a Dictionary, which should be the dictionary returned by the ByzPlotImage function.
    It returns a Point that represents the data value corresponding to the location of the supplied point. This function will return a value whether or not the point occurs inside or outside of a rendered data element. In fact, a translation will be made even if the point falls outside the plot rectangle, say in the main title of the plot, by extrapolating from the main X and Y axes values of the plot.
Two aspects of specifying a Byzgraf plot that bear further explanation are the plot description dictionary and the various possible formats of the Y data array.

The Plot Description Dictionary

Typically, one creates a subset of the plot description dictionary that is used to override the defaults in the plot description dictionary when it is passed as an argument to ByzPlotImage. One need not create a separate description dictionary for each plot as the same dictionary can be used for all plots involving the same type of data since Byzgraf automatically adjusts axis labeling as needed based on the data. Although there are over sixty-five plot description dictionary elements, usually less than fifteen need to be specified. Note that constants beginning with the prefix BYZ in the tables below refer to values defined in the byzgraf.yx file. Also note that all values specifying a length or distance are 72 units per inch as is typical with Yoix technology.
Data Type Name Default Value Purpose
doublealpha1alpha (opacity level) for image background ranging from 0 to 1
ColorbackgroundNULLbackground color of plot area; the plot area is just the portion of the image where the plot data is presented
Dictionaryboundscalculated or passed as an argument to ByzPlotImagespecifies min/max axis bounds for primary x/y axes (denoted by sub-dictionaries called x and y, respectively, and containing numeric values for min and max) and secondary x/y axes (denoted by sub-dictionaries called x2 and y2, respectively, and containing numeric values for min and max)
ObjectcolorsNULLnormally an Array of Color objects for the data; however, when only a single color is specified, then there is no need for an array
Objectcolors2NULLcolor specification for secondary data (see xdata2 and ydata2)
ObjectdrawlinesNULL1/0 inidcator to suppress lines in a line plot; an array of 1/0 values can be used to suppress specific lines
Objectdrawlines2NULLline suppression for secondary data (see xdata2 and ydata2)
Stringfooter_centerNULLcenter footer text
Stringfooter_leftNULLleft footer text
Stringfooter_rightNULLright footer text
FontfooterfontTahoma-normal-8font for footer text
StringformatBYZFORMATformat for axis numbers using printf notation, e.g. %g
intgrid_horizontalFALSEset non-zero to get an horizontal grid with major-tick spacing
intgrid_verticalFALSEset non-zero to get a vertical grid with major-tick spacing
doublegridgrayBYZGRIDGRAYgray level ranging from 0 to 1 for shading grid
DimensionimagesizeNULLsize of complete image; leave NULL to compute based on plotsize and scaling
FontlabelfontTahoma-normal-12font used for axis labels (see also sublabelfont
ArraylegendNULLarray of strings for legend labels
Arraylegend2NULLlegend for secondary data (see xdata2 and ydata2)
FontlegendfontTahoma-normal-10font for legend labels
doublelegendgapBYZLEGENDGAPspacing between legend elements (a legend element includes both the label and the color/line graphic that maps to the rendered data)
doublelegendgrayBYZLEGENDGRAYgray level ranging from 0 to 1 for shading of legend bounding box
ObjectlinestylesNULLusually a simple 1/0 inidcator of line style for a line plot; however, an array of integer values can be used for greater control. A zero value leaves all data lines as solid, a non-zero value automatically selects a different line style for each data line. Line styles differ in terms of combinations of dashes, dots and gaps. When using an array, numbers can range between 0 and 15 corresponding to the 16 line styles defined through the ByzLineStyle funtion in byzgraf.yx
Objectlinestyles2NULLline styles for secondary data (see xdata2 and ydata2)
doublemajorticklengthBYZMAJORTICKlength of major tick
ObjectmarkersNULLusually a simple 1/0 inidcator of marking for a line plot; however, an array of integer values can be used for greater control. A zero value suppresses use of markers, a non-zero value automatically selects a different marker for each data line. Markers are small symbols of varying shape and configuration. When using an array, numbers can range between 0 and 15 corresponding to the 16 line styles defined through the ByzDrawMark funcion in byzgraf.yx
Objectmarkers2NULLmarkers for secondary data (see xdata2 and ydata2)
doubleminorticklengthBYZMINORTICKlength of minor tick
doublepaddingBYZPADDINGpadding around edge of image
DimensionplotsizeNULLsize of plot area. When NULL, a starting default defined by BYZPLOTSIZE is used. When non-null, a positive width or height keeps that dimension from varying to fill the available image size.
doublescaling1when imagesize is NULL, the image size depends on the size of the rendered plot and the scaling factor; when image size is set, the appropriate scaling factor is calculated
intsizetofit3indicates if both width and height of plot is to be sized to image area (value of 3), if only height is to be sized (value of 2), if only width is to be sized (value of 1) or if no sizing is to occur (value of 0)
doublespacerBYZSPACERspacing between various plot elements (e.g., between an axis label and the axis tick labels)
FontsublabelfontTahoma-normal-10font for axis sub-labels
StringsubtitleNULLtext for plot sub-title
FontsubtitlefontTahoma-normal-14font for plot sub-title
FonttickfontTahoma-normal-12font for tick labels
Stringtitlepassed as an argument to ByzPlotImagetext for plot title
FonttitlefontTahoma-bold-16font for plot title
inttypepassed as an argument to ByzPlotImagesets the plot style and should be one of BYZGRAF_HISTOGRAM, BYZGRAF_LINEPLOT or BYZGRAF_STATPLOT
Arrayxdatapassed as an argument to ByzPlotImagearray of numeric values for the x-axis corresponding to the data in ydata; this value is ignored by histograms and stat plots
Arrayxdata2NULLarray of numeric values for the x-axis corresponding to the data in ydata2; this value is ignored by histograms and stat plots and if ydata2 is NULL. If ydata2 is non-null, but xdata2 is not supplied, then it defaults to the value of xdata
StringxlabelNULLlabel for the bottommost x-axis
Stringxlabel2NULLlabel for the topmost x-axis
intxmajorticks0major tick count for the bottommost x-axis meaning that the x-axis is internally divided into this number of equal portions and a tick mark of length majorticklength is placed at each boundary (including the starting and ending points)
intxmajorticks20major tick count for the topmost x-axis; similar to xmajorticks
intxminorticks0minor tick count for the bottommost x-axis meaning that the x-axispace between major tick marks is internally divided into this number plus one of equal portions and a tick mark of length minorticklength is placed at each boundary (excluding the starting and ending points)
intxminorticks20minor tick count for the topmost x-axis; similar to xminorticks
StringxsublabelNULLsub-label for the bottommost x-axis
Stringxsublabel2NULLsub-label for the topmost x-axis
ArrayxticklabelsNULLtick labels for the bottommost x-axis; each string in the array is distributed along the access. These labels are independent of the tick marks and so they may not line up if the divisions do not match up. When only label is in the array, it is placed at the start of the axis.
Arrayxticklabels2NULLtick label for the topmost x-axis; similar to xticklabels
intxticktextTRUEsuppresses tick labels on the bottommost x-axis when zero
intxticktext2FALSEsuppresses tick labels on the topmost x-axis when zero
Arrayydatapassed as an argument to ByzPlotImagey-axis data points corresponding to xdata; see the following section for a complete description of this important input
Arrayydata2NULLy-axis data points corresponding to xdata2; the format is the same as ydata, but it has no effect on histograms or stat plots. For line plots, supplying this information creates, in essence, a second plot overlaid upon the first, with the topmost and rightmost axes being responsible for providing the accurate range information. Be sure to properly set related values such as ymajorticks2 and yticktext2 to make axes labeling visible.
StringylabelNULLlabel for the leftmost y-axis
Stringylabel2NULLlabel for the rightmost y-axis
intymajorticks0major tick count for the leftmost y-axis; similar to xmajorticks
intymajorticks20major tick count for the rightmost y-axis; similar to xmajorticks2
intyminorticks0minor tick count for the leftmost y-axis; similar to xminorticks
intyminorticks20minor tick count for the rightmost y-axis; similar to xminorticks2
StringysublabelNULLsub-label for the leftmost y-axis
Stringysublabel2NULLsub-label for the rightmost y-axis
ArrayyticklabelsNULLtick label for the leftmost y-axis; similar to xticklabels
Arrayyticklabels2NULLtick label for the rightmost y-axis; similar to xticklabels2
intyticktextTRUEsuppresses tick labels on the leftmost y-axis when zero
intyticktext2FALSEsuppresses tick labels on the rightmost y-axis when zero
In addition, histograms and stat plots support these additional plot description values:
Data Type Name Default Value Purpose
doublebargrouptospaceratio0.2the starting value for bar group width (or bar width when there are no groups) is determined to be the width of the plot area divided by the number of groups (or one) times the quantity one plus this number; eventually the bar group width (or bar width) is adjusted based on other factors such as maxbarwidthratio and subbarspaceratio
doublemaxbarwidthratio0.10constrains the maximum bar width to plot width ratio to be this value; a value of one or larger effectively disables this restriction
doubleplotpadratio0extends the data range of the y-axis by this factor; useful when the range is automatically calculated and you do not want the shortest bar in a histogram to completely disappear
doublesubbarspaceratio0.25sets the ratio of the space between bars in a bar group and the width of a bar; this number has no effect where there are no bar groups
The following table lists values that are computed during the generation of the plot. If values are supplied for any of these fields in the plot description dictionary, however, they are used as minimum values.
Data Type Name Default Value Purpose
doublefooterheight0height of footer text
doublelabelheight0height of the bottommost x-axis label text
doublelabelwidth0height of the leftmost y-axis label text
doublelabel2height0height of the topmost x-axis label text
doublelabel2width0height of the rightmost y-axis label text
doublelegendheight0height of legend text
doublelegendtextwidth0maximum width of legend text elements
doublesublabelheight0height of the bottommost x-axis sublabel text
doublesublabelwidth0height of the leftmost y-axis sublabel text
doublesublabel2height0height of the topmost x-axis sublabel text
doublesublabel2width0height of the rightmost y-axis sublabel text
doublesubtitleheight0height of subtitle text
doubletitleheight0height of title text
doublextickspacer0maximum width of the bottommost x-axis tick labels
doublextickspacer20maximum width of the topmost x-axis tick labels
doubleytickspacer0maximum width of the leftmost y-axis tick labels
doubleytickspacer20maximum width of the rightmost y-axis tick labels
The following table contains values that are generated during plot rendering. If values are supplied, they will be over-written or result in a typecheck error. The plotimage entry contains the generated plot image. In most cases, only the plotimage is of use to a Byzgraf user, though the other values are used by the useful ByzCheckPointInPlot and ByzMapPointToData functions.
Data Type Name Default Value Purpose
Arraypaths[0,...]not applicablean array of dictionaries containing rendered data element path and identification information; look at the source of ByzCheckPointInPlot in to see how it can be used
Imageplotimagenot applicablethe generated plot image; one way to display this image is to use it as the background image of a JPanel; look at the byzgraf_sampler.yx for an example of this technique
Pointtranslationnot applicabletranslation information for the plot area origin; look at the source of ByzMapPointToData in to see how it can be used

The Y Data Array

The Y data array, namely the ydata (or ydata2) element in the plot description dictionary, needs to follow certain specification rules depending on the plot type and the desired plot type variation. For each plot type, the specification rules are as follows:
  • BYZGRAF_LINETYPE

    • line plot with a single line - When only a single line is to be plotted, ydata should be an array of numeric values equal in length to xdata.
    • line plot with one or more lines - When one or more lines are to be plotted, ydata should be an array of arrays. Each sub-array will represent a plot line and each sub-array should contain numeric values equal in length to xdata.

  • BYZGRAF_HISTOGRAM

    • histogram with ungrouped, unstacked bars - When the histogram consists of ungrouped, unstacked bars, ydata should be an array of numeric values with one value for each bar and each value representing the height of that bar.
    • histogram with ungrouped, stacked bars - When the histogram consists of ungrouped, stacked bars, ydata should be an array of arrays. Each sub-array represents a stacked bar and each sub-array should contain numeric values representing the size of each stack element in the bar. The sum of the stack elements, namely the sum of the numeric values, will represent the height of the stacked bar.
    • histogram with grouped, unstacked bars - When the histogram consists of grouped, unstacked bars, ydata should be an array of arrays. Each sub-array should contain a single array. This redundancy is needed to distinguish this case for the ungrouped, stacked bar case. Each sub-array represents a bar group. Each sub-sub-array should contain numeric values with one value for each bar in the group and each value representing the height of that bar.
    • histogram with grouped, stacked bars - When the histogram consists of grouped, stacked bars, ydata should be an array of arrays. Each sub-array should contain a single array. Again, this redundancy is needed to distinguish this case from other cases. Each sub-sub-array should contain one or more arrays of numeric values. Each sub-array represents a bar group. Each innermost array of numeric values represents a stacked bar with the numeric values representing the size of each stack element in the bar. The sum of the stack elements, namely the sum of the numeric values, will represent the height of the stacked bar.

  • BYZGRAF_STATPLOT

    • stat plot with ungrouped stat elements - When the stat plot consists of ungrouped stat elements, ydata should be an array of arrays. Each sub-array represents a stat element and should contain five numeric values representing, in order, the minimum outlier, the minimum range, the average value, the maximum range and, finally, the maximum outlier.
    • stat plot with grouped stat elements - When the stat plot consists of grouped stat elements, ydata should be an array of arrays. Each sub-array represents a grouping of stat elements. Each sub-array should consist of one or more arrays containing five numeric values. Each array of numeric values represents a stat element. The five numeric values have the same meaning and ordering as for the ungrouped case.

Review the source of byzgraf_sampler.yx to see specific examples of ydata for each of these cases.

Additional Information

As always, contact us if you have questions.

 

Yoix is a registered trademark of AT&T Inc.