4.3. Axes

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.

Figure 4.2. Horizontal Axis Specifications

Horizontal Axis Specifications

Figure 4.3. Vertical Axis Specifications

Vertical Axis Specifications

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 '%':

CharacterExpansion
Yfour digit year
ytwo digit year
dday of month without leading zero
D2-digit day of month with leading zero
hhour of day, 12 hour clock
Hhour of day, 24 hour clock
iminutes
mmonth number without leading zero
M2-digit month number with leading zero
Nmonth name, spelled out
nmonth name, 3 letter abbreviation
pAM or PM
pam or pm
sseconds
Wweekday name, spelled out
wweekday name, 3-letter abbreviation
Lnewline
%%

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.