A Multigraph graph has one or more horizontal axes, and one or more
vertical axes. The location and other display properties of the axes
are specified with the horizontalaxis
and
verticalaxis
elements in the mugl file.
This includes mathematical information such as the data type
and range of values along the axis, as well as display information such
as how the axis should be labeled, a title to be drawn for the axis, and
so on.
A mugl file can contain any number (0 or more) of horizontalaxis
and verticalaxis
elements. Each graph always contains at least one horizontal axis and
at least one vertical axis.
If the horizontalaxis
element is missing,
multigraph creates a horizontal axis with all the default settings.
The same is true for the the verticalaxis
tag.
The horizontalaxis
and
verticalaxis
elements have the following
attributes:
id
An identifier that can be used to refer to this axis elsewhere in the mugl file. If this attribute is missing, it defaults to "x" for the first horizontal axis, and to "x1", "x2", ... for any additional horizontal axes. The default is "y" for the first vertical axis, and "y1", "y2", ... for any additional vertical axes.
type
Indicates the data type for the axis. Should be one of "number" or "datetime". The default is "number".
length
The length of the axis. There are two ways to specify the axis length. The first way is to simply give a number between 0 and 1, which represents a fraction of the parallel dimension of the plot area (width for horizontal axes, height for vertical axes). So, for example, for a horizontal axis, a value of "1" means that the axis length is exactly the width of the plot area, and a value of "0.5" would mean that the axis is half as long as the width of the plot area.
The second way to specify an axis length is to give an expression of the form "A+B" or "A-B". In this case, the first number A represents a fraction of the parallel dimension of the plot area, as above, and the second number +B or -B represents a number of pixels to add or subtract from that length. So, for example, a length of "1-10" for a horizontal axis would mean 10 pixels less than the width of the plot area. A value of "0.5+20" for a vertical axis would mean 20 pixels longer than half the height of the plot area. If for some reason you want to specify an axis length exactly in terms of pixels, use 0 for A; so for example, "0+200" would give an axis that is 200 pixels long. (Note that you definitely need to specify the "0+" in this case; if you specify a length simply as "200", Multigraph will interpret it, according to the first method above, as 200 times the width or height of the plot area, which is almost certainly not what you want.)
anchor
base
position
These attributes give the location of the axis relative to the plot area, according
to the conventions described in Section 4.6.1, “Positioning”.
base
is the location of the base point relative to the plot area;
the default value for base
is "-1 -1" --- i.e. the lower left corner of the plot area.
anchor
is a single number (not a coordinate pair) between -1 and 1
indicating the location of the anchor point along the axis. The default is "-1", which
represents the left endpoint of a horizontal axis, or the bottom endpoint of a vertical axis.
position
is a coordinate pair of pixel offsets, as described in
Section 4.6.1, “Positioning”; its default value is "0 0".
Versions of Multigraph prior to version 2.3 used a slightly different axis positioning
system, in which the position
attribute was a single number
indicating a pixel displacement from the bottom (for horizontal axes) or left (for vertical axes) edge
of the plot area. To provide backward compatibility,
if position
is specified as a single number, the current version of Multigraph
will interpret it to be a displacement in the direction perpendicular to the axis; this behavior,
together with the default values of the
base
and anchor
attributes (which did not exist in the
older versions of Multigraph), gives backward compatibility with the older style of axis
positioning. In new MUGL files, you can often achive the desired axis positioning using
only the
length
,
base
, and/or
anchor
attributes, and accept the
default value of "0 0" for the position
attribute.
positionbase
Deprecated. The current version of Multigraph
accepts this option to provide backward compatibility with older versions, but
it should not be used in new MUGL files. Use the base
attribute instead to switch a vertical axis to be placed relative to the
right edge of the plot area (base="1 -1", for example), or to
switch a horizontal axis to be placed relative to the
top edge of the plot area (base="-1 1", for example).
pregap
postgap
Deprecated. Do not use these.
min
The minimum data value for the axis --- i.e., the data value corresponding to the left (for horizontal axes) or bottom (for vertical axes) endpoint of the axis. If the axis is a "number" type axis, this value is a number. If it is a "datetime" type axis, the value is a datetime in the format YYYYMMDDHHmmss.
Alternatively "min" value may be the keyword "auto", which indicates that the minimum data value for the axis should be computed from the given data. This only works for data sources where the entire data set is available at the outset --- it does not work for web-service based data sources.
The default value for the "min" attribute is "auto".
minposition
An expression that indicates the location along the axis corresponding to the minimum data value (before any panning or zooming that the user might do). This is expressed in general in the form "A+B" or "A-B", where A is a relative coordinate between -1 and 1, and B is pixel offset. The "+B" or "-B" is optional; if it is not present, B is taken to be 0. So, for example, minposition="-1" corresponds to the left or bottom endpoint of the axis; this is the default. minposition="-1+5" corresponds to a point that is 5 pixels to the right of the left endpoint, or above the bottom endpoint.
max
The maximum data value for the axis --- i.e., the data value corresponding to the right (for horizontal axes) or top (for vertical axes) endpoint of the axis. If the axis is a "number" type axis, this value is a number. If it is a "datetime" type axis, the value is a datetime in the format YYYYMMDDHHmmss.
Alternatively "max" value may be the keyword "auto", which indicates that the maximum data value for the axis should be computed from the given data. This only works for data sources where the entire data set is available at the outset --- it does not swork for web-service based data sources.
The default value for the "max" attribute is "auto".
maxposition
An expression that indicates the location along the axis corresponding to the maximum data value (before any panning or zooming that the user might do). This is expressed in general in the form "A+B" or "A-B", where A is a relative coordinate between -1 and 1, and B is pixel offset. The "+B" or "-B" is optional; if it is not present, B is taken to be 0. So, for example, maxposition="1" corresponds to the right or top endpoint of the axis; this is the default. maxposition="1-5" corresponds to a point that is 5 pixels to the left of the right endpoint, or below the top endpoint.
Note that is is possible to specify a minposition
and maxposition
combination in which the min position is to the right
of, or above, the max position, which will cause the data values along the axis to
increase in the opposite direction from usual (increasing leftward for horizontal
axes, or downward for vertical axes). This is perfectly valid and will work correctly,
but you should make sure that it is really what you want before deciding to make
use of this feature, because it is likely to be confusing to users, unless there
is a good reason to portray your data in this manner.
Figure 4.2, “Horizontal Axis Specifications” and Figure 4.3, “Vertical Axis Specifications”
show how these attribute values determine the way that each kind of axis is displayed
relative to the plot area. Note that the position of each axis is relative to an edge
of the plot area, but all or part of the axis may lie outside the plot area (in the padding
box). In particular, a negative position
value represents a distance
away from the plot area (into the padding box), and
negative
pregap
and
postgap
values cause the ends of the axis to extend into the padding box.
In addition to the above attributes, the horizontalaxis
and verticalaxis
elements may contain the following
subelements:
title
The text of this element is used as a title for the axis; it is positioned and oriented according
to the values of the
position
,
anchor
, and
angle
attributes described in Section 4.6.1, “Positioning”. The
title is positioned relative to the the center of the axis; the "position" is a pixel offset from this point.
(The "base" point mentioned in Section 4.6.1, “Positioning”
The default anchor point depends on the choice and position of the axis. For a horizontal axis,
the default anchor point is "0 1" if the axis is positioned at the bottom of the graph
(positionbase="bottom"), or "0 -1" if the axis is positioned at the top of the graph (positionbase="top").
For a vertical axis,
the title's default anchor point is "1 0" if the axis is positioned to the left of the graph
(positionbase="left"), or "-1 0" if the axis is positioned to the right of the graph (positionbase="right").
The default angle is always 0. The default title position also depends on the axis, and has
been chosen to look reasonable in most common situations; see the source file Config.as if you want
to know exactly what the default position values are.
If there
is no title
element, the axis's title defaults to its
id
. To prevent a title from being drawn at all, use
an empty title
tag ("<title/>
").
labels
The labels
element specifies how multigraph will draw
tick marks along the axis, and text labels for the tick marks. It has two possible forms,
depending on whether it has a "spacing" attribute. In the first case, when it does
have a "spacing" attribute, it takes the following attributes:
format
A string describing the format to be used for tick labels. The syntax for this string depends on the type of the axis. For 'number' type axes, it should be a C-style "printf" format string, such as '%1d', which is the default. For 'datetime' type axes, it should be a string containing some combination of the following special format characters, each of which should be preceeded by a '%':
Character | Expansion |
Y | four digit year |
y | two digit year |
d | day of month without leading zero |
D | 2-digit day of month with leading zero |
h | hour of day, 12 hour clock |
H | hour of day, 24 hour clock |
i | minutes |
m | month number without leading zero |
M | 2-digit month number with leading zero |
N | month name, spelled out |
n | month name, 3 letter abbreviation |
p | AM or PM |
p | am or pm |
s | seconds |
W | weekday name, spelled out |
w | weekday name, 3-letter abbreviation |
L | newline |
% | % |
Any characters in the format string that are not preceeded by a '%' are included verbatim in the formatted result.
start
A data value indicating where tick marks should be aligned on the axis. The location of axis tick marks is determined by the combination of this "start" value and a "spacing" value; multigraph will draw tick marks (and labels for the tick marks) at locations T + n*S, where T is the "start" value, S is the "spacing" value, for each integer n such that T + n*S is visible in the graph's padding area. The default "start" value is 0.
spacing
A list of values, separated by spaces, giving the possible spacings to be used between tick marks on the axis. These numbers should be sorted in decreasing order. Multigraph will attempt to choose the densest tick spacing possible from amoung these choices that results in labels that do not overlap. The default value for the "spacing" attribute is "10000 5000 2000 1000 500 200 100 50 20 10 5 2 1 0.1 0.01 0.001".
angle
position
anchor
These determine the location and orientation of each tick mark's label relative to the location of the tic mark itself. See Section 4.6.2, “Axis Label Positioning” and Section 4.6.1, “Positioning” for further details.
The second possible form for the
labels
element accepts all of the above attributes except
the spacing
attribute; this form takes a sequence of
label
subelements instead. Each label subelement indicates
one possible spacing for axis tick marks, along with other settings to be used
when that spacing is chosen. Specifically, the label
subelement
accepts the following attributes:
format
start
spacing
angle
position
anchor
In the context of a label
element, these attributes have the same
meaning and form as for the labels
element, except that the "spacing"
attribute should be a single data value rather than a list of values. The values specified
by the attributes of a label
element apply only when the spacing for
that particular element is in effect. The default value for each of these attributes (except
for the "spacing" attribute, which is required), is whatever value would be in effect
for the containing labels
element.
grid
The presence of this element causes Multigraph to draw grid lines
perpendicular to this axis, at the location of each tick mark. The
grid
element takes one optional attribute:
color
A hexadecimal number giving the color to be used for the grid lines. The default is "0xeeeeee", which is very light gray.
If a horizontalaxis
or verticalaxis
element does not contain a
grid
subelement, Multigraph does not
draw grid lines along that axis. Note that
the grid
element only affects the drawing of
grid lines associated with the axis it appears in. If you want
both horizontal and vertical grid lines, be sure to include
a grid
element in both
the horizontalaxis
and verticalaxis
sections of the mugl file.
pan
This element can be used to configure the type of panning that multigraph allows the user to do for this axis. It accepts the following attributes:
allowed
One of the words "yes" or "no"; default is "yes".
min
The minimum data value to ever be displayed for this axis; panning is never allowed to go below this number.
max
The maximum data value to ever be displayed for this axis; panning is never allowed to go above this number.
zoom
This element can be used to configure the type of zooming that multigraph allows the user to do for this axis. It accepts the following attributes:
allowed
One of the words "yes" or "no"; default is "yes".
min
This attribute controls how far "in" the user can zoom on this axis; its value is a distance along the axis, and is the smallest interval that the user will be allowed to zoom in to. For a number type axis, this value is just a number, and multigraph will constrain the zooming so that the range of values displayed along the axis is at least that number. For a datetime type axis, the value should be an interval of time consisting of a number followed by one of the letters 'Y', 'M', 'D', 'H', 'm', or 's', which indicate years, months, days, hours, minutes, or seconds, respectively. For example a value of "6M" will cause multigraph to constrain zooming along the axis so that the range of time displayed along the axis is always at least 6 months. If this attribute is missing, the default behavior is for unconstrained inward zooming.
max
This attribute controls how far "out" the user can zoom on this axis; its value is a distance along the axis, and is the greatest interval that the user will be allowed to zoom out to. For a number type axis, this value is just a number, and multigraph will constrain the zooming so that the range of values displayed along the axis is at most that number. For a datetime type axis, the value should be an interval of time consisting of a number followed by one of the letters 'Y', 'M', 'D', 'H', 'm', or 's', which indicate years, months, days, hours, minutes, or seconds, respectively. For example a value of "10Y" will cause multigraph to constrain zooming along the axis so that the range of time displayed along the axis is always at most 10 years. If this attribute is missing, the default behavior is for unconstrained outward zooming.
anchor
A data value that indicates a location on the axis about which zooming should be centered. Should be either a data value, or the keyword "none". If it is "none", then zooming is centered about the location of the mouse cursor when the user first presses the mouse button to begin dragging. The default is "none".
binding
This element can be used to "bind" two or more axes together with a linear mapping, so that interactive panning and/or zooming causes them to move together. It is typically used to connect axes that represent the same vertical scale with different units, such as celsius and Fahrenheit temperature. It can also be used to connect axes in different graphs that represent the same scale (for example, the horizontal time axis). It requires the following three attributes:
id
The id
attribute should be a name that identifies the binding. It can
be any string, and all axes having binding
elements with the same
id
value will be connected to each other.
min
A "minimum" value for the binding. Axes bound together in a binding will be connected in such a way that their "min" values correspond to each other.
max
A "maximum" value for the binding. Axes bound together in a binding will be connected in such a way that their "max" values correspond to each other.
The min
and max
attributes can be any two
data values on the axis that determine the linear relationship between an axis
and other axes in the same binding. They do not need to correspond to the axis's
own min and max values, and in general they will not.
For example, to bind a celsius temperature axis to a Fahrenheit temperature axis, you could use the binding
<binding id="tempbinding" min="0" max="100"/>
on the celsius axis, and
<binding id="tempbinding" min="32" max="212"/>
on the Fahrenheit axis.