The data
element in the mugl file specifies
the data to be plotted, either
by listing the data itself in the mugl file, or by describing where
multigraph can find the data. The data
element is
the only element that is absolutely required in a
mugl file. (Multigraph can make reasonable default decisions about
everything else, but it has to be given some data to graph!)
There are three ways that you can specify the data. The simplest is to include the data directly in the mugl file, in a list of commma-separated values. The second way is for the mugl file to refer to data that is contained in a separate comma-separated value (csv) file. The third way is for the data to be provided via a web service, in which case the mugl file indicates the address of that service, and multigraph will use the service to fetch the data as needed.
Regardless of which of the above forms the data is in, it is helpful to think of the data as consisting of a table of values, where each column in the table corresponds to a particular variable, and each row corresponds to a set of values for those variables. For example, a data set containing temperature and precipitation values measured every hour for one day might correspond to a table with 3 columns and 24 rows: one column each for the time of measurement, temperature, and precipitation, and one row for each of the 24 hours in the day.
A mugl file's data
element should
begin with a variables
subelement that indicates
some basic information about the columns in this "table" of data.
The variables
element contains a sequence of variable
subelements, each of
which has the following attributes that give information about a data variable:
id
An identifier to be used to refer to this variable elsewhere in the mugl file. The default is "x" for the first variable, "y" for the second variable, and "y1", "y2", ... for any additional variables.
column
A number indicating which "column" the variable is in. The default is 0 for the first variable, 1 for the second, and so on.
type
The data type of the variable. Should be either 'number' or 'datetime'; the default is 'number'.
After the variables
subelement in the
data
section, exactly one of the following three subelements should
occur:
values
The values
subelement should be used when the data
is to be included directly in the mugl file. The data should appear
between the <values> and </values> tags, with one set of
values per line, and individual values on each line separated by
commas.
csv
The csv
subelement should be used when the data is
in a separate comma-separated values file. The csv
subelement has a single attribute named location
,
whose value should be the name of the csv file.
service
The service
subelement indicates that multigraph should
fetch data from a REST web service. It has one attriubute named
location
which should give the address of the web service.
Because of JavaScript security restrictions, this address must be on the same
server where the HTML page containing the graph is. The value of the
location
attribute should be either a root-relative (i.e., starting with '/')
path, or a relative path that is relative to the location of the HTML file. In particular,
the REST service URL should not include the "http://" prefix or the server name.
Sometimes there is a need to treat certain data values as "missing", which will affect the way that Multigraph plots those values. For example, when drawing a plot that involes lines connecting consecutive data points, Multigraph will leave a gap at locations corresponding to missing data points.
Information about missing data values may be specified in the
variables
subsection of the data
element.
The
variables
tag takes an optional pair of attributes:
missingvalue
, which indicates a value to considered
as missing, and missingop
, which indicates a test
to be used to determine whether a given value is missing. The
missingop
attribute should be one of the strings
"lt", "le", "eq", "ge", or "gt", which stand for "less than", "less
than or equal", "equal", "greater than or equal", and "greater than",
respectively. The value of missingop
determines
the operation to be used in determining whether a data value should
be considered missing: the data value is compared, using the
missingop
operation, to the
missingvalue
value. For example, if
missingop
is "le" and
missingvalue
is "-9000", then any data values
less than or equal to -9000 will be considered missing.
The default for missingop
is "eq", so the default
test is for exact equality.
There is no default for missingvalue
; if it is not
specified, then no data values will be considered missing.
The variable
tag also accepts the
missingop
and missingvalue
attributes, in which case they apply only to
an individual variable. Values for missingop
and
missingvalue
given for an individual variable
element override any that are specified for the enclosing
variables
element. So you can specify
missingop
and missingvalue
either for each variable
individually,
or globally at the variables
level, in which case
any individual variable
tags that do not
have their own missingop
and missingvalue
settings will inherit the values from the inclosing
variables
settings.