4.5. Data

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.

4.5.1. Missing Data

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.