Graphite Feature Overview

This document enumerates the features we expect Graphite to support. This is an evolving document, and is likely to undergo revision as the design process proceeds. Feedback from potential users is encouraged (see Feedback Analysis for factors that went into this version of the requirements).

Input Formats

Graphite normally generates graphs from numeric sequences (lists, tuples, standard arrays, or Numeric arrays). For a simple line or scatter plot, one could supply a single list of numeric values as Y coordinates; the X coordinates will be automatically filled in as integers from 0 to the length of the sequence, and Z coordinates will default to zero. For something like an X/Y scatter plot, the X and Y coordinates would be given to Graphite as two sequences. To add error bars another sequence called yerr can be specified.

It is generally easy to extract a row of a multi-dimensional sequence (e.g., a tuple of tuples), but extracting a column is somewhat more work. Utility functions will be provided to simplify this sort of task, for cases where the data's "natural" format is a two-dimensional data table. Utility functions to set graph data directly from text or binary data files may also be provided.

In addition, one may provide a function rather than a sequence of numbers for any axis. This function will be sampled when the graph is generated; the sampling density will be adjustable.

A graph may have multiple data sets. Each may be graphed with a different format (see Plot Types below), or if not enough plot formats are given, the formats will be cycled through as needed.

Output Formats

Graphite graphs draw to a PIDDLE Canvas. PIDDLE provides an interactive drawing interface on several systems (MacOS, Windows, and systems which support Tk), and can also output to PDF, PostScript, and (via the Python Imaging Library) a variety of pixelmap formats such as GIF, JPEG, and PNG. While PIDDLE development is still ongoing, it looks likely to be stable and ready for use by the time Graphite is released (June 1999). By using PIDDLE as the interface to both screen graphics and output files, Graphite gains flexible output options at little cost.

Plot Types

Graphite uses an object-oriented design which allows new plot types (i.e. PlotFormats) to be added easily. As a result, it is expected that the types of plots available will continue to grow both before and after Graphite is released. At a mininum, we expect to include at least the following types:

Point Plot -- a combination of scatter and line plot; each point in the dataset is plotted with a certain symbol, and connected to its neighbor with lines. The line may be omitted to obtain a traditional scatter plot; the symbols may also be omitted if lines are drawn. Optional error bars are available on all three axes; these may be specified asymmetrically or symmetrically. Line style and symbol style are configurable. Points may also be individually labelled. Lines may optionally be given a fill style, used to fill below the line, and a Z-thickness used in 3D plots.
Bar Plot -- each point is represented as a bar; the Y value indicates the height of the bar, and the X and Z specify bar position. Bar style (color, hashing, width, etc.) are configurable. Graphs containing multiple bar plots combine their displays in one of several ways: by displaying bars side-by-side, by stacking, or by overlaying. Bars may be individually labelled at the top. Labels below the bars may be specified as tick mark labels, as with any other plot type. Possibly, one may also give a set of labels as the X coordinate data (but this notion is not fully worked out yet).
Polar Plot -- each Y value specifies the radius of the data point and each 'X' value specifies the angle.
Pie Plot -- each Y value specifies the angular extent of a slice of the pie; Z values, if given, are used to "explode" a slice out from the center. Each slice may be individually styled and labelled. The pie plot also has global attributes specifying its position and extent, making it easy to put several pies into one chart.
Density Plot -- requires three-dimensional data (e.g., Y as a function of X and Z). This plot is given a plane (defaulting to Z=0) on which to draw, and a palette function (several standard palettes will be provided); each point on the plane will be colored according to the corresponding Y value in the data. Additionally, isocontours can be located in the data and added to the plot.
Surface Plot -- similar to a Density plot, except that the surface drawn is extended into the third dimension rather than being confined to a plane. The surface is drawn with hidden line removal (unless the fill style is transparent), and with optional lighting. The user may also specify a color function to be applied to each point in the surface, e.g., color as a function of Y. One may also add either a mesh (periodic grid lines which follow the surface) to enhance perception of the surface, or contour lines. The camera position and projection time (perspective or orthographic) are adjustable -- true with any plot, but especially relevant to the Surface plot. We hope to also add support for surfaces defined by irregularly sampled points.
Image Plot -- also similar to a Density plot, but more efficient at displaying large matrices of color values.

Frame and Axis Options

The frame of a graph provides a coordinate system starting at (0,0,0) and going to (1,1,1). Items such as the graph title and axis are placed relative to this coordinate system. The frame may be drawn or hidden.

Each axis has a number of options, including multiple sets of tick marks (with or without labels), axis labels, and grid lines. Axes may be linear, logarithmic, or polar. A normal graph has only two (X,Y) or three (X,Y,Z) visible axes; however, one may also add secondary axes (X2, Y2, and Z2 as needed). This allows one to make a graph with one data set plotted against the left y axis, and another data set plotted against the right (Y2) axis.

Point Symbols

Symbols are defined as PIDDLE figures, which allows them to have arbitrary shape while maintaining high-quality output both on-screen and when printed. Graphite will include a stock set of common symbols, and the user may create more. Symbol size, fill color, outline color, and outline size are always adjustable.

In addition to the standard symbols, the user may choose Tukey-style box plot symbols, which represent additional descriptive statistics for each point.

Error Trapping

User-configurable attributes on Graphite objects are stored as extended Python attributes we call "properties." A property looks and acts just like an ordinary Python member variable, with two exceptions:

a property may have a restricted type and range of acceptable values; attempts to assign an invalid value raise an exception with a clear error message
every property has help; a user may get online help on a Graphite object or any of its properties with simple Python commands

In addition, most Graphite objects are protected such that casual attempts to add a new member variable raises an exception. Usually such attempts are mistakes, e.g., a user may try to assign to "line_color" when the correct spelling is "lineColor". Use of properties and protected objects allows such mistakes to be caught early, when the source of the problem is clear.

Graph Legend

A legend will be a special sort of drawing object that can draw a representation of each data series, with a corresponding name. Legend options will include position, outline style, background fill style, layout, and font settings.

Overlays and Combinations

Graphite includes drawing primitives such as lines, polygons, text, arrows, etc. These may be added to a graph in addition to all the primitives automatically generated by the plot format and data. All primitives are defined in three dimensions; for an ordinary two-dimensional plot, the third dimension defaults to zero and can be ignored. Clipping (restriction of drawing primitives to within the graph box) is handled by Graphite when the graph is drawn.

A Graph object may itself act like a drawing primitive. This allows one graph to be embedded as an overlay in another, or for a set of graphs to be combined into one figure.

Text Formatting

Any string used for labels, legends, etc. can include formatting specifiers, such as style changes, super/subscripts, etc. in a character-by-character manner. We will use of XML markup tags for this purpose. A small set of standard fonts (including Times, Symbol, and Monaco or Courier) will be supported.

Graph Stationery

Graph objects will be pickleable; that is, they may be saved to disk and later reloaded. A shortcut function will be provided to save a graph without its data, as a "stationery" file that defines the layout, style, and other preferences. This file may then be loaded as the template for a new graph. Several standard stationery files will be provided to implement common graph layouts.

Interactive Configuration

One possible feature we are considering takes advantage of the interactive capabilities of PIDDLE to allow editing of graph options graphically. The user would invoke a command to edit the graph (or part thereof) on an interactive canvas. A set of high-level options would appear, including a menu of subparts which can also be edited. The user could quickly navigate to such features as line style, which would be illustrated graphically and chosen with the mouse. Once done editing, the graph would be updated and could be saved as a template for future graphs.

http://Graphite.sourceforge.net/featureoverview.html
Last Updated: 1/10/00 . . . . . . mstrout@cs.ucsd.edu