Graphite Requirements

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.

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:

Frame and Axis Options

The frame of a graph is the box enclosing the graph, the graph title, and the axes. The box may be drawn or hidden; the title position and text style are configurable. 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, color, and fill 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: 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 font/style changes, super/subscripts, etc. in a character-by-character manner. We will use of TeX 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.
Last Updated: 4/25/99 . . . . . .