| MultiGraph: Multi-Purpose Interactive Scientific Graphics for Java | ||
|---|---|---|
| Prev | Chapter 4. MultiGraphlet Configuration and Usage | Next |
MultiGraphlet is a general purpose graphing applet for time series data. In order to draw a graph for a particular data element, or set of data elements, it needs to be told some things about how to draw the graph, such as what scale(s) to use on the vertical axes, what element(s) to graph, what line style(s) and color(s) to use, and so on. These things are all part of what is called a "graph specification".
The graph specification is given in an XML format like the following example:
<graph>
<verticalscale>
<name>FTEMP</name>
<title>F</title>
<ymin>0</ymin>
<ymax>100</ymax>
<labelstart>0.0</labelstart>
<labelspacing>1000,500,100,50,10,5,1</labelspacing>
</verticalscale>
<vlabels>
<left>FTEMP</left>
</vlabels>
<element>
<name>temp</name>
<title>Temperature</title>
<graphtype>DOTLINE</graphtype>
<vscale>FTEMP</vscale>
<color>0,0,255</color>
<station_id>0</station_id>
<field>TEMP</field>
</element>
</graph>
This describes a graph of temperature in degrees Fahrenheit; the left vertical axis is labeled with the heading "F" at the top of the axis, and the vertical scale starts with 0 degrees at the bottom and ends with 100 degrees at the top. The graph is in the "DOTLINE" style (dots at each data point, connected by lines in between), in the color blue (0,0,255).
In general a graph description begins with <graph> and ends with </graph>. In between, there are one or more "verticalscale" sections, followed by a "vlabels" section, followed one or more "elements" section.
A "verticalscale" section specifies a vertical scale, which is a coordinate system for the vertical axis of the graph. There must be one or more of these. Each "verticalscale" section must have one of each of the following XML tags:
| name |
A short name that MultiGraphlet uses to identify this vertical scale. This name is what you refer to in the "element" sections further down to specify which vertical scale an element should be plotted with. The user does not see this name; it is only used internally inside the graph description. |
| title |
A short phrase that MultiGraphlet uses as a heading at the top of the vertical axis, to indicate the units for the axis. |
| ymin |
The value for the lower end of the axis, level with the horizontal (time) axis. This value can change if the user stretches or moves the vertical scale; the ymin value specified here gives the initial value, which is the way the graph is drawn when MultiGraphlet first appears. |
| ymax |
The value for the upper end of the axis, level with the top of the vertical axis. This value can change if the user stretches or moves the vertical scale; the ymax value specified here gives the initial value, which is the way the graph is drawn when MultiGraphlet first appears. |
| labelstart |
MultiGraphlet draws text labels next to certain key values on the vertical axis; "labelstart" specifies the value where these labels should start. Often this is the same as ymin. |
| labelspacing |
This is a list of numbers that MultiGraphlet uses in its algorithm for placing vertical text labels in such a way that they don't overlap each other as the user stretches or shrinks the vertical scale. Each of these numbers is a distance, in the scale of this vertical axis. MultiGraphlet will draw the vertical labels spaced at one of these distances from each other; it chooses the one that causes the labels to be as close as possible to a certain desirable pixel distance (50 pixels) apart from each other on the screen. For example, if the "labelspacing" list is "1000,500,100,50,10,5,1", then MultiGraph will draw vertical text labels every 1000 units, or every 500 units, or every 100 units, or every 50 units, or every 10 units, or every 5 units, or every 1 unit apart, choosing the one that causes the labels to be as close as possible to 50 pixels apart on the screen. |
The "vlabels" section tells MultiGraph which vertical scale to display on the left vertical axis, and which one to display on the right vertical axis. The XML tags "left" and "right" should contain the "name" of one of the vertical scales described in the "verticalscales" section, and The "right" one is optional.
Note that although there can be any number of vertical scales in a graph, only two of them can appear as labels on the vertical axes. The other ones can be used for plotting elements, but there will be no labels for them on the graph. This may be changed in a future version.
An "element" section specifies a data element to be plotted. There must be one or more of these. Each "element" section must have one of each of the following XML tags:
| name |
A short name that MultiGraphlet uses internally to identify this element. The user does not see this name; it is only used internally. |
| title |
A word or short phrase that MultiGraphlet uses in the graph legend at the top of the window to describe this element. |
| graphtype |
A keyword indicating the style to be used in graphing this element. Should be one of the words "DOTLINE" (for dots with lines connecting them), "FILLED" (for a line graph with the area below the lines shaded), or "BAR" (for a bar graph). |
| vscale |
The "name" of one of the vertical scales described in the "verticalscales" section; MultiGraphlet will graph this element using this vertical scale. |
| color |
The color to use for this element, specified as a list of 3 R,G,B values in the range 0-255. |
| station_id |
For now, this should always be 0 (and must be present). It will be able to have other meaninful values in a future version. |
| field |
This should give the name of the data field corresponding to this data element. MultiGraphlet uses this name in constructing URLs for fetching data from the data server. See Section 4.4 for more information. |
Once you have written a graph specification in this XML format, there are two ways to provide that specification to MultiGraphlet. If you have just one or a few graph specifications, you can put each one in its own file in the applet's codebase directory, and specify the URL of that file in the "graph_url" parameter of the MultiGraphlet applet tag.
If you have a large number of graph specifications you can write a "graph server" program that takes a single parameter called "name", and returns a graph specification corresponding to that name. You then give the URL to that program in the "graph_url" applet parameter, and the name of the particular graph you want to invoke in the "config" parameter. MultiGraphlet will fetch the graph specification via an http request.
See Section 4.5 for more details on the applet parameters.