Yoix / Byzgraf, a Set of Yoix Business Graphics Functions

Figure 1. A Sample Line Plot

Figure 2. A Sample Histogram

Figure 3. A Sample Stat Plot

Summary

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

• Line plot
• Histogram
• Stat plot

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

• 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.

The Plot Description Dictionary

The Y Data Array

• 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