Graph Tutorial
1. Introduction
2. The Components of a Graph
Attributes: xs
ys
2a. Traces and Trace Sets
Attributes: linecolor (*)
linestyle (*)
linewidth (*)
2b. Title
Attributes: title
titlefg
titlefont
titlejustify
2c. Subtitle
Attributes: subtitle
subtitlefg
subtitlefont
subtitlejustify
2d. Footnote
Attributes: footnote
footnotefg
footnotefont
footnotejustify
2e. Legend
Attributes: legend
legend (*)
legendbg
legendfg
legendfont
legendstyle
xlegend
ylegend
legendhlthickness
legendshadowthickness
2f. x-Axis and y-Axis Titles
Attributes: x/X/y/Ytitle (**)
x/X/y/Ytitlefg (**)
x/X/y/Ytitlefont (**)
x/X/y/Ytitlejustify (**)
y/Ytitlestyle (**)
2g. Axes
Attributes: axis
x/X/y/Yfg (**)
grid
gridfg
gridstyle
gridwidth
rule
rulewidth
y/Ymode (**)
2g1. Axis Ticks
Attributes: x/X/y/Yinc (**)
x/X/y/Ymajorticksize (**)
x/X/y/Yminorticks (**)
x/X/y/Yminorticksize (**)
x/X/y/Ytickstyle (**)
2g2. Axis Labels
Attributes: x/X/y/Ylabelfont (**)
x/X/y/Ylabeljustify (**)
x/X/y/Ylabelout (**)
x/Xsublabel (**)
x/Xsublabeljustify (**)
2g3. Controlling Tick Mark Location and Label Formatting
Attributes: x/X/y/Ylabel (**)
x/y/X/Yextent (**)
x/y/X/Ylabelheight (**)
x/X/y/Ylabelwidth (**)
x/Xsublabelout (**)
2h. Alternate Axes
Attributes: axis
x/yaxis (*,**)
2i. Zero Axes
Attributes: zero
zerofg
zerostyle
zerowidth
3. Trace Styles
Attributes: barwidth
fillcolor (*)
font
gradient (*)
style (*)
symbol (*)
symbolsize (*)
3a. Text Traces
Attributes: title (*)
titlefg (*)
titlefont (*)
4. Graph Attributes
Attributes: bg
bottom
fg
left
refer
right
top
y/Ybottom (**)
y/Ytop (**)
x/Xleft (**)
x/Xright (**)
x/Xmin (**)
x/Xmax (**)
y/Ymin (**)
y/Ymax (**)
5. User Interactions
5a. Zooming
5b. Vertical Cursor and Cross Hairs
Attributes: legendstyle
5c. Referencing a Graph, Line Trace, or Trace Point
Attributes: coordinate/Coordinate
refer
referpoint
selectable
selected
5d. Selecting the Legend or a Text Trace
5e. Repositioning the Legend and Traces
5f. Copying and Deleting Traces
Attributes: delete
5g. Editing and Creating Text Traces
Attributes: addtexttrace
copytextrace
delete (as callback function)
mode
textactivate
5h. Modifying and Creating Numeric Traces
Attributes: addtrace
copytrace
movelimit (*)
selected (*)
selectdistance
6. Monitoring Performance
Variable: s.QUIET
(*) Trace set attributes, or trace attributes for short. All the others
are graph attributes.
(**) An attribute with x/X/y/Y prefixed to its name is one that is
separately defined for all four axes. The four axes are: the normal
x-axis at the bottom of the graph, referred to as "x"; the normal y-axis
at the left of the graph, referred to as "y"; the alternate x-axis at
the top of the graph, referred to as "X"; and the alternate y-axis at
the right of the graph, referred to as "Y". For example, x/X/y/Ytitle
means there are four attributes: xtitle, Xtitle, ytitle, and Ytitle, one
for each of the axes; x/yaxis means there are two attributes, xaxis and
yaxis.
1. Introduction
¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢
The purpose of this tutorial is to familiarize the reader with the graph
display class in the A+ screen management system. In general, only those
aspects of screen management specific to graphs are discussed here. See
the general screen management tutorial to learn how the more widely
applicable functions apply to graphs.
The tutorial is made up of descriptions and A+ examples. You should set
up your Emacs environment to have two visible buffers, one holding the
tutorial and the other an A+ session. If you are currently reading this
in Emacs, simply press F4.
To bring individual expressions from the tutorial into the A+ session,
place the cursor on the expression and press F2. It is assumed that the
expressions and functions are brought into the A+ session when you first
encounter them.
If you need more help on running Emacs and A+ see the "Getting Started"
tutorial.
Once you have an active A+ session, load the screen management system by
entering
$load s
That is, place the cursor on the above expression and press F2.
At various points in the exercises, you will refresh the A+ session by
exiting with $off, pressing F4 to start A+ again, and then loading the
screen management system. Session refreshings will be indicated as
follows:
$off ã Exit from A+
Press F4 to start A+ again, then move the cursor back to the tutorial
buffer, on the next line.
$load s
You may make mistakes when running the tutorial and it may become
difficult to get back to a place where you can continue. At that point
you should simply go back to the latest session refresh sequence and
start over from there.
Two more things before we start. First of all, by default graphs appear
in the upper left corner of the screen. To avoid having the graphs
overlay the tutorial, move the Emacs screen to the lower right, or put
the tutorial in the bottom Emacs buffer and the A+ session in the top
(you can do this by pressing F5 and then F6; you may have to do it more
than once.)
Secondly, even though the default sizes of the examples may be quite
small, don't resize them unless told to do so, because the resizing may
change the details of the graphs.
In the examples we usually display the graphs first and then set their
attributes so that you can see the effects. In practice, however, you
set the attributes before displaying the graph.
2. The Components of a Graph
¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢¢
A graph is a layout composed of one or more trace sets. The simplest
trace set is a vector v, whose elements are plotted as the y-coordinates
with x-coordinates É#v. That is, the points (i,v[i]) are plotted for all
i from 0 to (#v)-1.
vû 53 14 27 2 31 85 30 11 67 50
gû`v
show `g is `graph
At this point you should see a window with "A+" in the grey title bar,
and a gray graph area below it. The graph area has a title area with "g"
in it, an x-axis and a y-axis, a legend, and a trace. This is the
default appearance of the graph. Each of these components can be
modified by setting the appropriate attributes, and there are other
components that do not appear in the default. And, of course, there can
be more than one trace on a graph. We will look at all of these
components in this section.
There are two attributes that allow us to control the size of the graph.
We will use these attributes for resizing to ensure that the assumptions
about the appearance of the graphs are correct.
`g has (`xs`ys;(300;200)) ã This may have no effect, i.e.,
ã this may be the default size.
2a. Traces and Trace Sets
The present graph g has only one trace set, i.e., one component variable
v. However, like any container, it can have more than one. For example,
wû(É#v)*2
gûg,`w
You should now see two traces on the graph, and an updated legend.
The more general form of a trace set is a matrix rather then a vector,
because then the x-coordinates as well as the y-coordinates can be
specified. The individual coordinates are arranged as rows of the
matrix, with the x-coordinates along the first column and y-coordinates
along the second. For example,
xû4 2Ò8 10 4 24 1 5 6 60
x
8 10
4 24
1 5
6 60
gûg,`x
You should now see three traces on the graph, and an updated legend.
Note that the new trace is indicated in the legend by "x:0", instead of
simply "x". The reason for this is that matrix trace sets can provide
more than one trace on the graph. For example, if we catenate a new
column onto x as follows:
xûx(,@1 0) 40 20 50 80
you will see a fourth trace and a new row in the legend, indicated by
"x:1". The 3-column matrix x provides two traces to the graph, both
with the same x-coordinates. One trace is defined by columns 0 and 1 of
x (the one indicated by "x:0" in the legend), and the other is defined
by columns 0 and 2 (and indicated by "x:1" in the legend). All traces in
a trace set share the same x-coordinates, which are in column 0 of the
matrix.
Note that in the default case, the traces in a trace set share the same
color, but are distinguished by their line styles. Both line color and
line style are trace set attributes that can be set. For example:
`w has (`linecolor;`yellow)
`w has (`linestyle;`dot)
A full list of colors can be found in the A+ reference manual. The line
styles are `solid, `dash (e.g., the trace indicated by "x:1" in the
legend), `dot and `dotdash. For example:
`w has (`linestyle;`dotdash)
(Toggle back and forth between the last two expressions to see the
difference in the two line styles.) Also, `dot1 through `dot5 give
various intervals between dots, with `dot1 the smallest, `dot5 the
largest, and `dot3 the same as `dot.
`w has (`linestyle;`dot1)
`w has (`linestyle;`dot2)
`w has (`linestyle;`dot3)
`w has (`linestyle;`dot4)
`w has (`linestyle;`dot5)
Analogously, there are `dash1 through `dash5 (different length dashes)
and `dotdash1 through `dotdash5.
The line colors and line styles can be set individually for all traces
in a trace set by specifying these attributes to have vectors of values.
`x has (`linecolor;`white `dodgerblue)
`x has (`linestyle;`dot `solid)
The last attribute affecting the appearance of line graphs allows the
line width to specified, which is useful for emphasis:
`v has (`linewidth;2)
Note that the width of the corresponding line segment in the legend also
changed. The units of line width are pixels.
The last thing to be illustrated in this section is that a trace set
with multiple visible traces behaves differently in a graph with a
single trace set and in a graph with multiple visible trace sets. We
will use a separate graph and locate it 350 pixels to the right, for
simultaneous viewing. First, return the original graph to its default
values:
`x has (`linecolor;; `linestyle;); `v has (`linewidth;);
xxû4 2Ò8 10 4 24 1 5 6 60
ggû`xx
show `gg is `graph; `gg has (`x;350);
xxûxx(,@1 0) 40 20 50 80
The two traces contributed by x to the graph g, which is a graph with
multiple trace sets, have the same color, but different line styles;
color is used to differentiate among trace sets. On the other hand, the
two traces contributed by xx to the graph gg, which has only one trace
set, have different colors, but the same line style.
free `gg
Most of the attributes set so far have been on the trace sets, but three
(the size parameters `xs and `ys and the horizontal position parameter
`x) have been on the graph itself. This distinction is sometimes made
explicit by our referring to attributes as "trace attributes" or "graph
attributes."
There are other visual forms a trace can take besides these various line
styles; see "3. Trace Styles."
2b. Title
The "g" that appears at the top of the gray plot area in our current
example is the title of the graph. A more meaningful title can be
specified using the `title attribute:
`g has (`title;"Graph Tutorial Example")
Both color and the font can also be set, and the title can be justified.
There may be a delay in changing the font. Wait for the change before
proceeding. (A list of recommended fonts can be found in the A+
Reference Manual.)
`g has (`titlefg;`yellow)
`g has (`titlefont;"helvetica-bold-20")
`g has (`titlejustify;`left) ã or `right
`g has (`titlejustify;`center)
The title can have more than one line:
`g has (`title;("Graph Tutorial Example";"Components of a Graph"))
Note that the plot area composed of the axes and traces was
automatically resized to accommodate the two rows of the title.
The title can be removed by setting it to the empty vector:
`g has (`title;"")
2c. Subtitle
One graph component that does not appear in the default form of a graph
is the subtitle. The subtitle appears between the title and the plot
area. Since it has color and font settings separate from those for the
title, it can be used for more effective title presentations. For
example, put the first row of the title back:
`g has (`title;"Graph Tutorial Example")
and put the second row back as the subtitle:
`g has (`subtitle;"Components of a Graph")
`g has (`subtitlefg;`blue)
`g has (`subtitlefont;"Times-Roman-15")
`g has (`subtitlejustify;`left) ã or `right
`g has (`subtitlejustify;`center)
Subtitles, like titles, can have more than one row, and are removed by
setting their value to "".
2d. Footnote
The footnote is another component that does not appear in the default
form of a graph.
`g has (`footnote;"Morgan Stanley Co.")
`g has (`footnotefg;`yellow)
`g has (`footnotefont;"Times-BoldItalic-15")
`g has (`footnotejustify;`center) ã or `right
`g has (`footnotejustify;`left)
Footnotes are removed by setting their value to "".
2e. Legend
The text in the legend can be set for each trace set:
`v has (`legend;"solid red")
`w has (`legend;"broken yellow")
`x has (`legend;("solid blue";"broken blue"))
Note that if the text for a legend entry is the empty character vector,
that entry is removed.
`v has (`legend;"")
`v has (`legend;"solid red")
At this point you may want to resize the graph window, since otherwise
the legend will now take up a large portion of the plot area.
`g has (`xs`ys;(600;500))
The legend box can also be repositioned within the plot area.
`g has (`legend;`br) ã Bottom right
`g has (`legend;`tc) ã top center
`g has (`legend;`tl) ã top left (where we started)
Other settings are `tr, `bl, and `bc. (Note that we just set the `legend
attribute for the graph g, while just above are settings of the `legend
attribute for trace sets.) In addition, you can specify the position of
the upper left corner of the legend box, as percentages of the
horizontal and vertical lengths of the graph window. They take effect
when `legend has the value `xy:
`g has (`xlegend `ylegend;(25;75)) ã the (x,y) percentages
`g has (`legend;`xy)
Now that the `legend attribute has been set to `xy, settings of `xlegend
and `ylegend take effect immediately:
`g has (`xlegend;50)
Note that the legend cannot be partially hidden by the choice of
`xlegend and `ylegend. For example, if these coordinates are set to
(95,95) one might expect that only the upper left corner of the legend
would be visible. However, this is not the case:
`g has (`xlegend `ylegend;(95;95)) ã the (x,y) percentages
The specified position is respected as far as possible, consistent with
keeping the legend completely visible.
The values of `xlegend and `ylegend are integers between 0 and 100 or,
alternatively, fractions between 0 and 1.
The legend can also be strung out horizontally:
`g has (`legend;`tl)
`g has (`legendstyle;`hor)
The original configuration is:
`g has (`legendstyle;`ver)
Other attributes control the colors and font of the legend.
Specifically, the background color of the legend:
`g has (`legendbg;`white)
the foreground color, or color of the text in the legend:
`g has (`legendfg;`blue)
the font of the text in the legend:
`g has (`legendfont;"Times-Roman-15")
and, finally, even the pixel width of the legend's highlight and shadow
thicknesses (the defaults are 1):
`g has (`legendshadowthickness;3)
`g has (`legendhlthickness;2)
The legend can be made to blend into the graph:
`g has (`legendbg;0Ø`bg of `g)
`g has (`legendshadowthickness;0)
`g has (`legendhlthickness;0)
The legend can be removed by setting the legend position to `none:
`g has (`legend;`none)
2f. x-Axis and y-Axis Titles
Titles for axes are two other components that do not appear in the
default form of a graph.
`g has (`xtitle;"0 to 9")
`g has (`ytitle;"0 to 81")
Let's make them big enough to be easily seen:
`g has (`xtitlefont;"Times-Roman-25")
`g has (`ytitlefont;"Times-Roman-25")
Note that the x-axis title is positioned below the x-axis and the y-axis
title is above the y-axis. The y-axis title can be repositioned
vertically along the y-axis as follows:
`g has (`ytitlestyle;`ver)
The axis titles can be justified:
`g has (`xtitlejustify;`left)
`g has (`xtitlejustify;`right)
`g has (`xtitlejustify;`center)
`g has (`ytitlejustify;`top)
`g has (`ytitlejustify;`bottom)
`g has (`ytitlejustify;`center)
Return to the original position with:
`g has (`ytitlestyle;`hor)
The y-axis title can now be justified right and left:
`g has (`ytitlejustify;`left)
`g has (`ytitlejustify;`right)
`g has (`ytitlejustify;`center)
Notice that there seems to be no difference in right and center
justification of the y-axis title. We can set the left margin so you can
see the difference:
`g has (`left;20)
`g has (`ytitlejustify;`left)
`g has (`ytitlejustify;`right)
`g has (`ytitlejustify;`center)
`g has (`left;0)
We'll have more to say about margins later. The colors of the axis
titles can be set separately:
`g has (`xtitlefg;`red)
`g has (`ytitlefg;`yellow)
2g. Axes
Most of the settable attributes in good graphics packages deal with
axes, and this one is no different. There are four parts to an axis: the
rule which extends the length of the axis; the tick marks; the labels on
the tick marks; and the grid lines of the graph associated with the tick
marks. Each of these parts can be controlled with the appropriate
attributes. In addition, there are a few attributes that affect the
overall appearance of the axes.
First of all, we can control the color of the axes:
`g has (`xfg;`yellow)
`g has (`yfg;`red)
We can also control the thickness of the axis rules:
`g has (`rulewidth;2)
As you can see, the thickness of both axes rules and tick marks are affected.
The units of the axis thickness are pixels.
A rule width of 0 has special meaning. Although it looks no different
from 1 on the screen, it has the effect of drawing the rules more
efficiently, and more importantly, perhaps, there is a noticable
difference when a graph is printed.
`g has (`rulewidth;0)
More interesting, perhaps, is the control one has over the style of the
axes. We will go through all the possibilities. For example, we can have
an x-axis only or a y-axis only.
`g has (`axis;`x)
`g has (`axis;`y)
`g has (`axis;`xy)
Vertical grid lines can be placed at the major x-axis tick marks.
`g has (`grid;`x)
Likewise, horizontal grid lines can be placed at the major y-axis tick
marks.
`g has (`grid;`y)
Both horizontal and vertical grid lines are also possible:
`g has (`grid;`xy)
Both the widths (in pixels) and colors of the gridlines can be set:
`g has (`gridwidth;2)
`g has (`gridfg;`green)
A grid width of 0 has the same effects as a rule width of 0:
`g has (`gridwidth;0)
There is a `rule attribute whose default value is `axis, meaning that
any axes that appear have rules. This attribute can also be set to
values like those for `grid, indicating which axes have rules. For
example, we can have a graph with an ordinary y-axis and just the x-axis
rule:
`g has (`axis;`y)
`g has (`rule;`xy)
An interesting effect is obtained by removing the rule from the y-axis:
`g has (`rule;`x)
The graph can have ascending values or descending values:
`g has (`ymode;`descend)
`g has (`ymode;`ascend)
2g1. Axis Tick Marks
We will use an uncluttered graph to illustrate the details of tick-mark
and label attributes.
$off ã Exit from A+
Press F4 to start A+ again, then move the cursor back to the tutorial
buffer, on the next line.
$load s
vû 53 14 27 2 31 85 30 11 67 50
gû`v
show `g is `graph
`g has (`xs`ys;(300;200)) ã This may have no effect, i.e.,
ã this may be the default size.
The lengths of both the major and minor tick marks can be set. The unit
of length is pixels. Let's first look at the default values to get a
sense of their scale.
`xmajorticksize of `g
< 10 ã A+ output
`xminorticksize of `g
< 6 ã A+ output
The tick marks can be made smaller, leaving a larger plot area. For
example:
`g has (`xminorticksize;2)
`g has (`xmajorticksize;5)
The number of minor tick marks that appear between major tick marks can
be specified, for the x-axis and y-axis separately. In the present
example, 4 minor tick marks between major tick marks on the y-axis would
put a mark at every increment of 5:
`g has (`yminorticks;4)
It often improves the appearance of a graph to remove the minor tick
marks, which can be done by setting their number to 0. For example:
`g has (`xminorticks;0)
The number of major tick marks can also be specified, if somewhat
indirectly, by specifying the increment between major tick marks. For
example:
`g has (`yinc;40)
`g has (`xinc;2)
And, finally, we can control the style of the tick marks: pointing away
from the plot area, into the plot area, or straddling the axis:
`g has (`ytickstyle;`in) ã The tick marks point inwards
`g has (`xtickstyle;`inout) ã The tick marks straddle the axis
`g has (`xtickstyle;`out) ã The tick marks point outwards
The latter is the default. Graphs with tick style `in are effective
because the plot area is larger, and the inward pointing ticks rarely
decrease the usable plot area.
2g2. Axis Labels
We have control over two aspects of the axis labels: the font in which
they are set and their format.
At this point it is useful to switch to an example with realistic data.
$off ã Exit from A+
Press F4 to start A+ again, then move the cursor back to the tutorial
buffer, on the next line.
$load s
xû0à "/usr/local/aplus-fsf-4.18/doc/tutorials/graphs/graph_data.m";
This data is high, low, open, close information taken at, roughly,
5-minute intervals over a 5-day period in Tokyo. The market day is
partitioned into 5-minute increments and x contains one row for each
period. A timestamp, which is in column 0, is the time of the last
reading for the 5-minute period in which it falls. The timestamps are
Unix timestamps.
The data in columns 1 through 4 of a given row are associated with the
5-minute time period in which the timestamp in column 0 lies. They
represent, starting with column 1, the high value of all readings taken
during the 5-minute period, the low value, the open, and the close.
At this point we need only one of the traces:
yûx[;0 1]
gû`y
show `g is `graph
`g has (`xs`ys;(300;200)) ã This may have no effect, i.e.,
ã this may be the default size.
You will notice that the data on the graph appears clustered in several
areas, and these clusters are connected by relatively long line
segments. The clusters represent periods of market activity, while the
long line segments represent periods during which the market is closed.
In applications, these long segments would be factored out to give the
graph a uniform appearance, but that is not a concern here.
Let's look at the timestamp format on the x-axis labels first. Since
this is daily data, we start with the seven-day format, which uses
abbreviated names for the days:
`g has (`xlabelout;`day7_u)
Note that the major tick marks indicate the beginning of every other
day, and the minor tick marks therefore mark the remaining days.
Let's look at days of the month or days of the year, which are integers
indicating the number of days since the beginning of the month or year:
`g has (`xlabelout;`day31_u)
The minor tick marks now represent half days.
`g has (`xlabelout;`day365_u)
Once again, the minor tick marks represent days.
The time span between major tick marks, and therefore the meaning of the
minor tick marks, depends to a large extent on the sizes of the labels,
because these sizes determine the number of labels the graph can
accommodate. We have some indirect control over the number of labels
that appear and their format, because we can specify the font for the
labels. (More direct control is described below in "2g3. Controlling Tick
Mark Location and Label Formatting".) For example:
`g has (`xlabelout;`day7_u)
Check the default label font, and then set it to a smaller pixel size.
`xlabelfont of `g
`g has (`xlabelfont;"Helvetica-Bold-7")
You should now see a major tick for each weekday. Of course the labels
are very hard to read. Another possibility is to simply choose the size
of the graph appropriately. First reset the axis font:
`g has (`xlabelfont;"Helvetica-Bold-12")
and then resize the graph:
`g has (`xs`ys;(800;300))
There are two month-only formats, one that uses names and the other the
numbers 1 through 12, and there are two year-only formats using 2 digits
and 4 digits. These formats are not particularly interesting for data
which is all from the same month, but for completeness here they are:
`g has (`xlabelout;`m_u)
`g has (`xlabelout;`m12_u)
`g has (`xlabelout;`y2_u)
`g has (`xlabelout;`y4_u)
The next format gives a text form of day, month and year, while the four
that follow give various abbreviated forms:
`g has (`xlabelout;`mdy_u)
`g has (`xlabelout;`mdy2_u)
`g has (`xlabelout;`mdy4_u)
`g has (`xlabelout;`dmy2_u)
`g has (`xlabelout;`dmy4_u)
The remaining time formats are hours, minutes, and seconds, so to get
major tick marks with these units, restrict the data to a single day, as
follows:
yû50Ùy
The market hours are 9:30 to 11:00 and 1:30 to 3:30. Test the following
formats:
`g has (`xlabelout;`hrmin)
`g has (`xlabelout;`hrmin24)
`g has (`xlabelout;`hr)
`g has (`xlabelout;`hr24)
To get major tick mark labels in minutes, further restrict the data as
follows:
yû12Ùy
This data is not fine enough to exhibit variations in seconds, but here are
the remaining time formats:
`g has (`xlabelout;`min)
`g has (`xlabelout;`sec)
`g has (`xlabelout;`minsec)
`g has (`xlabelout;`hrminsec)
`g has (`xlabelout;`hrminsec24)
Finally, you can remove the labels altogether:
`g has (`xlabelout;`)
In addition to the primary x-axis labels, there are sublabels that
provide a second level of text. Sublabels are useful when all the label
text does not fit conveniently on one line, and we will see examples of
this in the next section. For now, go back to the original graph of this
section:
yûx[;0 1]
`g has (`xs`ys;(300;200))
`g has (`xlabelout;`day31_u)
`g has (`xsublabelout;`m_u) ã The sublabels automatically appear.
One last point on x-axis formatting. The labels and sublabels can be
justified relative to the tick marks:
`g has (`xlabeljustify;`right)
`g has (`xlabeljustify;`left)
`g has (`xlabeljustify;`center)
`g has (`xsublabeljustify;`right)
`g has (`xsublabeljustify;`left)
`g has (`xsublabeljustify;`center)
The sublabels are removed in the same way as labels:
`g has (`xsublabelout;`)
Turning now to the y-axis, which in this example represents bond prices,
there are the following formats:
`g has (`ylabelout;`32nd)
`g has (`ylabelout;`64th)
`g has (`ylabelout;`128th)
`g has (`ylabelout;`320th)
`g has (`ylabelout;`328th)
y-axis labels can also be justified:
`g has (`ylabeljustify;`top)
`g has (`ylabeljustify;`bottom)
`g has (`ylabeljustify;`center)
Finally, we have three generally applicable label formats. For
convenience we will use the present example for illustration, even
though these formats are not appropriate for the data. The first of the
three displays the decimal part of the number as a fraction:
`g has (`ylabelout;`frac)
The last two provide conventional floating point and fixed point
formats:
`g has (`ylabelout;`float)
`g has (`ylabelout;`fixed)
The number of decimal digits that appear can be specified for the fixed
format:
`g has (`ylabelout;(`fixed;2))
The default label format is `float.
2g3. Controlling Tick Mark Location and Label Formatting
In addition to the variety of label formats illustrated above, you can
also specify your own format, much as you specify the format of any data
that appears on the screen. Furthermore, you have complete control over
the tick mark locations and the text of the labels for those tick marks.
Let's start with a clean slate.
$off ã Exit from A+
Press F4 to start A+ again, then move the cursor back to the tutorial
buffer, on the next line.
$load s
The screen management system provides ways for programmers to control
the formatting of tabular data on the screen. Each array on the screen
can be controlled separately. The control mechanisms for data on the
screen are:
Ê a formatting parameter for the dyadic primitive format
function î can be specified for an array, and will be applied
to every displayed element;
Ê a formatting parameter for the system function _fmt can be
specified, and will be applied to every displayed element;
Ê a function can be specified that will be called for every
displayed element.
The same rules apply to labels on tick marks, only now the data elements
being formatted are tick values. For example:
yû98+0.01«+?20Ò100
gû`y
show `g is `graph
`g has (`ylabelout;6.3) ã A valid format parameter of î
A second example:
`g has (`ylabelout;"f10.4") ã A valid format parameter of _fmt
`ylabelout can also be specified as a function. See the discussion of
the of the `out attribute in the A+ Reference Manual.
Complete control over ticks and tick labels is provided by the `ylabel
attribute. We'll begin by adjusting the window of the current graph
slightly, just to make sure the bottom and top ticks that are created
below will appear.
`g has (`ymin `ymax;(97.9;99.1))
The value of the `ylabel attribute is a four-element nested vector of
the form
ã (ticks;labels;sizes;widths)
where
- ticks is a numeric vector representing the tick values, or locations
on the axis where the tick marks occur;
- labels is either a nested vector of character vectors, where iØlabels
is the label for the tick value i#ticks, or a character matrix, where
i#labels is the label for the tick value i#ticks;
- sizes is a vector of numbers between 0 and 1, where the length of the
i-th tick mark is i#ticks times the current size of the major ticks
(that size is controlled by the `majorticksize attribute);
- widths is a vector of integers, where i#widths is the width, in
pixels, of the grid line at the ith tick mark.
Continuing the previous example:
ticksû98+.2«É6
labelsû("one";"two";"three";"four";"five";"six")
sizeû0 .2 .4 .6 .8 1
widthû0 1 2 3 4 5
`g has (`ylabel;(ticks;labels;size;width))
You should see tick marks at locations 98, 98.2,...,99 with labels "one"
through "six". The tick marks lengths are 0, 2,...,10 pixels (10 is the
value of the `majorticksize attribute). And, finally, there are grid
lines of width 0, 1,...,5 pixels. As you can see, the possibilities are
boundless for creating major and minor tick marks with various label and
grid line strategies.
In this example all four quantities have the same length, but that is
not required. If more labels are given than there are tick marks, the
extras are ignored. If fewer are given, the missing ones are considered
to be blank. In particular, tick marks without labels are obtained by
specifying one label, and making that one all blank.
`g has (`ylabel;(ticks;" ";size;width))
If either size or width has fewer elements than ticks, those elements
are used cyclically, in the manner of the A+ Reshape primitive.
`g has (`ylabel;(ticks;labels;size[1 3 5];width[2 4]))
It is not necessary to specify all four components; only ticks must be
present. If labels is missing, the default format is used, or the
setting of the labelout attribute if there is one.
`g has (`ylabel;(ticks;size[1 3 5];width[2 4]))
If only one of size and width is present, which it is can (almost)
always be determined by the values: widths must be whole numbers, while
sizes are 0, 1, or fractions in between. The one ambiguous case is a
vector of 0's and 1's, and that is taken to be a width specification.
`g has (`ylabel;(ticks;0 1))
Like `ylabelout, `ylabel can be assigned a function that will be called
whenever tick marks and labels are needed for a graph, e.g., each time a
graph is zoomed (see "5a. Zooming"). When called, the function must
produce a four-element vector like the one described above.
There are interesting interactions between xlabel settings and
sublabels. Suppose the x-axis in the present example represents dates
and define:
`g has (`xlabel;(2«É10;10 3Ò"JanAprJulOct"))
Each group of labels "Jan through "Oct" represents a year, and we can
use the sublabel attribute to put year designations under the groups:
`g has (`xsublabel;(3 11 19;3 4Ò"199219931994"))
When a graph is zoomed, a section of the view is blown up to fill the
entire plot area. If `ylabel is assigned a fixed value, as in the above
example, then these are the only tick marks that can be used for the
zoomed view. Some of them may fall in the range of the zoomed view, but
some may not. If the area of the original graph chosen for zooming
contained none of these tick values, no tick marks would appear. But if
`ylabel is assigned a function, that function will be called to
determine new tick locations and labels for the zoomed view.
There are several graph attributes that can be referenced in the `ylabel
function that produce information helpful in determining tick values and
labels.
`yextent of `g
is a three-element vector containing the minimum value along the y-axis,
the maximum value, and a scale factor. As a result of the last
expression you should see:
< 97.9 99.1 107.5
although the third element might be different. 97.9 is the minimum value
and 99.1 the maximum value along the y axis, which we set above. The
scale factor is such that
(99.1-97.9)«107.5
is the length of the y-axis in pixels. Resize the graph, evaluate
`yextent of `g
again, and you should see a new scale factor.
It should be easy to understand that the minimum and maximum values are
necessary for determining tick values. But what is the point of the
scale? Well, you don't want so many tick values that the labels overrun
each other. Since you know the length of the y-axis in pixels, once you
determine the number of tick marks, you know the distance between tick
marks in pixels. The labelheight attributes tell you the height in
pixels of all labels, and therefore you can determine whether or not
they overlap. For example:
`xlabelheight of `g
Analogously, xlabelwidth attributes tell you the width of labels in
pixels, which can be used, for example, to see that x-axis labels don't
overrun one another. However, the situation is more complicated for
x-axis labels, since both the label texts and font characters can have
different widths. Therefore, to determine the width of a proposed
label, the text of the label is part of the query:
(`xlabelwidth;"testlabel") of `g
It is also possible to determine the widths of several labels at once,
either as the rows of a character matrix or as the elements of a nested
vector of character vectors:
(`xlabelwidth;3 5Ò"one two three") of `g
or
(`xlabelwidth;("one";"two";"three")) of `g
Now that we have specified the y-axis labels and can determine their
widths, we can easily create a nice effect for these labels:
`g has (`ylabeljustify;`top)
`g has (`ymajorticksize;Ó/0Ø(`ylabelwidth;labels) of `g)
`g has (`ylabeljustify;`bottom)
2h. Alternate Axes
The last two graph components have to do with arranging traces with
different scales on the same graph. Neither of these components appear
in the default form of a graph. The components are the alternate x-axis
and the alternate y-axis. Wealues:
`g has (`ymode;`descend)
`g has (`ymode;`ascend)
2g1. Axis Tick Marks
We will use an uncluttered graph to illustrate the details of tick-mark
and label attributes.
$off ã Exit from A+
Press F4 to start A+ again, then move the cursor back to the tutorial
buffer, on the next line.
$load s
vû 53 14 27 2 31 85 30 11 67 50
gû`v
show `g is `graph
`g has (`xs`ys;(300;200)) ã This may have no effect, i.e.,
ã this may be the default size.
The lengths of both the major and minor tick marks can be set. The unit
of length is pixels. Let's first look at the default values to get a
sense of their scale.
`xmajorticksize of `g
< 10 ã A+ output
`xminorticksize of `g
< 6 ã A+ output
The tick marks can be made smaller, leaving a larger plot area. For
example:
`g has (`xminorticksize;2)
`g has (`xmajorticksize;5)
The number of minor tick marks that appear between major tick marks can
be specified, for the x-axis and y-axis separately. In the present
example, 4 minor tick marks between major tick marks on the y-axis would
put a mark at every increment of 5:
`g has (`yminorticks;4)
It often improves the appearance of a graph to remove the minor tick
marks, which can be done by setting their number to 0. For example:
`g has (`xminorticks;0)
The number of major tick marks can also be specified, if somewhat
indirectly, by specifying the increment between major tick marks. For
example:
`g has (`yinc;40)
`g has (`xinc;2)
And, finally, we can control the style of the tick marks: pointing away
from the plot area, into the plot area, or straddling the axis:
`g has (`ytickstyle;`in) ã The tick marks point inwards
`g has (`xtickstyle;`inout) ã The tick marks straddle the axis
`g has (`xtickstyle;`out) ã The tick marks point outwards
The latter is the default. Graphs with tick style `in are effective
because the plot area is larger, and the inward pointing ticks rarely
decrease the usable plot area.
2g2. Axis Labels
We have control over two aspects of the axis labels: the font in which
they are set and their format.
At this point it is useful to switch to an example with realistic data.
$off ã Exit from A+
Press F4 to start A+ again, then move the cursor back to the tutorial
buffer, on the next line.
$load s
xû0à "/usr/local/aplus-fsf-4.18/doc/tutorials/graphs/graph_data.m";
This data is high, low, open, close information taken at, roughly,
5-minute intervals over a 5-day period in Tokyo. The market day is
partitioned into 5-minute increments and x contains one row for each
period. A timestamp, which is in column 0, is the time of the last
reading for the 5-minute period in which it falls. The timestamps are
Unix timestamps.
The data in columns 1 through 4 of a given row are associated with the
5-minute time period in which the timestamp in column 0 lies. They
represent, starting with column 1, the high value of all readings taken
during the 5-minute period, the low value, the open, and the close.
At this point we need only one of the traces:
yûx[;0 1]
gû`y
show `g is `graph
`g has (`xs`ys;(300;200)) ã This may have no effect, i.e.,
ã this may be the default size.
You will notice that the data on the graph appears clustered in several
areas, and these clusters are connected by relatively long line
segments. The clusters represent periods of market activity, while the
long line segments represent periods during which the market is closed.
In applications, these long segments would be factored out to give the
graph a uniform appearance, but that is not a concern here.
Let's look at the timestamp format on the x-axis labels first. Since
this is daily data, we start with the seven-day format, which uses
abbreviated names for the days:
`g has (`xlabelout;`day7_u)
Note that the major tick marks indicate the beginning of every other
day, and the minor tick marks therefore mark the remaining days.
Let's look at days of the month or days of the year, which are integers
indicating the number of days since the beginning of the month or year:
`g has (`xlabelout;`day31_u)
The minor tick marks now represent half days.
`g has (`xlabelout;`day365_u)
Once again, the minor tick marks represent days.
The time span between major tick marks, and therefore the meaning of the
minor tick marks, depends to a large extent on the sizes of the labels,
because these sizes determine the number of labels the graph can
accommodate. We have some indirect control over the number of labels
that appear and their format, because we can specify the font for the
labels. (More direct control is described below in "2g3. Controlling Tick
Mark Location and Label Formatting".) For example:
`g has (`xlabelout;`day7_u)
Check the default label font, and then set it to a smaller pixel size.
`xlabelfont of `g
`g has (`xlabelfont;"Helvetica-Bold-7")
You should now see a major tick for each weekday. Of course the labels
are very hard to read. Another possibility is to simply choose the size
of the graph appropriately. First reset the axis font:
`g has (`xlabelfont;"Helvetica-Bold-12")
and then resize the graph:
`g has (`xs`ys;(800;300))
There are two month-only formats, one that uses names and the other the
numbers 1 through 12, and there are two year-only formats using 2 digits
and 4 digits. These formats are not particularly interesting for data
which is all from the same month, but for completeness here they are:
`g has (`xlabelout;`m_u)
`g has (`xlabelout;`m12_u)
`g has (`xlabelout;`y2_u)
`g has (`xlabelout;`y4_u)
The next format gives a text form of day, month and year, while the four
that follow give various abbreviated forms:
`g has (`xlabelout;`mdy_u)
`g has (`xlabelout;`mdy2_u)
`g has (`xlabelout;`mdy4_u)
`g has (`xlabelout;`dmy2_u)
`g has (`xlabelout;`dmy4_u)
The remaining time formats are hours, minutes, and seconds, so to get
major tick marks with these units, restrict the data to a single day, as
follows:
yû50Ùy
The market hours are 9:30 to 11:00 and 1:30 to 3:30. Test the following
formats:
`g has (`xlabelout;`hrmin)
`g has (`xlabelout;`hrmin24)
`g has (`xlabelout;`hr)
`g has (`xlabelout;`hr24)
To get major tick mark labels in minutes, further restrict the data as
follows:
yû12Ùy
This data is not fine enough to exhibit variations in seconds, but here are
the remaining time formats:
`g has (`xlabelout;`min)
`g has (`xlabelout;`sec)
`g has (`xlabelout;`minsec)
`g has (`xlabelout;`hrminsec)
`g has (`xlabelout;`hrminsec24)
Finally, you can remove the labels altogether:
`g has (`xlabelout;`)
In addition to the primary x-axis labels, there are sublabels that
provide a second level of text. Sublabels are useful when all the label
text does not fit conveniently on one line, and we will see examples of
this in the next section. For now, go back to the original graph of this
section:
yûx[;0 1]
`g has (`xs`ys;(300;200))
`g has (`xlabelout;`day31_u)
`g has (`xsublabelout;`m_u) ã The sublabels automatically appear.
One last point on x-axis formatting. The labels and sublabels can be
justified relative to the tick marks:
`g has (`xlabeljustify;`right)
`g has (`xlabeljustify;`left)
`g has (`xlabeljustify;`center)
`g has (`xsublabeljustify;`right)
`g has (`xsublabeljustify;`left)
`g has (`xsublabeljustify;`center)
The sublabels are removed in the same way as labels:
`g has (`xsublabelout;`)
Turning now to the y-axis, which in this example represents bond prices,
there are the following formats:
`g has (`ylabelout;`32nd)
`g has (`ylabelout;`64th)
`g has (`ylabelout;`128th)
`g has (`ylabelout;`320th)
`g has (`ylabelout;`328th)
y-axis labels can also be justified:
`g has (`ylabeljustify;`top)
`g has (`ylabeljustify;`bottom)
`g has (`ylabeljustify;`center)
Finally, we have three generally applicable label formats. For
convenience we will use the present example for illustration, even
though these formats are not appropriate for the data. The first of the
three displays the decimal part of the number as a fraction:
`g has (`ylabelout;`frac)
The last two provide conventional floating point and fixed point
formats:
`g has (`ylabelout;`float)
`g has (`ylabelout;`fixed)
The number of decimal digits that appear can be specified for the fixed
format:
`g has (`ylabelout;(`fixed;2))
The default label format is `float.
2g3. Controlling Tick Mark Location and Label Formatting
In addition to the variety of label formats illustrated above, you can
also specify your own format, much as you specify the format of any data
that appears on the screen. Furthermore, you have complete control over
the tick mark locations and the text of the labels for those tick marks.
Let's start with a clean slate.
$off ã Exit from A+
Press F4 to start A+ again, then move the cursor back to the tutorial
buffer, on the next line.
$load s
The screen management system provides ways for programmers to control
the formatting of tabular data on the screen. Each array on the screen
can be controlled separately. The control mechanisms for data on the
screen are:
Ê a formatting parameter for the dyadic primitive format
function î can be specified for an array, and will be applied
to every displayed element;
Ê a formatting parameter for the system function _fmt can be
specified, and will be applied to every displayed element;
Ê a function can be specified that will be called for every
displayed element.
The same rules apply to labels on tick marks, only now the data elements
being formatted are tick values. For example:
yû98+0.01«+?20Ò100
gû`y
show `g is `graph
`g has (`ylabelout;6.3) ã A valid format parameter of î
A second example:
`g has (`ylabelout;"f10.4") ã A valid format parameter of _fmt
`ylabelout can also be specified as a function. See the discussion of
the of the `out attribute in the A+ Reference Manual.
Complete control over ticks and tick labels is provided by the `ylabel
attribute. We'll begin by adjusting the window of the current graph
slightly, just to make sure the bottom and top ticks that are created
below will appear.
`g has (`ymin `ymax;(97.9;99.1))
The value of the `ylabel attribute is a four-element nested vector of
the form
ã (ticks;labels;sizes;widths)
where
- ticks is a numeric vector representing the tick values, or locations
on the axis where the tick marks occur;
- labels is either a nested vector of character vectors, where iØlabels
is the label for the tick value i#ticks, or a character matrix, where
i#labels is the label for the tick value i#ticks;
- sizes is a vector of numbers between 0 and 1, where the length of the
i-th tick mark is i#ticks times the current size of the major ticks
(that size is controlled by the `majorticksize attribute);
- widths is a vector of integers, where i#widths is the width, in
pixels, of the grid line at the ith tick mark.
Continuing the previous example:
ticksû98+.2«É6
labelsû("one";"two";"three";"four";"five";"six")
sizeû0 .2 .4 .6 .8 1
widthû0 1 2 3 4 5
`g has (`ylabel;(ticks;labels;size;width))
You should see tick marks at locations 98, 98.2,...,99 with labels "one"
through "six". The tick marks lengths are 0, 2,...,10 pixels (10 is the
value of the `majorticksize attribute). And, finally, there are grid
lines of width 0, 1,...,5 pixels. As you can see, the possibilities are
boundless for creating major and minor tick marks with various label and
grid line strategies.
In this example all four quantities have the same length, but that is
not required. If more labels are given than there are tick marks, the
extras are ignored. If fewer are given, the missing ones are considered
to be blank. In particular, tick marks without labels are obtained by
specifying one label, and making that one all blank.
`g has (`ylabel;(ticks;" ";size;width))
If either size or width has fewer elements than ticks, those elements
are used cyclically, in the manner of the A+ Reshape primitive.
`g has (`ylabel;(ticks;labels;size[1 3 5];width[2 4]))
It is not necessary to specify all four components; only ticks must be
present. If labels is missing, the default format is used, or the
setting of the labelout attribute if there is one.
`g has (`ylabel;(ticks;size[1 3 5];width[2 4]))
If only one of size and width is present, which it is can (almost)
always be determined by the values: widths must be whole numbers, while
sizes are 0, 1, or fractions in between. The one ambiguous case is a
vector of 0's and 1's, and that is taken to be a width specification.
`g has (`ylabel;(ticks;0 1))
Like `ylabelout, `ylabel can be assigned a function that will be called
whenever tick marks and labels are needed for a graph, e.g., each time a
graph is zoomed (see "5a. Zooming"). When called, the function must
produce a four-element vector like the one described above.
There are interesting interactions between xlabel settings and
sublabels. Suppose the x-axis in the present example represents dates
and define:
`g has (`xlabel;(2«É10;10 3Ò"JanAprJulOct"))
Each group of labels "Jan through "Oct" represents a year, and we can
use the sublabel attribute to put year designations under the groups:
`g has (`xsublabel;(3 11 19;3 4Ò"199219931994"))
When a graph is zoomed, a section of the view is blown up to fill the
entire plot area. If `ylabel is assigned a fixed value, as in the above
example, then these are the only tick marks that can be used for the
zoomed view. Some of them may fall in the range of the zoomed view, but
some may not. If the area of the original graph chosen for zooming
contained none of these tick values, no tick marks would appear. But if
`ylabel is assigned a function, that function will be called to
determine new tick locations and labels for the zoomed view.
There are several graph attributes that can be referenced in the `ylabel
function that produce information helpful in determining tick values and
labels.
`yextent of `g
is a three-element vector containing the minimum value along the y-axis,
the maximum value, and a scale factor. As a result of the last
expression you should see:
< 97.9 99.1 107.5
although the third element might be different. 97.9 is the minimum value
and 99.1 the maximum value along the y axis, which we set above. The
scale factor is such that
(99.1-97.9)«107.5
is the length of the y-axis in pixels. Resize the graph, evaluate
`yextent of `g
again, and you should see a new scale factor.
It should be easy to understand that the minimum and maximum values are
necessary for determining tick values. But what is the point of the
scale? Well, you don't want so many tick values that the labels overrun
each other. Since you know the length of the y-axis in pixels, once you
determine the number of tick marks, you know the distance between tick
marks in pixels. The labelheight attributes tell you the height in
pixels of all labels, and therefore you can determine whether or not
they overlap. For example:
`xlabelheight of `g
Analogously, xlabelwidth attributes tell you the width of labels in
pixels, which can be used, for example, to see that x-axis labels don't
overrun one another. However, the situation is more complicated for
x-axis labels, since both the label texts and font characters can have
different widths. Therefore, to determine the width of a proposed
label, the text of the label is part of the query:
(`xlabelwidth;"testlabel") of `g
It is also possible to determine the widths of several labels at once,
either as the rows of a character matrix or as the elements of a nested
vector of character vectors:
(`xlabelwidth;3 5Ò"one two three") of `g
or
(`xlabelwidth;("one";"two";"three")) of `g
Now that we have specified the y-axis labels and can determine their
widths, we can easily create a nice effect for these labels:
`g has (`ylabeljustify;`top)
`g has (`ymajorticksize;Ó/0Ø(`ylabelwidth;labels) of `g)
`g has (`ylabeljustify;`bottom)
2h. Alternate Axes
The last two graph components have to do with arranging traces with
different scales on the same graph. Neither of these components appear
in the default form of a graph. The components are the alternate x-axis
and the alternate y-axis. Wealues:
`g has (`ymode;`descend)
`g has (`ymode;`ascend)
2g1. Axis Tick Marks
We will use an uncluttered graph to illustrate the details of tick-mark
and label attributes.
$off ã Exit from A+
Press F4 to start A+ again, then move the cursor back to the tutorial
buffer, on the next line.
$load s
vû 53 14 27 2 31 85 30 11 67 50
gû`v
show `g is `graph
`g has (`xs`ys;(300;200)) ã This may have no effect, i.e.,
ã this may be the default size.
The lengths of both the major and minor tick marks can be set. The unit
of length is pixels. Let's first look at the default values to get a
sense of their scale.
`xmajorticksize of `g
< 10 ã A+ output
`xminorticksize of `g
< 6 ã A+ output
The tick marks can be made smaller, leaving a larger plot area. For
example:
`g has (`xminorticksize;2)
`g has (`xmajorticksize;5)
The number of minor tick marks that appear between major tick marks can
be specified, for the x-axis and y-axis separately. In the present
example, 4 minor tick marks between major tick marks on the y-axis would
put a mark at every increment of 5:
`g has (`yminorticks;4)
It often improves the appearance of a graph to remove the minor tick
marks, which can be done by setting their number to 0. For example:
`g has (`xminorticks;0)
The number of major tick marks can also be specified, if somewhat
indirectly, by specifying the increment between major tick marks. For
example:
`g has (`yinc;40)
`g has (`xinc;2)
And, finally, we can control the style of the tick marks: pointing away
from the plot area, into the plot area, or straddling the axis:
`g has (`ytickstyle;`in) ã The tick marks point inwards
`g has (`xtickstyle;`inout) ã The tick marks straddle the axis
`g has (`xtickstyle;`out) ã The tick marks point outwards
The latter is the default. Graphs with tick style `in are effective
because the plot area is larger, and the inward pointing ticks rarely
decrease the usable plot area.
2g2. Axis Labels
We have control over two aspects of the axis labels: the font in which
they are set and their format.
At this point it is useful to switch to an example with realistic data.
$off ã Exit from A+
Press F4 to start A+ again, then move the cursor back to the tutorial
buffer, on the next line.
$load s
xû0à "/usr/local/aplus-fsf-4.18/doc/tutorials/graphs/graph_data.m";
This data is high, low, open, close information taken at, roughly,
5-minute intervals over a 5-day period in Tokyo. The market day is
partitioned into 5-minute increments and x contains one row for each
period. A timestamp, which is in column 0, is the time of the last
reading for the 5-minute period in which it falls. The timestamps are
Unix timestamps.
The data in columns 1 through 4 of a given row are associated with the
5-minute time period in which the timestamp in column 0 lies. They
represent, starting with column 1, the high value of all readings taken
during the 5-minute period, the low value, the open, and the close.
At this point we need only one of the traces:
yûx[;0 1]
gû`y
show `g is `graph
`g has (`xs`ys;(300;200)) ã This may have no effect, i.e.,
ã this may be the default size.
You will notice that the data on the graph appears clustered in several
areas, and these clusters are connected by relatively long line
segments. The clusters represent periods of market activity, while the
long line segments represent periods during which the market is closed.
In applications, these long segments would be factored out to give the
graph a uniform appearance, but that is not a concern here.
Let's look at the timestamp format on the x-axis labels first. Since
this is daily data, we start with the seven-day format, which uses
abbreviated names for the days:
`g has (`xlabelout;`day7_u)
Note that the major tick marks indicate the beginning of every other
day, and the minor tick marks therefore mark the remaining days.
Let's look at days of the month or days of the year, which are integers
indicating the number of days since the beginning of the month or year:
`g has (`xlabelout;`day31_u)
The minor tick marks now represent half days.
`g has (`xlabelout;`day365_u)
Once again, the minor tick marks represent days.
The time span between major tick marks, and therefore the meaning of the
minor tick marks, depends to a large extent on the sizes of the labels,
because these sizes determine the number of labels the graph can
accommodate. We have some indirect control over the number of labels
that appear and their format, because we can specify the font for the
labels. (More direct control is described below in "2g3. Controlling Tick
Mark Location and Label Formatting".) For example:
`g has (`xlabelout;`day7_u)
Check the default label font, and then set it to a smaller pixel size.
`xlabelfont of `g
`g has (`xlabelfont;"Helvetica-Bold-7")
You should now see a major tick for each weekday. Of course the labels
are very hard to read. Another possibility is to simply choose the size
of the graph appropriately. First reset the axis font:
`g has (`xlabelfont;"Helvetica-Bold-12")
and then resize the graph:
`g has (`xs`ys;(800;300))
There are two month-only formats, one that uses names and the other the
numbers 1 through 12, and there are two year-only formats using 2 digits
and 4 digits. These formats are not particularly interesting for data
which is all from the same month, but for completeness here they are:
`g has (`xlabelout;`m_u)
`g has (`xlabelout;`m12_u)
`g has (`xlabelout;`y2_u)
`g has (`xlabelout;`y4_u)
The next format gives a text form of day, month and year, while the four
that follow give various abbreviated forms:
`g has (`xlabelout;`mdy_u)
`g has (`xlabelout;`mdy2_u)
`g has (`xlabelout;`mdy4_u)
`g has (`xlabelout;`dmy2_u)
`g has (`xlabelout;`dmy4_u)
The remaining time formats are hours, minutes, and seconds, so to get
major tick marks with these units, restrict the data to a single day, as
follows:
yû50Ùy
The market hours are 9:30 to 11:00 and 1:30 to 3:30. Test the following
formats:
`g has (`xlabelout;`hrmin)
`g has (`xlabelout;`hrmin24)
`g has (`xlabelout;`hr)
`g has (`xlabelout;`hr24)
To get major tick mark labels in minutes, further restrict the data as
follows:
yû12Ùy
This data is not fine enough to exhibit variations in seconds, but here are
the remaining time formats:
`g has (`xlabelout;`min)
`g has (`xlabelout;`sec)
`g has (`xlabelout;`minsec)
`g has (`xlabelout;`hrminsec)
`g has (`xlabelout;`hrminsec24)
Finally, you can remove the labels altogether:
`g has (`xlabelout;`)
In addition to the primary x-axis labels, there are sublabels that
provide a second level of text. Sublabels are useful when all the label
text does not fit conveniently on one line, and we will see examples of
this in the next section. For now, go back to the original graph of this
section:
yûx[;0 1]
`g has (`xs`ys;(300;200))
`g has (`xlabelout;`day31_u)
`g has (`xsublabelout;`m_u) ã The sublabels automatically appear.
One last point on x-axis formatting. The labels and sublabels can be
justified relative to the tick marks:
`g has (`xlabeljustify;`right)
`g has (`xlabeljustify;`left)
`g has (`xlabeljustify;`center)
`g has (`xsublabeljustify;`right)
`g has (`xsublabeljustify;`left)
`g has (`xsublabeljustify;`center)
The sublabels are removed in the same way as labels:
`g has (`xsublabelout;`)
Turning now to the y-axis, which in this example represents bond prices,
there are the following formats:
`g has (`ylabelout;`32nd)
`g has (`ylabelout;`64th)
`g has (`ylabelout;`128th)
`g has (`ylabelout;`320th)
`g has (`ylabelout;`328th)
y-axis labels can also be justified:
`g has (`ylabeljustify;`top)
`g has (`ylabeljustify;`bottom)
`g has (`ylabeljustify;`center)
Finally, we have three generally applicable label formats. For
convenience we will use the present example for illustration, even
though these formats are not appropriate for the data. The first of the
three displays the decimal part of the number as a fraction:
`g has (`ylabelout;`frac)
The last two provide conventional floating point and fixed point
formats:
`g has (`ylabelout;`float)
`g has (`ylabelout;`fixed)
The number of decimal digits that appear can be specified for the fixed
format:
`g has (`ylabelout;(`fixed;2))
The default label format is `float.
2g3. Controlling Tick Mark Location and Label Formatting
In addition to the variety of label formats illustrated above, you can
also specify your own format, much as you specify the format of any data
that appears on the screen. Furthermore, you have complete control over
the tick mark locations and the text of the labels for those tick marks.
Let's start with a clean slate.
$off ã Exit from A+
Press F4 to start A+ again, then move the cursor back to the tutorial
buffer, on the next line.
$load s
The screen management system provides ways for programmers to control
the formatting of tabular data on the screen. Each array on the screen
can be controlled separately. The control mechanisms for data on the
screen are:
Ê a formatting parameter for the dyadic primitive format
function î can be specified for an array, and will be applied
to every displayed element;
Ê a formatting parameter for the system function _fmt can be
specified, and will be applied to every displayed element;
Ê a function can be specified that will be called for every
displayed element.
The same rules apply to labels on tick marks, only now the data elements
being formatted are tick values. For example:
yû98+0.01«+?20Ò100
gû`y
show `g is `graph
`g has (`ylabelout;6.3) ã A valid format parameter of î
A second example:
`g has (`ylabelout;"f10.4") ã A valid format parameter of _fmt
`ylabelout can also be specified as a function. See the discussion of
the of the `out attribute in the A+ Reference Manual.
Complete control over ticks and tick labels is provided by the `ylabel
attribute. We'll begin by adjusting the window of the current graph
slightly, just to make sure the bottom and top ticks that are created
below will appear.
`g has (`ymin `ymax;(97.9;99.1))
The value of the `ylabel attribute is a four-element nested vector of
the form
ã (ticks;labels;sizes;widths)
where
- ticks is a numeric vector representing the tick values, or locations
on the axis where the tick marks occur;
- labels is either a nested vector of character vectors, where iØlabels
is the label for the tick value i#ticks, or a character matrix, where
i#labels is the label for the tick value i#ticks;
- sizes is a vector of numbers between 0 and 1, where the length of the
i-th tick mark is i#ticks times the current size of the major ticks
(that size is controlled by the `majorticksize attribute);
- widths is a vector of integers, where i#widths is the width, in
pixels, of the grid line at the ith tick mark.
Continuing the previous example:
ticksû98+.2«É6
labelsû("one";"two";"three";"four";"five";"six")
sizeû0 .2 .4 .6 .8 1
widthû0 1 2 3 4 5
`g has (`ylabel;(ticks;labels;size;width))
You should see tick marks at locations 98, 98.2,...,99 with labels "one"
through "six". The tick marks lengths are 0, 2,...,10 pixels (10 is the
value of the `majorticksize attribute). And, finally, there are grid
lines of width 0, 1,...,5 pixels. As you can see, the possibilities are
boundless for creating major and minor tick marks with various label and
grid line strategies.
In this example all four quantities have the same length, but that is
not required. If more labels are given than there are tick marks, the
extras are ignored. If fewer are given, the missing ones are considered
to be blank. In particular, tick marks without labels are obtained by
specifying one label, and making that one all blank.
`g has (`ylabel;(ticks;" ";size;width))
If either size or width has fewer elements than ticks, those elements
are used cyclically, in the manner of the A+ Reshape primitive.
`g has (`ylabel;(ticks;labels;size[1 3 5];width[2 4]))
It is not necessary to specify all four components; only ticks must be
present. If labels is missing, the default format is used, or the
setting of the labelout attribute if there is one.
`g has (`ylabel;(ticks;size[1 3 5];width[2 4]))
If only one of size and width is present, which it is can (almost)
always be determined by the values: widths must be whole numbers, while
sizes are 0, 1, or fractions in between. The one ambiguous case is a
vector of 0's and 1's, and that is taken to be a width specification.
`g has (`ylabel;(ticks;0 1))
Like `ylabelout, `ylabel can be assigned a function that will be called
whenever tick marks and labels are needed for a graph, e.g., each time a
graph is zoomed (see "5a. Zooming"). When called, the function must
produce a four-element vector like the one described above.
There are interesting interactions between xlabel settings and
sublabels. Suppose the x-axis in the present example represents dates
and define:
`g has (`xlabel;(2«É10;10 3Ò"JanAprJulOct"))
Each group of labels "Jan through "Oct" represents a year, and we can
use the sublabel attribute to put year designations under the groups:
`g has (`xsublabel;(3 11 19;3 4Ò"199219931994"))
When a graph is zoomed, a section of the view is blown up to fill the
entire plot area. If `ylabel is assigned a fixed value, as in the above
example, then these are the only tick marks that can be used for the
zoomed view. Some of them may fall in the range of the zoomed view, but
some may not. If the area of the original graph chosen for zooming
contained none of these tick values, no tick marks would appear. But if
`ylabel is assigned a function, that function will be called to
determine new tick locations and labels for the zoomed view.
There are several graph attributes that can be referenced in the `ylabel
function that produce information helpful in determining tick values and
labels.
`yextent of `g
is a three-element vector containing the minimum value along the y-axis,
the maximum value, and a scale factor. As a result of the last
expression you should see:
< 97.9 99.1 107.5
although the third element might be different. 97.9 is the minimum value
and 99.1 the maximum value along the y axis, which we set above. The
scale factor is such that
(99.1-97.9)«107.5
is the length of the y-axis in pixels. Resize the graph, evaluate
`yextent of `g
again, and you should see a new scale factor.
It should be easy to understand that the minimum and maximum values are
necessary for determining tick values. But what is the point of the
scale? Well, you don't want so many tick values that the labels overrun
each other. Since you know the length of the y-axis in pixels, once you
determine the number of tick marks, you know the distance between tick
marks in pixels. The labelheight attributes tell you the height in
pixels of all labels, and therefore you can determine whether or not
they overlap. For example:
`xlabelheight of `g
Analogously, xlabelwidth attributes tell you the width of labels in
pixels, which can be used, for example, to see that x-axis labels don't
overrun one another. However, the situation is more complicated for
x-axis labels, since both the label texts and font characters can have
different widths. Therefore, to determine the width of a proposed
label, the text of the label is part of the query:
(`xlabelwidth;"testlabel") of `g
It is also possible to determine the widths of several labels at once,
either as the rows of a character matrix or as the elements of a nested
vector of character vectors:
(`xlabelwidth;3 5Ò"one two three") of `g
or
(`xlabelwidth;("one";"two";"three")) of `g
Now that we have specified the y-axis labels and can determine their
widths, we can easily create a nice effect for these labels:
`g has (`ylabeljustify;`top)
`g has (`ymajorticksize;Ó/0Ø(`ylabelwidth;labels) of `g)
`g has (`ylabeljustify;`bottom)
2h. Alternate Axes
The last two graph components have to do with arranging traces with
different scales on the same graph. Neither of these components appear
in the default form of a graph. The components are the alternate x-axis
and the alternate y-axis. Wealues:
`g has (`ymode;`descend)
`g has (`ymode;`ascend)
2g1. Axis Tick Marks
We will use an uncluttered graph to illustrate the details of tick-mark
and label attributes.
$off ã Exit from A+
Press F4 to start A+ again, then move the cursor back to the tutorial
buffer, on the next line.
$load s
vû 53 14 27 2 31 85 30 11 67 50
gû`v
show `g is `graph
`g has (`xs`ys;(300;200)) ã This may have no effect, i.e.,
ã this may be the default size.
The lengths of both the major and minor tick marks can be set. The unit
of length is pixels. Let's first look at the default values to get a
sense of their scale.
`xmajorticksize of `g
< 10 ã A+ output
`xminorticksize of `g
< 6 ã A+ output
The tick marks can be made smaller, leaving a larger plot area. For
example:
`g has (`xminorticksize;2)
`g has (`xmajorticksize;5)
The number of minor tick marks that appear between major tick marks can
be specified, for the x-axis and y-axis separately. In the present
example, 4 minor tick marks between major tick marks on the y-axis would
put a mark at every increment of 5:
`g has (`yminorticks;4)
It often improves the appearance of a graph to remove the minor tick
marks, which can be done by setting their number to 0. For example:
`g has (`xminorticks;0)
The number of major tick marks can also be specified, if somewhat
indirectly, by specifying the increment between major tick marks. For
example:
`g has (`yinc;40)
`g has (`xinc;2)
And, finally, we can control the style of the tick marks: pointing away
from the plot area, into the plot area, or straddling the axis:
`g has (`ytickstyle;`in) ã The tick marks point inwards
`g has (`xtickstyle;`inout) ã The tick marks straddle the axis
`g has (`xtickstyle;`out) ã The tick marks point outwards
The latter is the default. Graphs with tick style `in are effective
because the plot area is larger, and the inward pointing ticks rarely
decrease the usable plot area.
2g2. Axis Labels
We have control over two aspects of the axis labels: the font in which
they are set and their format.
At this point it is useful to switch to an example with realistic data.
$off ã Exit from A+
Press F4 to start A+ again, then move the cursor back to the tutorial
buffer, on the next line.
$load s
xû0à "/usr/local/aplus-fsf-4.18/doc/tutorials/graphs/graph_data.m";
This data is high, low, open, close information taken at, roughly,
5-minute intervals over a 5-day period in Tokyo. The market day is
partitioned into 5-minute increments and x contains one row for each
period. A timestamp, which is in column 0, is the time of the last
reading for the 5-minute period in which it falls. The timestamps are
Unix timestamps.
The data in columns 1 through 4 of a given row are associated with the
5-minute time period in which the timestamp in column 0 lies. They
represent, starting with column 1, the high value of all readings taken
during the 5-minute period, the low value, the open, and the close.
At this point we need only one of the traces:
yûx[;0 1]
gû`y
show `g is `graph
`g has (`xs`ys;(300;200)) ã This may have no effect, i.e.,
ã this may be the default size.
You will notice that the data on the graph appears clustered in several
areas, and these clusters are connected by relatively long line
segments. The clusters represent periods of market activity, while the
long line segments represent periods during which the market is closed.
In applications, these long segments would be factored out to give the
graph a uniform appearance, but that is not a concern here.
Let's look at the timestamp format on the x-axis labels first. Since
this is daily data, we start with the seven-day format, which uses
abbreviated names for the days:
`g has (`xlabelout;`day7_u)
Note that the major tick marks indicate the beginning of every other
day, and the minor tick marks therefore mark the remaining days.
Let's look at days of the month or days of the year, which are integers
indicating the number of days since the beginning of the month or year:
`g has (`xlabelout;`day31_u)
The minor tick marks now represent half days.
`g has (`xlabelout;`day365_u)
Once again, the minor tick marks represent days.
The time span between major tick marks, and therefore the meaning of the
minor tick marks, depends to a large extent on the sizes of the labels,
because these sizes determine the number of labels the graph can
accommodate. We have some indirect control over the number of labels
that appear and their format, because we can specify the font for the
labels. (More direct control is described below in "2g3. Controlling Tick
Mark Location and Label Formatting".) For example:
`g has (`xlabelout;`day7_u)
Check the default label font, and then set it to a smaller pixel size.
`xlabelfont of `g
`g has (`xlabelfont;"Helvetica-Bold-7")
You should now see a major tick for each weekday. Of course the labels
are very hard to read. Another possibility is to simply choose the size
of the graph appropriately. First reset the axis font:
`g has (`xlabelfont;"Helvetica-Bold-12")
and then resize the graph:
`g has (`xs`ys;(800;300))
There are two month-only formats, one that uses names and the other the
numbers 1 through 12, and there are two year-only formats using 2 digits
and 4 digits. These formats are not particularly interesting for data
which is all from the same month, but for completeness here they are:
`g has (`xlabelout;`m_u)
`g has (`xlabelout;`m12_u)
`g has (`xlabelout;`y2_u)
`g has (`xlabelout;`y4_u)
The next format gives a text form of day, month and year, while the four
that follow give various abbreviated forms:
`g has (`xlabelout;`mdy_u)
`g has (`xlabelout;`mdy2_u)
`g has (`xlabelout;`mdy4_u)
`g has (`xlabelout;`dmy2_u)
`g has (`xlabelout;`dmy4_u)
The remaining time formats are hours, minutes, and seconds, so to get
major tick marks with these units, restrict the data to a single day, as
follows:
yû50Ùy
The market hours are 9:30 to 11:00 and 1:30 to 3:30. Test the following
formats:
`g has (`xlabelout;`hrmin)
`g has (`xlabelout;`hrmin24)
`g has (`xlabelout;`hr)
`g has (`xlabelout;`hr24)
To get major tick mark labels in minutes, further restrict the data as
follows:
yû12Ùy
This data is not fine enough to exhibit variations in seconds, but here are
the remaining time formats:
`g has (`xlabelout;`min)
`g has (`xlabelout;`sec)
`g has (`xlabelout;`minsec)
`g has (`xlabelout;`hrminsec)
`g has (`xlabelout;`hrminsec24)
Finally, you can remove the labels altogether:
`g has (`xlabelout;`)
In addition to the primary x-axis labels, there are sublabels that
provide a second level of text. Sublabels are useful when all the label
text does not fit conveniently on one line, and we will see examples of
this in the next section. For now, go back to the original graph of this
section:
yûx[;0 1]
`g has (`xs`ys;(300;200))
`g has (`xlabelout;`day31_u)
`g has (`xsublabelout;`m_u) ã The sublabels automatically appear.
One last point on x-axis formatting. The labels and sublabels can be
justified relative to the tick marks:
`g has (`xlabeljustify;`right)
`g has (`xlabeljustify;`left)
`g has (`xlabeljustify;`center)
`g has (`xsublabeljustify;`right)
`g has (`xsublabeljustify;`left)
`g has (`xsublabeljustify;`center)
The sublabels are removed in the same way as labels:
`g has (`xsublabelout;`)
Turning now to the y-axis, which in this example represents bond prices,
there are the following formats:
`g has (`ylabelout;`32nd)
`g has (`ylabelout;`64th)
`g has (`ylabelout;`128th)
`g has (`ylabelout;`320th)
`g has (`ylabelout;`328th)
y-axis labels can also be justified:
`g has (`ylabeljustify;`top)
`g has (`ylabeljustify;`bottom)
`g has (`ylabeljustify;`center)
Finally, we have three generally applicable label formats. For
convenience we will use the present example for illustration, even
though these formats are not appropriate for the data. The first of the
three displays the decimal part of the number as a fraction:
`g has (`ylabelout;`frac)
The last two provide conventional floating point and fixed point
formats:
`g has (`ylabelout;`float)