XML How To

Introduction

XML is a general purpose tag language developed by the web consortium (W3C). The syntax of XML is very similar to HTML, except that unlike HTML, XML does not define a priori any specific tags. Instead it is up to users of XML within any specific problem domain to develop their own set of tags. HTML can be thought of as a particular set of XML tags for use in the web browser page display domain. XML includes the concept of a DTD, a file which defines a set of tags for a particular problem domain, as well as rules for how tags can be nested and what attributes each tag allows.

We have developed a DTD for storing HEP plots as XML. The DTD supports storing all of the display attributes supported by the JAS plot bean. In addition the DTD supports:

• Storing the data for the plot in the XML itself (either as binned or unbinned data).
• OR storing a reference to the actual data source in the XML.

Storing the data in the XML itself is useful for storing a snapshot of the data. Storing a reference to the data is useful when the goal is to store the style attributes of a plot, but to access the current "live" version of the data.

One advantage of XML is that it is an ASCII format and can, when necessary be edited by hand. The JAS XML has been designed with this capability in mind. In addition we have tried to make the XML format used as generic as possible, in the hopes that it can be used as the basis of a mechanism to exchange plots between different applications in future.

Some Simple XML Examples

Example 1

The first example XML file creates a simple 1D histogram from data stored in the XML file itself. 

The first two lines of the XML file are necessary boilerplate which should appear in all such XML files. Following that the tags define a single plot which has a data area displaying binned 1D data that is specified in the XML file itself. The resulting plot is show below.

More examples to come. The Babar JAS/XML/HTML page also has some detail on using XML to create plots for JAS.

PlotML extensions

As of JAS 2.2.2 it is possible to specify normalization and function overlays (and fits) in the plotml (xml) file.

Normalizing Plots

You can normalize a plot by adding the following tag after the style tag

<normalization method="AREA">

The method can be one of:

• CONSTANT - default (non) normalization
• MAXBIN - normalize to the maximum bin
• BIN - normalize to a specific bin (or xBin,yBin) use param="n" to specify the bin
• BINAT - normalized to the bin at a specific X (or X,Y coordinate) use param="x" to specify coordinate
• AREA - normalize to the area under the plot
• ENTRIES - normalize to the number of entries in the plot
• STATISTIC - normalize to a specific entry in the statistics - use param="statisticName" to specify

In addition you can specify the following attributes:

• multiplier=value, applies an (additional) fixed normalization factor
• relativeTo=dataTag, normalizes relative to a different dataset overlayed on the same plot. To use this option you must tag the data you want to normalize to by specifying a name=dataTag attribute on the data1D or data2d tag.

Normalization Examples

Fitting Plots

You can overlay a function on a plot, and optionally fit it to a dataset by specifying the following tag.

<function1d type="Gaussian">
   <functionParam name="amplitude" value="372"/>
   <functionParam name="mean" value="0.996"/>
   <functionParam name="sigma"value="0.123"/>
   <functionStyle1d lineColor="Blue"/>
</function1d>

Where type can be one of:

• Straight Line (parameters slope, yoffset)
• Gaussian (parameters amplitude, mean, sigma)
• Quadratic (parameters a,b,c)
• Cubic (parameters a,b,c,d)
• Polynomial
• Exponential
• Lorentzian
• Spline

In addition you can specify <fit ref=dataTag> to fit the function to a specific dataset. To use this option you must tag the data you want to fit by specifying a name=dataTag attribute on the data1D tag.

Fitting Examples

Related Infomation

Creating XML files from within JAS

The easiest way to create an XML file is to create the plot graphically inside JAS, and then to right click on the plot and choose "Save Plot As..." from the popup menu. In the file chooser which will then popup be sure to select XML File as the file type before selecting a filename to save your file as.

Reading XML files from within JAS

In a forthcoming release of JAS you will be able to read XML containing plots simply by choosing Open from the File menu and selecting a file of type XML. Until then you can run the standalone XML viewer utility using the command (after having set the appropriate CLASSPATH):

java jas.hist.test.XMLHistViewer yourxmlfile.xml

Details of the DTD

For a detailed description of what is allowed in the XML file, refer to the most recent version of the PlotML.dtd file from the JAS source code repository.

Using XML with Servlets

The Servlet How To includes an example of using XML with servlets.

Using XML to display Plots in HTML pages

The HTML How To describes how to use the jas.bean.XMLPlot bean to display plots based on XML within the JAS HTML viewer.