The Graph Display Class


The graph display class enables graphical representation of data in a variety of styles and formats, and interactive manipulation of that data. This class is a container class. A graph is represented by a global variable whose value is a scalar or vector of symbols. These symbols hold the names of other global variables, which are the children of the graph. Graph children have display class graphTrace. This class is automatically given to all children of a graph, and cannot otherwise be set.

The children of a graph are called graph trace sets. Each graph trace set can contribute one or more visible traces on a graph. The visible traces will simply be called traces. Some attributes are defined for graph trace sets, such as the colors of the traces, while others, such as the legend layout, are defined for the graph itself.

Some major features of a graph are shown in the first figure. Included are three traces, a title, subtitle, axes without rule lines, axis labels and x-axis sublabels, and a legend. The overall arrangement of a graph is fixed, but otherwise what appears in the figure can be set by means of the appropriate attributes.

There are various styles for the visible traces, including bar graph, pie chart, candlestick, and high-low, and a variety of ways users can interact with graphs, including zooming, annotating, and adjusting data points. The attributes available to a programmer for monitoring and controlling user interactions are described in this chapter, in the table "Attributes for Interactions with Graphs"; the user interactions themselves are described in the chapter "User Interactions with Displays", and in particular in "Graph Objects".

This chapter begins with a brief description of the organization of the data to be graphed and the attributes that apply directly to this data. Among these attributes is style, by which the appearance of the graph is specified. Descriptions of the major components of a graph and their associated attributes follow. The chapter concludes with sections on attributes associated with user interactions and miscellaneous attributes.

Trace Set Data

A graph trace set is either a numeric vector or a numeric matrix with at least two columns. The vector form, for a vector v, produces a single trace with x-coordinates #v and corresponding y-coordinates v or a pie chart with areas proportional to the elements of v. The matrix form produces one or more traces, with the first column containing the x-coordinates for all traces in the set. The remaining columns can represent one or more individual traces, such as lines or scatter charts, or one trace that requires more than one y-coordinate for its definition, such as a candlestick. A one-row, two-column matrix is used for a text trace, specifying the position of the lower left corner of the text. The text itself is specified as the title attribute of the trace set.

For performance reasons, when dates of the form yyyymmdd or mmdd appear in the data, they are considered as numbers, not parsed as dates, resulting in a distorted graph, unless the dates are all in the same month. If you convert the dates to Unix seconds, they will be properly distributed.

Trace Set Attributes

Trace set attributes are defined for trace sets, as opposed to the graphs themselves. They are nonpersistent: they disappear when a trace set is freed. They are all functional (see "Functional Attributes"). Each can be set to either a scalar value that applies to all traces, or a vector of values, one for each trace. A summary can be found in the table below. A detailed discussion of each attribute except barwidth follows the table.

Attributes Governing Appearance of Trace Sets in General
These attributes are all for graphTrace objects, except barwidth, which is an attribute of graph objects. See the
next table for the trace styles to which the colors, widths, and linestyle apply.
Attribute (all functional)Summary Description Data FormatDefault Value
barwidth The maximum width in pixels of the bars in a bar or stack graph. (Graph attribute.) numeric10
fillcolor Fill color for bar, pie, stack, area graphs; symbol color for scatter plots. string or symbol s.FILLCOLORS: one per trace set; if only one trace set, one per trace.
gradient If 1, color cycling is used for some styles. numeric0
legendText in the legend box that annotates the traces. string or symboldecorated trace set variable name
linecolor Line color for simple traces like scatter and line plots; component colors for compound traces like high-low and candlestick; outlines for bar, pie, etc. string or symbol s.LINECOLORS: one per trace set; if only one trace set, one per trace.
linestyle The basic styles are `solid, `dot, `dash, and `dotdash. symbol s.LINESTYLES: used for variation in each trace set when more than one set.
linewidth The line width in pixels for line style traces and pie outlines; for high-low style traces, the maximum display width. Not used for candlestick and various high-low graphs if it would cause individual figures to overlap. numeric1
See remark about overlap in description.
styleThe visual appearance of a trace. symbol`line
symbolThe symbol used in scatter plots. symbol`cross
symbolsize The size of the scatter plot symbol. numeric10
textfg The color a text trace appears in. symbol same as its titlefg
textfont The font a text trace appears in. character string same as its titlefont
xaxis If `x, the trace is plotted against an x-axis on the bottom; if `X, it is plotted against an x-axis on the top. symbol`x
yaxis If `y, the trace is plotted against a y-axis on the left; if `Y, it is plotted against a y-axis on the right. symbol`y

   fillcolor

The fillcolor attribute specifies the color used to fill the regions of a bar, pie, stack or area trace, and the color of the symbols of a scatter plot. The default fillcolor value is the value of the linecolor attribute; thus, in the absence of a fillcolor setting the bars appear as a solid rectangle. With a fillcolor different from that of linecolor, the bars appear with a border drawn in the linecolor value. The default behavior for fill coloring is described in the table above.

   gradient

If the gradient attribute has the value 1, then the colors of symbols in a scatter plot and bars in a bar graph are obtained by cycling through the colors listed in s.FILLCOLORS. If the attribute has been assigned a function, that function is called for every scatter point or bar.

   legend

The legend attribute controls the text that annotates the trace segments in the legend. The default is the name of global variable that contains the trace set. If the variable for a trace set is a matrix, then the name is supplemented by ":n", where n is 0, 1, ... . For example, if the global variable name is x, then the annotations are "x:0", "x:1", and so on.

   linecolor

The linecolor attribute specifies the color of the line segments in line, line-scatter, step, step-scatter, and segment traces, and the color of the borders of area, fill, pie, and stack traces. The default behavior of linecolor for these trace styles is described in the table above.

Up to four colors are meaningful for candlesticks and open-high-low-close graphs. In the case of a candlestick graph, the first color specifies the fill color of the candle when the open exceeds the close, the second is the color of the vertical lines segments, or wicks, the third is the candle border, and the fourth is the fill color of the candle when the close exceeds the open. When there is only one linecolor for a candlestick graph, it is used to fill the candle when the open exceeds the close, and the candles are hollow when the close exceeds the open. See the table "Attributes for Text Areas of Graphs".

For open-high-low-close traces, the first color specifies the color of the open ticks, the second is the color of the vertical line segments, the third is unused, and the fourth is the color of the close ticks. The default is to use the line color for all three colors. See the table just mentioned. If fewer than four colors are given they are used cyclically, in the manner of the primitive function Reshape. There are several cases for each of the styles high-low-close, high-low, and close, due to the fact that the data for these styles can have several different formats (i.e., number of columns). See the table "High-low Family; Data and Line Colors".

   linestyle

The basic linestyles are `solid, `dash, `dot, and `dotdash. In addition, `dot1 through `dot5 can be used for various intervals between dots, with `dot1 the smallest interval, `dot5 the largest, and `dot3 the same as `dot. Analogously, there are `dash1 through `dash5, where the dash length varies and `dash is between `dash2 and `dash3, and `dotdash1 through `dotdash5. When there is more than one trace set, the default assigns the basic styles in the order given above to the individual traces in each trace set. If there are more than four traces in a trace set, these styles are repeated as needed. When there is only one trace set, all the traces are `solid. This attribute applies to line, linescatter, and pie traces, as well as to trace sets with styles open-high-low-close, high-low-close, high-low, and close.

   linewidth

The linewidth attribute specifies (in pixels) the width of the line segments in line and linescatter traces, and the high-low style family of traces, and the outlines in pie charts. Line width is limited to 35, even if a higher value is set. Note: a significant performance penalty occurs on Sun Sparc workstations for line and linescatter traces with linewidths greater than 1 and more than 100 data points, due to system limitations. However, the various high-low style graphs look better with line segments wider than the default. See the figure "Various Line and Scatter Trace Styles", where all the graphs have line width 3.

Note: the linewidth setting for candlestick and the various high-low graphs is not used if it would cause the individual figures to overlap.

   symbol

The symbol attribute is used to specify the symbol used in a scatter plot. The values for the various symbols are:
`circle,    `circlefilled,    `cross,
`diamond,   `diamondfilled,
`square,    `squarefilled,    `star,
`triangle,  `trianglefilled,  `xsym.
If the value is any other symbol or a character vector, the text of that value is used for the symbol; the font in which a text symbol appears is specified by the font attribute of the trace set variable.

   symbolsize

The size, in pixels, of the symbol in a scatter plot.

   style

The style of the traces in a trace set, specified as one of the symbols in the table "Trace Styles, Data Format, and Attribute Applicability". See "Trace Styles".

   xaxis, yaxis

The xaxis attribute specifies whether a trace is plotted against the default x-axis at the bottom of the plot area or the alternate x-axis at the top; analogously, yaxis specifies whether the default y-axis on the left is used, or the alternate y-axis on the right. The alternate axes do not normally appear unless at least one trace is associated with them; see, however, the axis attribute.

   Trace Styles

The graph display class supports a variety of trace styles that are summarized in the following table. Included in this table is a cross reference indicating the applicability of the trace attributes discussed above. In addition to the table summary, a discussion and sample graphs of each style follow.

Trace Styles, Data Format, and Attribute Applicability
The attributes pertain to graphTrace objects. An x indicates that the column's attribute is meaningful for the row's trace style.
Trace StyleValue of style AttributeData Format fill-
color
line-
color
line-
style
line-
width
area`areavector, matrix xxxx
bar`barvector, matrix xx  
candlestick`candlen x 5 matrix  x morexx
close `c or `closevector, n x 2 - n x 5 matrix  x morexx
color profile`colorprofile vector, n x 2 - n x 5 matrix xx morexx
fill`fillvector, matrix xxxx
high-low`hlvector, n x 3 - n x 5 matrix  x morexx
high-low- close`hlc vector, n x 4 - n x 5 matrix  x morexx
line`linevector, matrix  xxx
linescatter`linescattervector, matrix xxxx
market profile `marketprofilevector, n x 2 - n x 5 matrix  x morexx
none` or `none any valid trace     
open-high- low-close`ohlc n x 5 matrix  x morexx
outline`outlinevector, matrix xxxx
pie chart`pie vector xxxx
scatter`scattervector, matrix xx  
segment`segmentvector, matrix  xxx
stack`stackvector, matrix xxxx
step`stepvector, matrix  xxx
stepscatter`stepscattervector, matrix xxxx
text`text1 x 2 matrix     

bar

The bar trace style displays trace data as a bar graph. The barwidth attribute (see the table "Miscellaneous Attributes for Graphs") specifies the maximum width for each bar. If a space limitation exists, the actual bar width is adjusted to fit within the available space. When there is a space limitation and the adjusted bar width is less than a threshold value, the border is dropped from the bar display and only the fill color appears.

The fillcolor and linecolor attributes are used to set the colors inside the bars, and the bar border colors, respectively. The linestyle and linewidth attributes have no effect on bar graphs.

The second figure shows a series of graphs with an increasing number of bar style traces in each successive graph. These graphs illustrate both the positioning of the bars on the x-axis relative to the x-value, and the effects of space limitation on the bar width. With each additional bar, the bar width is adjusted to fit within the available space while maintaining the same relative spacing. Notice that the borders around the bars eventually disappear.

A Series of One to Six Bar Traces

line

The line trace style is the default trace style and consists of line segments connecting consecutive data points. See the figure immediately below.

Various Line and Scatter Trace Styles

scatter

The scatter trace style uses a symbol (the default is a cross) to indicate the location of each data point in a trace. To produce scatter plots with small dots, set the trace symbol to `circlefilled and the `symbolsize to 3 (a smaller size will not be shown). See "fillcolor" for a discussion of fill colors and this trace style. See the previous figure.

linescatter

The linescatter trace style is a combination of the line and scatter style traces; the trace is an ordinary line graph, but in addition scatter symbols mark each data point. See the previous figure.

step and stepscatter

The step trace style is a variation of the line style that replaces each line segment with a step consisting of a horizontal and a vertical segment. The stepscatter trace style is the analogous variation of the linescatter style. See the previous figure.

segment

The segment trace style is a variation of the line style that permits a series of disconnected line segments to be specified in one trace. The line segments are every other one of those in a line graph. See the previous figure.

candle, ohlc, hlc, hl, c, marketprofile, colorprofile

The high-low family of trace styles can accept data in a variety of formats, which are summarized in the table "High-low Family; Data and Line Colors". With these flexible trace formats, it is possible to display any of the following graph styles without changing the underlying data: open-high-low-close, candlestick, high-low-close, high-low, close, market profile, and color profile. All these styles can be assigned to five-column trace sets.

Analogously, the following subset can be assigned to four-column trace sets: high-low-close, high-low, and close; to three-column trace sets: high-low and close; to two-column and vector trace sets: close, market profile, and color profile.

For these traces the linewidth attribute specifies the maximum width of line segments, if sufficient space is available. See the following figure.

Various Trace Styles Based on the Same Data

High-low Family; Data and Line Colors
Keys:   x: x coordinate; u: unused; v: vertical line segment color; c: close tick color; t: trace color.
Trace StyleTrace Set Data Column Indexlinecolor Index
01234 0123
ohlc, candlen x 5 matrix xopenhighlowclose See "linecolor"
hlcn x 5 matrix xopenhighlowclose uvuc
n x 4 matrix xhighlowclose  vuc 
hln x 5 matrix xopenhighlowclose uvuu
n x 4 matrix xhighlowclose  vuu 
n x 3 matrix xhighlow   vu  
color profile, close, market profilen x 5 matrix xopenhighlowclose uuut
n x 4 matrix xhighlowclose  uut 
n x 3 matrix xhighlow   ut  
n x 2 matrix xclose    t   
vector close     t   

text

Text traces are positioned on a graph by specifying the coordinates of the lower left corner of the bounding box of the text. The trace set for a text trace is a 1 by 2 matrix holding these coordinates as an (x, y) pair. The text that appears on the graph is the value of the title attribute of the trace set variable; the trace's titlefg attribute applies to the text unless its textfg attribute has been set, and likewise for titlefont and textfont.  The text "All Six Traces" on the lower right graph of the bar trace figure is a text trace.

Text traces do not appear in the graph legend and are superimposed on top of the other traces.

none

A trace on a graph can be hidden from view by setting its style attribute to `none or to the empty symbol (` ), and restored by resetting this attribute to any other appropriate value.

area

All traces with this style are accumulated in one visible trace. If there is only one trace with this style, its graph is the filled-in region bordered by the x axis and the line graph which this trace would form if its style were line. The lower region in the lower right graph in the figure "Various Stack and Area Graphs" is such a graph. If there is more than one trace with this style, the graph is a set of filled-in regions, stacked one above the other. See the filled-in regions in the upper right graph of the figure just mentioned, and compare that graph to the one on the lower left; they differ only in that both traces with style stack in the lower left have style area in the upper right.

fill

If a trace of this style is drawn as a line trace and the first and last points are connected, the result is the border of a closed region. If the style is fill that region is filled-in with the fillcolor. See the lower right graph in the stack and area figure, where the top region has style fill, the bottom region has style area, and their trace sets are equal.

stack

All traces with this style are accumulated in one visible trace, which appears to be a set of bar graphs, stacked one above the other. In fact, those individual bar graphs can be seen by setting the style of all traces with style stack to style bar. See the lower left graph in the stack figure, and compare it to the upper left.

Various Stack and Area Graphs

pie

Only y values are significant for pie charts, which are not graphed against a coordinate. Hence there are no x values, and only a vector is used for a `pie trace. In the absence of other traces in the graph, you might want to set the `axis attribute to `none, as has been done in the pie-chart figure. The attributes specifically for pie charts are shown in the following table.

     p1.2 2.3 3.4 4.5                Set points for the graph
     g`p                             Set up graph

     `g is `graph                     Establish class
     `p has (`style;`pie)             Establish style
     `g has (`axis;`none;             Turn off x-y axis display
             `xs;602;`ys;496;         Set size of window (x-size and y-size, in pixels)
             `pieoffsetmargin;0.35)   Set minimum space between text and edges of pie

     `p has (`pievaluealign;`bottom;
             `piepercentalign;`bottom)
     `p has (`linecolor;`black;`textfg;`black)                 Set colors for pie borders and text
     `p has (`pieoffsets;  0      0            0.15 0;         Pull out one slice
             `fillcolor;   `green `deepskyblue `red `yellow;   Slice colors
             `pieprofiles; 0.75   0.5          1    1)         Slice thicknesses

     show `g

A Pie Chart

Other Attributes Governing Appearance of pie Trace Sets
All attributes are for graphTrace except pieoffsetmargin, which is for graph.
AttributeDescriptionData FormatDefault Value
pieangle If pieprimaryslicealign is `none, pieangle gives the orientation of the primary slice of a pie chart in counterclockwise degrees from the three o'clock position. integer scalar0
pieaspectratio The extent to which a pie chart is tilted towards the viewer, ranging from 0.0 to 1.0. 1.0 is a top view, or flat pie. numeric scalar0.6
piedepthfactor The maximum height of the pie in a pie chart, as a fraction of the standard depth factor. Cf. pieprofiles. numeric scalar1.0
pielegendalign Where the legend for each slice of a pie chart is placed. Values are null, `none, `inside, `outside, `left, `right, `top, `center, and `bottom. The last five control placement with regard to values and percentages and will be ignored if not consistent with the values of pievaluealign and piepercentalign. Several values may be concatenated, as in `inside`top`left. The color and font are controlled by the trace's titlefg and titlefont attributes. scalar or vector `sym`center
pieoffsetmargin This attribute is for graph, not graphTrace. The margin around pie charts, as a fraction of the available space. The value ranges between 0 (inclusive) and 1 (exclusive). 0 makes pie charts as large as possible in the graph. 0.99 makes them dots. Values close to 1 cause calculation overflows, which appear as A+ domain errors. numeric scalarapprox. 0.3
pieoffsets The extent to which each slice is separated (pulled out) from the center of a pie chart. Values between 0.0 and 1.0 (inclusive) are treated as fractions of the pie's radius. Values greater than 1.0 and equal to or less than 100.0 are treated as percentages of the pie's radius. The value or values given are used cyclically for the slices. numeric scalar or vector0
piepercentalign Where to place the display of the percentage that each slice is of a pie. Values are null, `none, `inside, `outside, `left, `right, `top, `center, and `bottom. The last five control placement with regard to values and legends and will be ignored if not consistent with the values of pievaluealign and pielegendalign. Several values may be concatenated, as in `inside`top`left. The color and font are controlled by the trace's titlefg and titlefont attributes. scalar or vector `symNull
pieprimaryslice The trace index of the slice to be considered the "primary" slice of a pie chart, the slice whose display is controlled by pieprimaryslicealign or pieangle. The value -1 means that the largest slice will be considered the primary slice. For a brief time, it was called primaryslice. integer scalar-1
pieprimaryslicealign Where to place the primary slice of a pie chart (by rotating the pie). The possible values are null, `none (see pieangle), `left, `right, `top, `bottom. For a brief time, it was called primaryslicealign. scalar `sym Null (`top)
pieprofiles The height of each slice of a pie, as compared to the maximum height of the pie. Values between 0.0 and 1.0 (inclusive) are treated as fractions of the pie's maximum height. Values greater than 1.0 and equal to or less than 100.0 are treated as percentages of the pie's maximum height. The value or values given are used cyclically for the slices. numeric scalar or vector1.0
pievaluealign Where to place the display of the value of each slice of a pie chart. Values are null, `none, `inside, `outside, `left, `right, `top, `center, and `bottom. The last five control placement with regard to percentages and legends and will be ignored if not consistent with the values of piepercentalign and pielegendalign. Several values may be concatenated, as in `inside`top`left. The format of the value display is controlled by the out attribute, and the color and font are controlled by the trace's titlefg and titlefont attributes. scalar or vector `symNull
primaryslice Called this for a brief time, but now called pieprimaryslice.   
primaryslicealign Called this for a brief time, but now called pieprimaryslicealign.   

 

The Order in Which Traces Are Drawn

The basic order in which traces are drawn is the index order of the graph trace variables in the graph variable, and within each graph trace variable, the index order of the columns. (This order may be changed without freeing the trace variables.) The traces appear in the legend in this order, starting at the top in vertical legends. When multiple bar graphs have common x-coordinates, they are drawn from left to right in this order, clustered near that common value. Stack and area graphs are drawn from top to bottom in this order. All area and fill traces are drawn in this order before traces of any other style are drawn; all bar and stack graphs are then drawn in this order; all remaining traces other than text traces are then drawn in this order; finally, all text traces are drawn in this order. Trace search order is the same as the order in which traces are drawn.
 

The Text Areas of a Graph

The text areas of a graph are its title, subtitle, footnote, and axis titles. The title and subtitle areas are illustrated in the first figure. The title appears at the top of the graph. The subtitle appears below the title, and the footnote appears below the x-axis at the bottom of the graph. Any of the three can have one or more lines, their text can be justified, and their color and font can be specified.

The x-axis title appears under the x-axis labels and sublabels; the y-axis title appears at the top of the y axis. See the table "Axis Attributes for Graphs".

Attributes for Text Areas of Graphs
These are all attributes of graph objects
AttributeDescriptionData FormatDefault Value
footnoteThe text of the footnote on the graph. string, symbol; a nested vector of strings or symbols is accepted for multiline text.null string
footnotefgThe color of the footnote text.string, symbol `axiscolor (inherits the axis color until the footnotefg attribute is set to a different color)
footnotefont The font of the footnote text. stringlucidasans typewriter-12
footnotejustify `center, `left, or `right justify the text. symbol`center
subtitleThe text of the subtitle of the graph. string, symbol; a nested vector of strings or symbols is accepted for multiline text.null string
subtitlefgThe color of the subtitle text.string, symbol `axiscolor (inherits the axis color until the subtitlefg attribute is set to a different color)
subtitlefont The font of the subtitle text. stringlucidasans typewriter-12
subtitlejustify `center, `left, or `right justify the text. symbol`center
title The text of the title of the graph; trace set titles are meaningful for text traces only. string, symbol; a nested vector of strings or symbols is accepted for multiline text. variable name
titlefg The color of the title text. (The trace's titlefg governs the color of text traces and of each pie trace slice's legend, value, and percent text.) string, symbolblack
titlefont The font of the title text. (The trace's titlefont governs the font of text traces and of each pie trace slice's legend, value, and percent text.) stringkaplgallant
titlejustify `center, `left, or `right justify the text. symbol`center

   The Legend of a Graph

The legend appears automatically on a graph. Its default arrangement is vertical, but it can be also be aligned horizontally; see the legendstyle attribute in the table "Legend Attributes for Graphs", and see the bar trace figure for examples. The text that annotates each trace sample is specified using the trace set attribute named legend. The position, or justification, of the legend is specified using the graph attribute named legend. This position can be within the plot area, i.e., the area within the axes, or it can also be outside the plot area. The legend can be removed by setting the graph legend attribute to `none.

Legend Attributes for Graphs
These are all attributes of graph objects
AttributeDescriptionData FormatDefault Value
legend Position of the legend in the plot area or outside it. Values are:

`bc, `bl, `br, `tc, `tl, `tr`none (removes the legend).


Inside: `bottom, `center, `left, `horizontal, `inside (centered both ways), `right, `top, `vertical;
      Outside: `outside, `outsidehorizontal, `outsidevertical.
(xlegend and ylegend, if set, always take precedence over legend, but setting legend clears - unsets - them.)

symbolvector
`left `top `inside
legendbg The background color of the legend. symbol or stringgray
legendfg The foreground color of the legend. symbol or stringblack
legendfont The font of the text in the legend. The legend symbol size depends upon the font size. stringlucidasans typewriter-10
legendhlthickness The thickness of the legend highlight area, in pixels. numeric1
legend shadowthickness The thickness of the legend shadow area, in pixels. numeric1
legendstyle The style of the legend: vertical (`ver), horizontal (`hor), horizontal with the last trace values (`lastvalue), or not at all (`none) (see the bar trace figure).
The last values are those associated with the element or row with the largest index for each trace set.
symbol`ver
xlegend,
ylegend
The x, y coordinates of the upper left corner of the legend when the legend attribute of the graph is set and has not been cleared by a later setting of legend. numeric0, 0

 

The Axes of a Graph

The axes of a graph have the most attributes of the various components. For convenience, the descriptions appear in three tables, one for axes in general ("Axis Attributes for Graphs") and the other two for tick marks and tick labels specifically ("Axis Label and Tick Mark Attributes for Graphs", and "Attributes That Assist in Specifying Tick Marks and Labels"). Many of the axis-related attributes have more than one version, corresponding to more than one axis; the convention for their names is presented next.

   Default and Alternate Axes

Graphs have a default set of axes, with the x axis bordering the bottom of the plot area and the y axis bordering on the left. In addition, an alternate x axis can be drawn on top of the plot area, and an alternate y axis on the right. These alternate axes are referred to as the X axis and Y axis, as opposed to the default x axis and y axis.

These additional axes can be used purely for appearance, either supplementing or replacing the default axes, or they can be used to plot traces with different scales on the same graph (see the trace attributes xaxis and yaxis).

These axes have independent attributes, such as color, and the names of the attributes are prefixed with "x" to indicate the default x axis, "X" the alternate x axis, i.e., the X axis, "y", and "Y". For example, in the case of foreground color, the four attributes are xfg, Xfg, yfg, and Yfg. To save space in the tables, the four attributes may appear in shorthand notation, like x/X/y/Yfg for the four color attributes.

   The axis, grid, and rule Attributes

These attributes determine the appearance of the axes and grid lines.

The standard axis style is specified by the value `std for the axis attribute; see the bar trace figure. The value `std for the axis attribute has the property that when any of the xaxis or yaxis attributes of any trace is set to an alternate axis, that axis automatically appears. The boxed style, specified by the value `box, additionally has a box around the plot area. Axes are removed by setting the axis attribute to `none. Any combination of default and alternate axes can be used by setting the axis attribute to a symbol value containing the appropriate letters x, X, y, and Y (in any order).

The rules on the axes, which are the straight lines that run lengthwise, can be specified separately. For example, the boxed style can be obtained by setting the axis attribute to `xy and the rule attribute to `xXyY. When the rule attribute is set to `axis, its value is effectively the same as that of the axis attribute.

In addition, grid lines can be drawn at the major tick marks on axes by setting the grid attribute.

   The xlabel, Xlabel, ylabel, and Ylabel Attributes

These attributes provide complete control over the placement of tick marks, the text of their labels, their lengths, and the widths of their associated grid lines. A complete specification for any of them is a nested vector of length four, of the form (ticks;labels;sizes;widths), where:

Warning! The first component, ticks, is positional, as you would expect. The other three components, however, are actually interpreted by type, a `char or nested character item being used for labels, a `float item being used for sizes, and an `int item being used for widths! Their order does not matter! In fact, if two or more of them have the same type, then the last is used and the rest (of the same type) are quietly ignored!

Only the ticks are required, and if they alone are specified the ticks vector does not need to be nested. For any of the other three components, if the number of its elements exceeds the number of ticks, the extra elements are ignored. For sizes and widths, if there are fewer elements than ticks, the elements are used cyclically, in the manner of the A+ Reshape primitive function.

The label attributes are functional, giving a way to set the tick marks and their associated values under a variety of dynamic situations, such as scrolling. There are several attributes whose values can be queried but not set which give information that helps in laying out the tick marks and labels; see the table "Attributes That Assist in Specifying Tick Marks and Labels".

Examples of Correct `xlabel Specifications

(`xlabel;)    Set all to defaults. Labels: values; ticksizes: full (1.); no gridlines.
(`xlabel; 2 3 4)                 Ticks at 2 3 4. Defaults for others.
(`xlabel;(2 3 4; 3 2"abcdef"))  Ticks, labels. Defaults for others.
(`xlabel;(2 3 4; .4 .6 .4))      Ticks and ticksizes.
(`xlabel;(2 3 4; 1 2 1))         Ticks and linewidths.
(`xlabel;(2 3 4; 1 2))           Same effect as preceding.
(`xlabel;(2 3 4; .5; 2))         Ticks, ticksizes, linewidths.
(`xlabel;(2 3 4; 3 2"abcdef"; 1))   Ticks, labels, linewidths.
(`xlabel;(2 3 4;("ab";"cd";"ef"); .7; 1))  All.

   Zero axes

Zero axes can also appear in a graph. For which axes they are shown, their style, their color, and their thickness are governed by the attributes zero, zerostyle, zerofg, and zerowidth. The table "Axis Attributes for Graphs" gives their ranges of values and their defaults.

Axis Attributes for Graphs
These are all attributes of graph objects
AttributeDescriptionData FormatDefault Value
axis `std, `box, `none, or a symbol containing one or more of x, y, X, Y (see "The axis, grid, and rule Attributes")symbol`std
grid `none, or a symbol containing one or more of x, y, X, Y that does not contain both x and X, or y and Y (see "The axis, grid, and rule Attributes").
Grid lines can occur only at major tick marks, and only at all of them. To have irregularly spaced grid lines, instead of using the grid attribute specify traces that each have two points with the same x value and minimum and maximum y values and attributes such as (`legend;`; `linestyle;`dash; `linecolor;`black). These "grid" traces can be dependencies whose values depend upon those of the true traces.
symbol`none
gridfgThe color of the grid lines. string or symbolblack
gridstyle The style of the grid lines; one of `solid, `dash, `dotdash, `dot. symbol`dash
gridwidthThe line width of the grid lines.numeric 0 (very thin; like 1 for display, but finer for printing)
rule `std, `box, `none, `rule, or a symbol containing one or more of x, y, X, Y (see "The axis, grid, and rule Attributes"). symbol`std
rulewidthThe line width of axis rules and tick marks.numeric 0 (very thin; like 1 for display, but finer for printing)
xfg, Xfg,
yfg, Yfg
The color of the indicated axis, axis labels, and tick marks. string or symbolblack
x/X/y/Ymin,
x/X/y/Ymax
The minimum and maximum values of the indicated axes. For these attributes to be effective, min must be less than max (if both are set); otherwise, the minimum and maximum values of the indicated axes are derived from the trace data. Use values in the same domain as the data to which the pair applies, e.g., dates in the same form.
See
xmax in the table listing all attributes.
numeric Computed values used.
xtitle, Xtitle,
ytitle, Ytitle
The text of the indicated axis title.stringnull string
x/X/y/Ytitlefg The color of the text in the indicated axis title. stringblack
x/X/y/Ytitlefont The font in which the text of the indicated axis title is set. stringlucidasans typewriter-12
x/X/y/Ytitlejustify `left, `center, `right for horizontal titles; `top, `center, `bottom for vertical titles. string`center
ymode Controls which way the values run on the y-axis and Y-axis: `ascend or `descend. numeric`ascend
ytitlestyle, Ytitlestyle The y-axis and alternate y-axis titles can each appear above the axes (`hor) or stacked vertically alongside (`ver). In both cases the titles are outside the plot area of the graph. symbol`hor
zero Which zero axes appear: `none, `x, `X, `y, `Y, `xy, `xY, `Xy, or `XY. symbol`xy
zerofgControls the color of the zero axes. string or symbolslategray
zerostyle The style of the zero axes: `dot1 through `dot5, `dotdash1 through `dotdash5, `dash1 through `dash5, or `solid.symbol`dot1
zerowidthControls the width of the zero axes (0 - 10).numeric 0 (very thin; like 1 for display, but finer for printing)

Axis Label and Tick Mark Attributes for Graphs
These are all attributes of graph objects
AttributeDescriptionData FormatDefault Value
x/X/y/Yinc The increment in axis coordinates between adjacent major tick marks on the indicated axis. When it is set to nothing, (`xlabelout;), A+ determines this value based on trace data and axis label size. numeric0
xlabel, Xlabel,
ylabel, Ylabel (functional)
The tick mark locations, and any of the following: the text of the labels, the lengths of the tick marks as fractions of the majorticksize setting, and the widths (in pixels) of the grid lines. For details see "The xlabel, Xlabel, ylabel, and Ylabel Attributes". numeric or nested vector 
xsublabel, Xsublabel (functional) Sublabels provide a second row of axis labels below the label row. The interpretation of these attributes is the same as for label attributes (see above in this table).
x/X/y/YlabelfontThe font in which the labels on the indicated axis are set. symbol, stringlucidasans typewriter-12
x/Xlabeljustify,
x/Xsublabeljustify
Justify the labels or sublabels of the indicated axis: `left, `center, `right. symbol`center
y/Ylabeljustify Justify the labels of the indicated axis: `bottom, `center, `top.
x/X/y/Ylabelout,
x/Xsublabelout (functional)
Specification of tick label and sublabel formatting, in the same way that data formats are specified for the screen with the out attribute. Furthermore, set to ` or `none to remove the labels. If x/Xsublabelout is given a value when no sublabels are present, they appear automatically. symbol, function, or character string 
x/X/y/Ymajorticksize The size of the major ticks on the indicated axis, in pixels. numeric10
x/X/y/Yminorticks The number of minor tick marks that appear between consecutive major tick marks on the indicated axis. numeric1, 1
x/X/y/Yminorticksize The size of the minor ticks on the indicated axis, in pixels. numeric6
x/X/y/Ytickstyle The tick style for the indicated axis: if `out or `in, the tick marks point out of or into the plot area; if `inout, the tick marks straddle the axis. symbol`out

Attributes That Assist in Specifying Tick Marks and Labels
These are all attributes of graph objects
AttributeDescription
x/X/y/Yextent A three-element vector v giving the minimum value for the indicated axis (v[0]), the maximum value (v[1]), and a scale factor (v[2]) such that (v[1]-v[0])v[2] is the length of the axis in pixels.
x/X/y/Ylabelheight The height, in pixels, of any label on the indicated axis, based on the current font.
x/X/y/Ylabelwidth The width, in pixels, of a specified label for the indicated axis. The text of the label is given as a character vector, as for example:
(`xlabelwidth;'label text') of `g
where `g is the graph. A vector of character vectors or a character matrix can also be given for the text, and a vector of pixel lengths is returned. In the case of a matrix, the rows are taken as the labels.

 

Interactions with Graphs

There are a variety of interactions with graphs to customize the display, edit and manipulate trace data, perform detailed examination of traces, and navigate through graphs that are only partially displayed. These interactions are described in "User Interactions with Displays", and particularly in "Graph Objects". The following attributes provide the means for programmers to monitor user interactions and control the responses:

Attributes for Interactions with Graphs
AttributeDescription
addtexttrace Like addtrace, but applies to text traces. See "Example" regarding automatic creation of variable names.
addtrace An attribute with callback (see "Attributes with Callbacks"). If it is set to a value, which must be a function or a (function; static_data) pair, that function is called whenever a numeric trace is created interactively; the value of the coordinate attribute is the trace set of the created trace. The default behavior is to create a global variable containing the trace set and to append the name of this trace-set object (in symbol form) to the graph object; the new trace set is a two-column matrix and its style is `line. See "Example" regarding automatic creation of variable names.
coordinate This is a reference-only attribute whose value is the two-element vector (x-axis coordinate, y-axis coordinate) of the pointer position in the case of a refer event on a graph, or the entire trace in the cases of a refer event on a trace and an interactive creation of a new trace.
Coordinate Like coordinate, but the value is the alternate axis coordinates of the pointer position in the case of a refer event on a graph.
copytexttrace Like addtexttrace, but applies when text traces are copied interactively. See "Example" regarding automatic creation of variable names.
copytrace Like addtrace, but applies when a numeric trace is copied interactively. A numeric trace to be copied interactively must be selectable; see the selectable and refer attributes. See "Example" regarding automatic creation of variable names.
delete Like addtrace, but applies when a trace is deleted interactively. The default value of this attribute is 0, and with this value traces cannot be deleted interactively. If it is 1, traces can be deleted interactively, and the variable of the deleted trace is automatically removed from the graph object. Only text traces and selectable numeric traces can be deleted interactively; see the selectable attribute.
mode Set up interactive entry (`addtrace) or text entry (`addtexttrace) at `coordinate, or terminate entry, like Enter or double click (`normal).
movelimit Restrains the movement of a data point being modified interactively; one of `x (the default), `y, and `none.
refer A refer event occurs on the graph object when the left button is clicked with the pointer anywhere on the graph object except on a data point of a numeric trace. A refer event on a selectable trace occurs when the pointer is on the trace and the left button is double-clicked; see the selectable and coordinate attributes, and "Attributes with Callbacks".
referpoint A referpoint event occurs when the pointer is on any data point of any numeric trace and the left button is clicked; see the selected attribute, and "Attributes with Callbacks".
selectable Effective with two-column line traces only; that is, only two-column line traces are selectable. If the value is 1, the trace can be selected, i.e., the user can interactively manipulate the trace. The default value is 0.
selected The value is the two element vector of row, column indices of the selected data point when a referpoint event occurs.
textactivate A textactivate event occurs a text trace is interactively modified. The default action is to replace the value of the title attribute of the text trace with the new text. Note that there is no counterpart for the interactive modification of a numeric trace, but that action can be monitored with a callback function.
x/X/y/Yextent These attributes can be used to detect zooming, since each one contains the least and greatest values currently shown on its axis, as well as a scale factor.
x/X/y/Ymin, x/X/y/Ymax Resetting these attributes, even to all zeros, is a way of undoing in a program any zooming a user has done on the screen, in order, for example, to ensure that a new point is shown promptly.

Data points can be moved interactively (see "Data-Point Move"). Their movement can be restrained to vertical only, so that x coordinates don't change, by setting the movelimit attribute to `x, or to horizontal only by setting it to `y. There are no restraints when it is set to `none.
 

Miscellaneous Graph Attributes

Miscellaneous Attributes for Graphs
These are all attributes of graph objects.
AttributeDescriptionData FormatDefault Value
barwidth The maximum width in pixels of bars in bar and stack graphs. numeric10
bgThe background color of the graph. string or symbolgray
bottom,
top,
left,
right
The margin width or height of the area consisting of the plot area (the region within the four axis rules, even when some of the rules are absent), axes and labels, and axis titles, as a percentage of the default width or height of that area (a whole number or a fraction, e.g., 20 or 0.20, but only a whole number if in excess of 100%). numeric0
debug If 1, the A+ processor displays a message every time a graph is redrawn, updated (i.e., the last point on a trace is changed), or printed. integer0
fg The color of the axes, axis labels, legend titles and the legend border, subtitle, and footnote when their colors have not been explicitly specified. string or symbolblack
selectdistance The distance in pixels from which a trace data point is selectable for interactive manipulation of its value. numeric10
shadowthickness The width in pixels of the shadow area (the border) around the graph. Set to 0 for no border. numeric2
xleft,
xright,
Xleft,
Xright,
ytop,
ybottom,
Ytop,
Ybottom
xleft is the left margin of the xy trace area and xY trace area as a percentage of the axis range (a whole number or a fraction, e.g., 20 or 0.20, but only a whole number if in excess of 100%). Analogously, Ytop is the top margin of the xY and XY trace areas, and all the others are similar.
The xy trace area is the region holding traces plotted against the x and y axes. By default it coincides with the plot area. There is also an xY trace area holding traces plotted against the x and alternate y axis, as well as Xy and XY trace areas.
numeric0
xs,
ys,
extent
xs, ys: the dimensions of the graph in pixels.
extent: the vector x, y, xs, ys, where x and y are the graph's coordinates in pixels relative to its parent, or to the screen if it is top-level.
numericxs and ys: 200. extent: 0 0 200 200

 

Lists of All Graph and GraphTrace Attributes

The keys in the "Table of All Display Attributes" in the "Display Attributes" chapter that pertain to the graph display class are G, ALL, CNFT, NFT, and TOP.

The attributes that are meaningful for the graph display class (other than the print... attributes) are:

active
addtexttrace
addtrace
ancestors
arrowdown
arrowkeys
arrowleft
arrowlist
arrowright
arrowup
at
atsector
axis
b
barwidth
bg
bottom
bound
children
class
clear
coordinate
Coordinate
copytexttrace
copytrace
deiconized
delete
descendents
doc
downto
dynamic
eval
evaluate
exit
extent
f1-f12
familytree
fg
fkeys
focus
followers
followertree
font
foot
footnote
footnotefont
footnotejustify
freeze
fullscreen
grid
gridfg
gridstyle
gridwidth
h
H
has
head
hide
hl
hlthickness
icon
iconic
iconized
icontitle
incurrentworkspace
is
l
leader
left
leftto
legend
legendbg
legendfg
legendfont
legendhlthickness
legendshadowthickness
legendstyle
literal
lower
mapped
mode
naturalsize
newshow
notify
outofcurrentworkspace
parent
pieoffsetmargin
pin
preset
primary
r
raise
realize
recursively
refer
refresh
reparent
request
reshow
resize
resizeable
right
rightto
rule
rulewidth
script
selectdistance
selected
sensitive
set
settings
shadowthickness
shell
shelltitle
show
state
stateself
subtitle
subtitlefg
subtitlefont
subtitlejustify
syncshow
t
tabfrom
tablist
tabto
title
titlefg
titlefont
titlejustify
top
upto
vcol
vcols
verify
vrow
vrows
w
W
ws
x
X
xextent
xfg
xinc
xlabel
xlabelfont
xlabelheight
xlabeljustify
xlabelout
xlabelwidth
xleft
xlegend
xmajorticksize
xmax
xmin
xminorticks
xminorticksize
xright
xs
xsublabel
xsublabeljustify
xsublabelout
xtickstyle
xtitle
xtitlefg
xtitlefont
xtitlejustify
y
Y
ybottom
ylegend
ymode
ys
ytitlestyle
ytop
yx
YX
yxs
zero
zerofg
zerostyle
zerowidth
The keys in the "Table of All Display Attributes" that pertain to the graphTrace display class are gT and ALL.

The attributes that are meaningful for the graphTrace display class are:

active
ancestors
bg
bound
class
coordinate
doc
f1-f12
eval
evaluate
fillcolor
fkeys
gradient
has
is
legend
linecolor
linestyle
linewidth
movelimit
parent
pieangle
pieaspectratio
piedepthfactor
pielegendalign
pieoffsets
piepercentalign
pieprimaryslice
pieprimaryslicealign
pieprofiles
pievaluealign
preset
protect
protected
refer
referpoint
script
selectable
selected
set
settings
shell
state
stateself
style
symbol
symbolsize
textactivate
textfg
textfont
title
titlefg
titlefont
titlejustify
verify
xaxis
yaxis
(Point the mouse cursor to an attribute to display a short description at the bottom of the screen)


doc@aplusdev.org© Copyright 1995–2008 Morgan Stanley Dean Witter & Co. All rights reserved.