This is an interactive MUGL file which is annotated with comments documenting every element and attribute in the MUGL specification. Click on an element to expand it; hover over an attribute to see more documentation for it. You can download this entire annotated MUGL file, as a valid XML document, here: annotated-mugl.xml. Note that although this file is a valid XML document, and it conveys the structure of MUGL by example, it is not actually a valid MUGL file; don't try loading this file into Multigraph. It is intended for documentation of the MUGL specification only. A formal XSD document that defines the MUGL specification is also available.
<mugl>
+<window.../> -<window
width="INTEGER"
height="INTEGER"
border="INTEGER(2)"
bordercolor="COLOR(black)"
margin="INTEGER(2)"
padding="INTEGER(5)">
<!--| The <window> element specifies the following things related to the graph's
| margin, border, and padding area. The <window> element is optional and
| can appear at most once in the MUGL file.
|
| width: width of the graph, in pixels
| height: height of the graph, in pixels
| The width and height attributes are
| usually are omitted, in which case they default to the size
| specified when the graph is created, either with the
| "data-width" and "data-height" attributes if the graph is
| created using HTML5 markup, or with CSS attributes on the
| div element that contains the graph, or with options passed
| to the Multigraph constructor in JavaScript code.
| border: thickness, in pixels, of the border to draw around the graph.
| A value of 0 causes no border to be drawn.
| bordercolor: color to use for the border.
| margin: amount of margin to leave outside all four sides of the border.
| padding: amount of padding to leave inside all four sides of the border
|-->
</window>
+<legend.../> -<legend
visible="BOOLEAN"
base="POINT(1,1)"
anchor="POINT(1,1)"
position="POINT(0,0)"
frame="FRAME(padding)"
color="COLOR(white)"
opacity="DOUBLE(1.0)"
border="INTEGER(1)"
bordercolor="COLOR(black)"
rows="INTEGER"
columns="INTEGER"
cornerradius="INTEGER(0)"
padding="INTEGER(0)">
<!--| The <legend> element controls whether and how Multigraph creates a legend
| for the graph. The <legend> element is optional and
| can appear at most once in the MUGL file.
|
| visible: whether the legend should be drawn or not; the default is "false"
| if there is only one plot in the graph, and "true" if there are more
| than one plot
| base, anchor, position, frame: specify the location of the legend in the
| graph
| color: color of the legend background
| opacity: opacity of the legend background; a value of 0 causes no
| background to be drawn behind the legend. This opacity value only
| affects the legend background; it does not affect the text or icons
| inside the legend
| border: thickness, in pixels, of the border drawn around the legend; a
| value of 0 causes no border to be drawn
| bordercolor: color of border around the legend
| rows, columns: the legend is layed out in a grid, with an icon and text
| label corresponding to a single plot in each grid cell. These attributes
| determine how many rows and/or columns are in the grid.
| If neither rows nor columns is specified, columns defaults to 1,
| and there will be one row for each plots
| in the graph. If only one of rows/columns is specified, the other
| will be computed to be whatever it needs to be so that rows X columns
| is greater than or equal to the number of plots. If both rows and columns
| are specified, the legend is layed out in a grid of that size.
| cornerradius: the radius, in pixels, of rounding to apply to the corners of
| the legend box
| padding: an amount of space, in pixels, to leave inside the border of the legend
|-->
+<icon.../> -<icon
width="INTEGER(40)"
height="INTEGER(30)"
border="INTEGER(1)">
<!--|
| The <icon> subelement of <legend> controls the shape and appearance of the
| little icons that Mulitgraph draws for each plot in the legend. This subelement
| is optional and may appear at most once inside the <legend> element.
|
| width: the width, in pixels, of the icon
| height: the height, in pixels, of the icon
| horder: the thickness, in pixels, of the border to be drawn around each
| plot icon
|-->
</icon>
</legend>
+<background.../> -<background
color="COLOR(white)">
<!--| The <background> element controls how Multigraph draws the graph's background
| (the area inside the border). The <background> element is optional and can
| appear at most once in the MUGL file.
|
| color: a solid color to fill the background with
|-->
+<img.../> -<img
src="STRING!"
anchor="POINT(-1,-1)"
base="POINT(-1,-1)"
position="POINT(0,0)"
frame="FRAME(padding)">
<!--| The <img> subelement of <background> specifies an image to draw in
| the background. This subelement is optional and can appear at most
| once. If it is present, the image is drawn after the background is
| filled with the background color, but before anything else is drawn,
| so the image will appear underneath everything.
|
| src: the URL of the image to be drawn. If this is a relative
| URL, it is interpreted relative to the URL of the MUGL file.
| anchor, base, position, frame: specify the positioning
| of the image
|-->
</img>
</background>
+<plotarea.../> -<plotarea
marginbottom="INTEGER(35)"
marginleft="INTEGER(38)"
margintop="INTEGER(10)"
marginright="INTEGER(35)"
border="INTEGER(0)"
bordercolor="COLOR(0xeeeeee)"
color="COLOR">
<!--| The <plotarea> element specifies the size and appearance of the plot area. The
| element is optional and can appear at most once in the MUGL file.
|
| marginbottom, marginleft, margintop, marginright: these attributes give the
| margin amounts for the plot area, in pixels
| border: the thickness, in pixels, of a border to draw around the plot area; a
| value of 0 means that no border is drawn
| bordercolor: the color to use for the border
| color: a color to fill the background of the plot area with. If the attribute is
| present, the plot area is filled with this color after any background color
| and/or background image from the <background> element are drawn. The default
| behavior, if this attribute is not specified, is that no fill is applied
| to the plot area, so that whatever color and/or image was drawn for the
| <background> element shows through.
|-->
</plotarea>
+<title.../> -<title
base="POINT(0,1)"
anchor="POINT(0,1)"
position="POINT(0,0)"
frame="FRAME(padding)"
color="COLOR(white)"
opacity="DOUBLE(1.0)"
border="INTEGER(0)"
bordercolor="COLOR(black)"
padding="INTEGER(0)"
cornerradius="INTEGER(15)"
fontsize="INTEGER">
<!--| The <title> element indicates a title to be displayed in the graph. If the <title>
| element is not present, no title is drawn. If it is present, the text of the element
| indicates the text of the title.
|
| NOTE: at the time of this writing, the title element is not fully implemented in
| Multigraph 4.0. A better way to implement a graph title is to do it outside
| of Multigraph: create a <div> element outside of the Multigraph <div>, and use
| CSS to style and position it as desired. (You can even position it to appear
| as though it's inside the graph, by using relative or absolute positioning.)
|
| anchor, base, position, frame: specify the position of the title
| color: color of the background rectangle to be drawn behind the title
| opacity: opacity of the title background
| border: thickness, in pixels, of the border drawn around the title; a
| value of 0 causes no border to be drawn
| bordercolor: color of border around the title
| padding: an amount of space, in pixels, to leave inside the border of the title
| cornerradius: the radius, in pixels, of rounding to apply to the corners of
| the title box
| fontsize: the size of the font to use for the title
|-->
</title>
+<horizontalaxis.../> -<horizontalaxis
id="STRING"
type="DATATYPE(number)"
length="RELLEN(1.0)"
base="POINT(-1,1)"
anchor="DOUBLE(-1)"
position="POINT(0,0)"
min="DATAVALUEORAUTO(auto)"
max="DATAVALUEORAUTO(auto)"
minposition="RELPOS(-1.0)"
maxposition="RELPOS(1.0)"
color="COLOR(black)"
linewidth="INTEGER(1)"
tickmin="INTEGER(-3)"
tickmax="INTEGER(3)"
tickcolor="COLOR(black)">
<!--| The <horizontalaxis> and <verticalaxis> elements specify axes for the graph.
| Every graph has at least one horizontal axis and at least one vertical axis,
| but the <horizontalaxis> and <verticalaxis> elements are optional in the MUGL
| file; if either is absent, an axis of that orientation with all the default
| values is implied.
|
| id: the id of the axis. If this attribute is missing, an id of "x" is used for
| the first horizontal axis, "x1" for the second, and so on. For vertical axes,
| the default ids are "y", "y1", etc.
| type: the data type of the axis
| length: the length of the axis, as a RELLEN representing a fraction of the width
| (or height, for a vertical axis) of the plot area, plus or minus a pixel offset.
| base: a POINT in the range (-1,-1) to (1,1) giving the location in the plot area
| of the base point for the axis's location
| position: a POINT value giving the position offset for the location of the axis,
| relative to the base point
| anchor: a single number in the range [-1,1] indicating the location of the
| anchor point along the axis. -1 corresponds to the left endpoint, and 1
| corresponds to the right endpoint.
| min: the minimum data value for the axis; this is typically the value associated
| with the left endpoint of the axis, but see "minposition" below.
| max: the maximum data value for the axis; this is typically the value associated
| with the right endpoint of the axis, but see "maxposition" below.
| minposition: the location on the axis that corresponds to the minimum data value,
| as a RELPOS.
| maxposition: the location on the axis that corresponds to the maximum data value,
| as a RELPOS.
| color: the color of the line to draw for the axis
| linewidth: the pixel thickness of the line to draw for the axis
| tickmin: the length, in pixels, of the part of the axis tick marks that extends below
| the axis
| tickmax: the length, in pixels, of the part of the axis tick marks that extends above
| the axis
| tickcolor: the color to use when drawing the axis tick marks
|-->
+<labels.../> -<labels
format="STRING"
start="DATAVALUE(0)"
angle="DOUBLE(0)"
position="POINT"
anchor="POINT"
color="COLOR(black)"
spacing="STRING"
densityfactor="DOUBLE(1.0)">
<!--| The <labels> subelement of the axis elements indicates how and where tick marks
| and labels should be drawn along the axis.
|
| format: the format string to use for the labels; defaults to "%.1f" for number
| axes, and to "%Y-%M-%D %H:%i" for datetime axes
| start: a data value that indicates how the tickmarks and labels should be aligned
| along the axis. The alignment will be chosen so that a tick mark would be drawn
| at the location specified by the start value. Note that this does not necessarily
| mean that labeling will actually start at this value; labeling will start at whatever
| multiple of the chosen spacing, aligned at the start value, occurs at or after the
| left endpoint of the axis. In future versions of MUGL this attribute might be better
| renamed to "align".
| position, anchor, angle: specifies the position of the label associated with each tick
| mark. The "base" value for each label's positioning is the point along the axis
| corresonding to the value being labeled (i.e. the location of the tick mark along the axis).
| The default value for the angle is 0; the default values for the position and anchor depend
| on the orientation and location of the axis:
|
| bottom half, or left top half, or right
| half, of plot area half, of plot area
|
| horizontal position: (0,-5) position: (0, 5)
| anchor: (0,1) anchor: (0, -1)
|
| vertical position: (-8, 0) position: (5, 0)
| anchor: (1, 0) anchor: (-1, 0)
|
| color: the color to use when drawing labels
| spacing: a space-separated list of spacings, where each spacing is a DATAMEASURE. Multigraph will
| choose from among these spacings when deciding how many labels to draw; it will chose the
| spacing that results in the "optimal" density of labels along the axis. The default for number
| axes is
| "10000 5000 2000 1000 500 200 100 50 20 10 5 2 1 0.1 0.01 0.001"
| and the default for datetime axes is
| "1000Y 500Y 200Y 100Y 50Y 20Y 10Y 5Y 2Y 1Y 6M 3M 2M 1M 7D 3D 2D 1D 12H 6H 3H 2H 1H"
| densityfactor: this is a factor that can be used to tweak Multigraph's concept what what
| constitutes an "optimal" density of labels along the axis. It should be a positive number;
| Values greater than one result in more labels, and values less than one result in fewer
| labels. Note that this attribute is not yet fully implemented in Multigraph 4.0.
|
|-->
+<label.../> -<label
format="STRING"
start="STRING"
angle="DOUBLE"
position="POINT"
anchor="POINT"
spacing="STRING"
densityfactor="DOUBLE">
<!--| The <labels> element may contain one or more <label> subelements.
|
| If no <label> subelements are present, the labeling rules for the axis are determined by
| the attributes of the <labels> element (or their default values, for any that are not specified).
|
| If there are any <label> subelements, each one specifies an addiontal list of spacings,
| possibly with custom values of other attributes to go with those spacings. Each <label>
| subelement must have a "spacing" attribute, and may optionally also include values for any
| of the other attributes allowed for the <labels> tag. Any attributes not specified with a
| a <label> subelement inherit their values from the corresponding attribute on the enclosing
| <labels> tag, or the default value.
|-->
</label>
</labels>
+<title.../> -<title
base="DOUBLE(0)"
anchor="POINT"
position="POINT"
angle="DOUBLE(0)">
<!--| The <title> subelement of the axis elements gives a title to display with the axis. The text
| of the element gives the title text. If the element is missing, the id of the axis is used
| as the title text. To prevent a title from being displayed at all, include an empty <title/>
| element.
|
| base: the base point of the title's position; this is a number between -1 and 1, and
| indicates a point along the axis
| angle: the angle, in degrees, of the title text; the default is 0 which means horizontal
| position, anchor: these positioning values have the following defaults, depending on
| whether the axis is horizontal or vertical, and on which half of the plot area it
| is positioned in:
|
| bottom half, or left top half, or right
| half, of plot area half, of plot area
|
| horizontal position: (0, -18) position: (0, 15)
| anchor: (0, 1) anchor: (0, -1)
|
| vertical position: (-25, 0) position: (33, 0)
| anchor: (1, 0) anchor: (-1, 0)
|-->
</title>
+<grid.../> -<grid
color="COLOR(0xeeeeee)"
visible="BOOLEAN(false)">
<!--| The <grid> subelement of the axis elements can be used to cause Multigraph to draw a "grid" in the background
| of the plot area, with grid lines at the locations of the tick marks along the axes. The <grid> subelement
| of an axis element controls the grid lines corresponding to tick marks on that axis.
|
| visible: indicates whether grid lines should be drawn for this axis
| color: the color to use for this axis's grid lines
|-->
</grid>
+<pan.../> -<pan
allowed="BOOLEAN(yes)"
min="DATAVALUE"
max="DATAVALUE">
<!--| The <pan> subelement of the axis elements can be used to limit possible pan motions allowed in the graph.
|
| allowed: whether panning is allowed at all
| min: panning will be restricted to never go below this value. If the min attribute is not specified,
| panning in the negative direction is unrestricted
| max: panning will be restricted to never go above this value. If the max attribute is not specified,
| panning in the positive direction is unrestricted
|-->
</pan>
+<zoom.../> -<zoom
allowed="BOOLEAN(yes)"
min="DATAMEASURE"
max="DATAMEASURE"
anchor="DATAVALUE">
<!--| The <zoom> subelement of the axis elements can be used to limit possible zoom motions allowed in the graph.
|
| allowed: whether zooming is allowed at all
| min: restricts how far "in" the user can zoom along this axis; if this attribute is present, Multigraph
| will restrict zooming along this axis so that the length of the axis, measured in the data units
| of the axis, is always greater than or equal to this "min" value. If this attribute is not present,
| zooming in is unrestricted.
| max: restricts how far "out" the user can zoom along this axis; if this attribute is present, Multigraph
| will restrict zooming along this axis so that the length of the axis, measured in the data units
| of the axis, is always less than or equal to this "min" value. If this attribute is not present,
| zooming out is unrestricted.
| anchor: indicates a fixed point about which zooming should always occur. If this attribute is not
| present, zooming occurs about the point on the axis closest to the location of the mouse cursor.
| (Note that in this case, the "anchor" attribute is not related to positioning, in contract to
| other "anchor" attributes elsewhere in the MUGL specification.)
|-->
</zoom>
+<binding.../> -<binding
id="STRING!"
min="DATAVALUE!"
max="DATAVALUE!">
<!--| The <binding> subelement of the axis elements can be used to "bind" multiple axes together.
| Each "binding" has a unique "id" attribute, which can be any string and which serves to identify
| that binding. When any one axis associated with a particular binding changes scale due to panning
| or zooming, the other axes associated with that binding change their scales to match.
|
| id: the id of the binding
| min, max: the two data points that indicate how this axis takes part in the binding; this
| axis will be scaled so that its min/max values will be tied to the min/max values of the other
| axes in the same binding.
|
| Example: a pair of fahrenheit/celsius temperature axes can be created as follows:
|
| <verticalaxis id="fahrenheit" min="15" max="90">
| <binding id="tempbinding" min="32" max="212"/>
| </verticalaxis>
| <verticalaxis id="celsius">
| <binding id="tempbinding" min="0" max="100"/>
| </verticalaxis>
|
| Note that the min/max attribute values for the binding are completely different from the min/max attributes
| on the axes themselves. The min/max values for the binding indicate the linear relationship between the data
| values of the axes. The min/max values for the axes themselves indicate the initial scale that should be
| displayed along the axis. Note also that there is a potential conflict between the min/max axis attribute
| settings of the axes that participate in a binding, because the scale of the axis is indicatd both by
| that axis's min/max attributes, and by the linear relationship enforced by its binding. For this reason, it's
| best to only give min/max attributes values for ONE of the axis in a binding, as is the case for the fahrenheit
| axis in the example above. In a situation where min/max axis values are specified for more than one axis
| in a binding, Multigraph will favor enforcing the binding, by choosing the min/max values from one of the
| axes in the binding that specifies them, and adjusting the min/max values of the other axes in the binding
| accordingly.
|
|-->
</binding>
</horizontalaxis>
+<verticalaxis.../> -<verticalaxis>
<!--| The <verticalaxis> element indicates a vertical axis; its syntax is exactly the same
| as for the <horizontalaxis> element. See the documentation for <horizontalaxis> above
| for details.
|-->
</verticalaxis>
+<plot.../> -<plot>
<!--| Each <plot> element in a MUGL file corresponds to one collection of variables from
| a <data> section plotted against a specified pair of axes (one horizontal and one vertical),
| using a specified plot style. A MUGL file can have any number of <plot> elements; if
| no <plot> elements are present, a single plot is inferred, with all the default settings.
|-->
+<legend.../> -<legend
visible="BOOLEAN"
label="STRING">
<!--| The <plot> element may contain an optional <legend> element that controls that plot's
| entry in the graph's legend. Note that the graph's legend must be configured to be
| visible in the first place in order for these plot-specific settings to have any effect;
| see the top-level <legend> element for details on this.
|
| visible: whether this plot has an entry in the legend
| label: the label to use for this plot's entry in the legend; by default, the id
| of the plot's second variable is used
|-->
</legend>
+<horizontalaxis.../> -<horizontalaxis
ref="STRING!">
<!--| The <horizontalaxis> subelement indicates which horizontal axis this plot should use.
| If the plot does not contain a <horizontalaxis> subelement, it is assumed to use the
| first <horizontalaxis> in the MUGL file.
|
| ref: the id of a horizontal axis; this value must match the id attribute
| of a top-level <horizontalaxis> element in the MUGL file
|-->
+<variable.../> -<variable
ref="STRING!">
<!--| The <variable> subelement of the plot's <horizontalaxis> element indicates which variable
| should be plotted relative to the plot's horizontal axis. If there is no <variable> subelement,
| the first variable in the MUGL file's first <data> section is assumed.
|
| ref: the id of a variable from one of this MUGL file's <data> sections
|-->
</variable>
</horizontalaxis>
+<verticalaxis.../> -<verticalaxis
ref="STRING!">
<!--| The <verticalaxis> subelement indicates which vertical axis this plot should use.
| If the plot does not contain a <verticalaxis> subelement, it is assumed to use the
| first <verticalaxis> in the MUGL file.
|
| ref: the id of a vertical axis; this value must match the id attribute
| of a top-level <verticalaxis> element in the MUGL file
|-->
+<variable.../> -<variable
ref="STRING">
<!--| The <variable> subelement of the plot's <verticalaxis> element indicates which variable(s)
| should be plotted relative to the plot's vertical axis. A plot's <verticalaxis> element may
| contain any number of <variable> subelements. If there is no <variable> subelement, the
| second variable in the MUGL file's first <data> section is assumed.
|
| ref: the id of a variable from one of this MUGL file's <data> sections
|
| NOTE: all of the variables mentioned in a plot, whether in the <horizontalaxis> or <verticalaxis>
| subelements, must come from the same <data> section in the MUGL file.
|-->
</variable>
+<constant.../> -<constant
value="DATAVALUE">
<!--| The <constant> subelement of the plot's <verticalaxis> subelement is used to indicate a constant
| plot. If the <constant> subelement is present, no <variable> subelements may be present, and the plot
| will consist of a constant value extending across the entire plot area.
|
| value: the height at which the constant value should be plotted
|-->
</constant>
</verticalaxis>
+<renderer.../> -<renderer
type="RENDERERTYPE(line)">
<!--| The <renderer> element indicates the renderer, or plot style, that Multigraph should use to draw
| this plot. A <plot> element can have at most one <renderer> subelement. If no <renderer> subelement
| is present, a renderer of type "line", with the default options, is assumed.
|
| type: the name of the renderer to use
|-->
+<option.../> -<option
name="STRING!"
value="STRING!"
min="DATAVALUE"
max="DATAVALUE">
<!--| A <renderer> element can have any number of <option> subelements which customize the appearance
| of the plot. Associated with each <option> subelement is the name of an option (the "name" attribute),
| a value for that option (the "value" attribute), and optionally, an "applicability range" of data
| values for which that value should be used. The applicability range is indicated by the "min" and
| "max" attributes. If the "min" attribute is present, it specifies a lower endpoint for the applicability
| range, and analogously, the "max" attribute specifies an upper endpoint. If either of these attributes
| is omitted, the applicability range is unlimited in the corresponding direction.
|
| For example:
|
| <option name="color" value="blue" max="0">
|
| would cause data points less than 0 to be plotted in blue,
|
| <option name="color" value="green" min="0" min="10">
|
| would cause data points between 0 and 10 to be plotted in green,
|
| <option name="color" value="red" min="10">
|
| would cause data points greater than 10 to be plotted in red, and
|
| <option name="color" value="cyan">
|
| would cause all data points, regardless of their value, to be plotted
| in cyan.
|
| name: the name of the option
| value: the value of the option
| min: minimum data value for this option setting
| max: maximum data value for this option setting
|-->
</option>
</renderer>
+<datatips.../> -<datatips
format="STRING!"
bgcolor="COLOR"
bgalpha="DOUBLE"
border="INTEGER"
bordercolor="COLOR"
pad="INTEGER">
<!--| NOTE: the <datatips> element is not yet implemented in Multigraph 4.0.
|
| The <datatips> subelement of the <plot> element tells Multigraph to display "tooltip"-style popups
| as the user moves the mouse over individual data points, and indicates the format to use for those
| popups. The <datatips> subelement is optional, and if it is omitted, no datatips are displayed.
|
| format: a string that gives the text to be displayed in each datatip popup. Within
| this string, expressions of the form {0}, {1}, etc will be replaced with the values of the
| corresponding variable from the plot (with {0} being the first variable, {1} the second, and
| so on).
| bgcolor: the color to use for the background color of the datatip
| bgalpha: the alpha (transparency) value to use for the background of the datatip
| border: the thickness of a border to draw around the outline of the tooptip rectangle
| bordercolor: the color to use for the border
| pad: an amount (pixels) of space to leave around the text
|
|-->
+<variable.../> -<variable
format="STRING!">
<!--| Each <variable> subelement of the <datatips> element indicates a format string to be used
| when formatting the values of a variable to be used in constructing the datatip.
|
| format: the format string to be used for the variable
|
| For example, imagine a plot in which the first variable is of type datetime, and the second
| variable is of type number. Then
|
| <datatips format="{0}: {1}">
| <variable format="%d %n %Y"/>
| <variable format="%.2f"/>
| </datatips>
|
| would create datatips in which the first variable, {0}, would be formatted according to
| the format string "%d %n %Y", and the second variable, {1}, would be formatted according
| to the string "%.2f". So, for example, the data value ("20121203", "13.1") would be formatted
| as "3 Dec 2012: 13.1".
|-->
</variable>
</datatips>
</plot>
+<data.../> -<data>
<!--| A MUGL file should contain one or more <data> elements. Each <data> element provides a source
| of data that is available to be plotted in the graph. The data for each <data>
| element can be thought of as a collection of data points, where each point
| is an ordered sequence of N values. Within the same <data> element, all data points
| must contain the same number of values - i.e. the value of N must be the same for
| every point in the data source.
|
| Sometimes the N values that each point in a data source contains are called "columns",
| and the data points themselves are called "rows".
|
| Each column has a data type, either "number" or "datetime", associatd with it,
| and the value of that column is assumed to be of that type for every row.
|
| There are three different types of <data> elements:
|
| * <data> elements that include their data directly in the MUGL file in a <values> subelement
| * <data> elements that refer to data in an external file via a <csv> subelement
| * <data> elements that instruct Multigraph to pull data dynamically
| from a RESTful web service via a <service> subelement
|
| Each <data> element should have exactly one of these three subelements; it is an error
| for a <data> element to contain more than one of these. Note that a MUGL file can contain
| a unlimited number of <data> elements, though, and these <data> elements do not need to
| be of the same type.
|-->
+<variables.../> -<variables
missingvalue="DATAVALUE"
missingop="COMPARATOR">
<!--| The <variables> subelement provides information about the variables, or columns, that
| this data source contains.
|
| missingvalue: a DATAVALUE that Multigraph should use in checking for missing
| values for a variable. This attribute is optional. If it is present,
| it is used as the default missingvalue for any <variable> subelments
| in this <variables> element that do no explicity include their own
| value for the missingvalue attribute. The default is that there is
| no missingvalue, which means that <variable> subelements that do not
| explicitly set one do not inherit a value for it.
| missingop: a COMPARATOR (one of the strings 'lt', 'le', 'eq', 'ge', or 'gt')
| that indicates the operation that should be used to compare each data
| value to the specified missingvalue to determine whether it should be
| taken to be a missing value. The default is 'eq', so that values are
| considered missing if they are equal to the specified missingvalue, but
| note that no values are considered missing unless a value is specified
| for the missingvalue attribute.
|-->
+<variable.../> -<variable
id="STRING!"
column="INTEGER"
type="DATATYPE(number)"
missingvalue="STRING"
missingop="COMPARATOR">
<!--| The <variable> subelement provides information about one column of data for
| this data source.
|
| id: the id to assign to this column; this id is used by the ref attribute
| in the <plot> element's axis <variable> element. The id attribute
| is required for the <variable> element, but if one or more columns of
| the data source have no <variable> element present, Multigraph uses
| the default id values of "x", "y", "y1", "y2", ..., in that order.
| column: an integer indicating the column number that this <variable> element
| describes. Columns are numbered starting with 0. The default value
| for the column attribute depends on the order of the group of <variable>
| elements in an enclosing <variables> element; <variable> elements with no
| column attribute are assigned values, in order of appearance, from
| the set of column numbers not specifically indicated by other <variable>
| elements in the group.
| type: the DATATYPE of the column
| missingvalue, missingop: these attributes have the same meaning and type
| as for the <variables> element, but they apply only to this particular
| <variable> element. If either of these attributes is not specified
| for this <variable> element, its value is inherited from the
| value of the same attribute on the enclosing <variables> tag, if there
| is one there.
|-->
</variable>
</variables>
+<values.../> -<values>
<!--| The <values> subelement allows data value to be specified directly in the MUGL
| file. This element takes no attributs, and its text value should be a newline-separated
| list of data values, with each line consisting of N comma-separated values.
|-->
</values>
+<csv.../> -<csv
location="STRING!">
<!--| The <csv> subelement indicates a data source coming from an external CSV file.
| The CSV file should contain a newline-separated list of data values, with each
| line consisting of N comma-separated values.
|
| location: the URL of the CSV file containing the data. If this URL is relative,
| it is interpreted to be relative to the location of the MUGL file.
|-->
</csv>
+<service.../> -<service
location="STRING!"
format="STRING">
<!--| The <service> subelement indicates a data source corresponding to a RESTful web service;
| Multigraph will fetch ranges of data from the web service as needed, as the user pans/zooms
| around in the graph.
|
| There are two possible forms that the URL for the web service can take:
| 1. The URL is a string containing the substrings "$min" and "$max"
| 2. The URL is a string that does NOT contain the substrings "$min" and "$max"
| In the first case, Multigraph forms URLs for data requests by replacing "$min"
| and "$max" with the minimum and maximum values of the data source's first
| variable for the requested range. In the second case, Multigraph internally
| appends the expression "$min,$max" to the given URL, and then forms request URLs
| as described for the first case.
|
| location: the service URL.
| format: a format string to be used in formatting the data values that will be
| substituted for $min and $max in constructing request URLs as described above.
| The default, if the format attribute is not specified, is "%f" if the first column
| of the data source is of type number, or "%Y%M%D%H%i%s" if it is of type datetime.
|-->
</service>
</data>
+<throttle.../> -<throttle
pattern="STRING()"
requests="INTEGER(0)"
period="INTEGER(0)"
concurrent="INTEGER(0)">
<!--| The <throttle> element allows Multigraph to enforce constraints on the rate at which
| it initiates requests to fetch data for <csv> and/or <service> data sources. A MUGL
| file can contain any number of <throttle> elements; each one specifies a regular
| expression pattern, and a set of constraint values. Multigraph enforces that set of
| constraints to all URLs it fetches that match the regular expression. If there are
| multiple <throttle> elements, Multigraph will choose the constraints in the first
| <throttle> element in the file whose pattern matches the fetched URL.
|
| If there are no <throttle> elements in a MUGL file, Multigraph will do no throttling.
|
| A <throttle> element with an empty pattern, or missing pattern attribute, will match
| any URL, so its constraints will be applied to every outgoing request, unless there
| is another <throttle> element before it with a pattern that also matches the request URL.
|
| The test for whether a request URL matches a <throttle> pattern is done on the
| original "location" value for the <csv> or <service> element. For <service> elements,
| this is before any range values are inserted into the URL, and in both cases,
| the pattern is checked before a relative URL is rewritten to be relative to the
| location of the MUGL file.
|
| Throttling only applies to data fetched via a <csv> or <service> data source; it
| does not apply to any images retrieved by the <background> <img> element.
|
| pattern: the regular expression (JavaScript syntax) for URLs that this
| element's constraints should be applied to. This regular expression should
| *not* include delimiting '/' marks.
| requests: an integer N
| period: an integer P
| concurrent: an integer M
|
| Requests whose URL matches the pattern will be limited in such a way that
|
| * No more than N requests are initiated within P milliseconds of each other, AND
| * No more than M concurrent (outstanding at the same time) requests are allowed
|
| If N or P is 0, there is no time period based constraint, and if M is 0, there
| is no constraint on the number of concurrent requests.
|
| The default is N=P=M=0, so a <throttle> element that doesn't specify any of
| requests, period, or concurrent will have no effect.
|-->
</throttle>
</mugl>