JAIDA

JAIDA 3.2.3 Release Notes

The most recent version of this file is available here.
Release notes for other versions of JAIDA are available here.

JAIDA is a Java implementation of AIDA - Abstract Interfaces for Data Analysis. JAIDA 3.2.3 is based on AIDA 3.2. From a user perspective JAIDA 3.2.3 is entirely backwards compatible with AIDA 3.0 and JAIDA 3.0.*.

JAIDA allows Java programmers to quickly and easily create histograms, scatter plots and tuples, perform fits, view plots and store and retrieve analysis objects from files. JAIDA can be used either in a non-graphical environment (for batch processing) or with a simple GUI to display plots. Files written with JAIDA adhere to the AIDA IO standards and can be read by any AIDA compliant analysis system. 

Users wishing to get full GUI functionality may be interested in JAS3, a graphical data analysis toolkit built on top of JAIDA. JAS3 can also read .aida files written with JAIDA.

Contents

• Major changes in JAIDA 3.2
• Documentation
• License
• Getting started
• Limitations/Features of the Current Release
• Optional extras
• Reporting Bugs
• Saving plots
• Embedding the JAIDA plotter in your own Java application
• Using JAIDA in a servlet
• Using JAIDA with JAS3
• Using JAIDA from C++
• Using JAIDA from Python
• Using JAIDA from Pnuts
• Using JAIDA from Geant4

Changes

Changes in JAIDA 3.2.3

• Better implementation of writeToFile method. More details are provided below, where the features of the Plotter implementation are described.
• We have changed the way the statistics is evaluated for IHistograms and IProfiles. The details are provided below.

Changes in JAIDA 3.2.2

• Addition among functions is now supported. You can now fit for example "g + p0" to any AIDA data source.
• Improved styles support.
• Fixed problems with logarithmic axis.

Changes in JAIDA 3.2.1.1

• Scripts updated to set and convert classpath correctly when used in cygwin on Windows.

Major changes in JAIDA 3.2.1

• Improved support for plot styles, including the ability to modify styles after a plot is displayed.
• Support for reading root files from a remote root daemon using the root: protocol.
• .win32 setup file merged with .csh and .sh setup files.

Major changes in JAIDA 3.2.0

• JAIDA 3.2 implements the AIDA 3.2 interfaces.
• The default analysis factory has been changed from hep.aida.ref.BatchAnalysisFactory to hep.aida.ref.AnalysisFactory. See Getting Started for more information.
• An initial implementation of the AIDA IStyle interfaces is now available.

For a full list of changes in JAIDA 3.2.3 see the JAIDA change log.
For a full list of changes in AIDA 3.2 see the AIDA change log.

Documentation

These release notes list issues specific to the JAIDA implementation of AIDA. In general all of the AIDA documentation applies to JAIDA, in particular the following are useful:

• AIDA Users' Guide
• AIDA API documentation

License

JAIDA is part of the FreeHEP Java Library an "Open Source" library distributed under the terms of the LGPL. If you have questions about the licensing please send a mail to: developers@freehep.org.

Getting Started

This current release of JAIDA is designed to be used with Java 1.4.0 or later. It will not work with earlier versions of Java.

Several JAR files are included in this release. You have to include the ones you need in your CLASSPATH to be able to use JAIDA:

• aida.jar - The specification of the AIDA interfaces
• aida-dev.jar - The developer level specification of the AIDA interfaces
• freehep-hep.jar - The base (non-graphical) AIDA implementation
• freehep-base.jar - Some utilities used by freehep-hep
• openide-lookup.jar - Utility used by AIDA implementation
• jel.jar - Utility used by AIDA implementation
• optimizers.jar - Optimization package containing the optimizer UNCMIN
• bcel.jar - needed to read ROOT files
• jas-plotter.jar - Required if you need to display plots

A simple script called aida-setup is provided with JAIDA in the bin directory, you can run this to set the CLASSPATH appropriately.

Two implementations of the AIDA IAnalysisFactory are provided with JAIDA:

• hep.aida.ref.AnalysisFatory (the default)
• hep.aida.ref.BatchAnalysisFactory

The former includes a simple implementation of the AIDA plotter, the latter contains a dummy implementation of the plotter which allows for AIDA to be run in a batch (or headless) environment. You can explicitly select which analysis factory to use by setting the Java property hep.aida.IAnalysisFactory, e.g.:

java -Dhep.aida.IAnalysisFactory=hep.aida.ref.BatchAnalysisFactory

The built-in plotter is intended mainly as a simple viewer for AIDA plots, for a full-featured GUI implementation based on JAIDA see JAS3.

Features/Limitations of the Current Release

Histograms - We have provided a full implementation of the AIDA 3.2 histogram interfaces, including histogram arithmetic and projections and slices. For AIDA Histograms and Profiles the statistics (mean and rms) is calculated using ONLY "in-range" data, i.e. data whose bins don't have any components that is either in the UNDERFLOW or in the OVERFLOW bin. In this implementation you can choose to used all the data for the statistics evaluation by adding "useOutflowsInStatistics=true" to the options String when creating Histograms and Profiles. If an AIDA object is filled with a NaN, such value will be ignored in the evaluation of the statistics but it will be considered in the count of the overall number of entries. The number of NaN entries can be obtained by subtracting the number of in-range entries and the number of out-of-range entries from the number of total entries. The number of NaN entries will be displayed in the statistics box when plotting the AIDA object if such number is non zero.

Profile - One and two dimensional Profile histograms are fully implemented.

Clouds - We have provided a full implementation of the AIDA 3.2 cloud interfaces. By default clouds will "auto-convert" to histograms when they reach 100,000 entries. You can turn off auto-conversion by specifying the option "autoConvert=no" when creating the Cloud. A new options controls how clouds are auto-converted to histograms, "margin=0.1" will add a 10% margin to the computed min/max of the cloud which determining the histogram range. The default value is "margin=0.05", "margin=0" will restore the behaviour of the previous release.

DataPointSet - A full implementation of the AIDA 3.2 is implemented including operations among DataPointSets.

Trees and IO - The current implementation of  ITree supports reading and writing AIDA standard XML files (.aida files) in either gzip compressed format, or uncompressed format. You can control this via the options parameter when the ITree is created. The default is "compressed=yes". It is also possible to open ROOT files, and if the optional CERNLIB adapter is installed, also PAW files.

Tuples - The whole functionality of AIDA ITuple interface is supported, including support for evaluators, filters and nest ITuples . Full interactive analysis of ITuples  is provided by the TupleExplorer plugin in JAS3.

Plotting - Full support for the IPlotter interface is included, including regions and overlays. In the Java implementation the Plotter observes all displayed Histograms and Clouds, and will automatically update the display as necessary. Therefore the IPlotter.refresh() method is currently ignored in the Java implementation. Not all AIDA implementations will do this, so for portability you should still periodically call the refresh() method. Similarly the Java implementation is multi-threaded, so plots will be refreshed while the main program continues to run, and hence the IPlotter.interact() method is also ignored by the Java implementation. Currently it is not possible to plot 3D (or higher dimensionality) data objects. Histograms with variable bin-widths are not yet displayed correctly. Initial support for plot styles has been added in this release.

The following parameters have been added in the Java implementation to the plotter region to access the limits of the plot area: xAxisLowerLimit, xAxisUpperLimit, yAxisLowerLimit, yAxisUpperLimit. To access the region's limits just type:

double xLowerLimit = Double.parseDouble( plotterRegion.parameterValue("xAxisLowerLimit") );

The parameter "mode" is used to control how an object is added to a plot. It is passed as an option in the plot(...) method on the IPlotterRegion and it can take two values: "overlay" to overlay the object to the existing ones, "replace" to replace the existing plots with the one corresponding to the provided object. The latter is equivalent to first clearing the region and then plotting the object. The default value is "overlay".

plotterRegion.plot(hist, "mode=overlay"); or
plotterRegion.plot(hist, "mode=replace");

writeToFile method: there might be some problems when invoking the writeToFile method due to the way the Plotter is currently implemented. In particular the following applies to the situation in which the plotter is showing in the GUI (show() has been invoked) and the data is changed (for example an histogram is filled); this results in a plot updating on the screen to reflect the changes in the data. To do this the data source fires events to the plot to notify that it changed, and, as a result of this the plot updates. To prevent too many events being fired and scripts being slow waiting for the GUI to update we have a 1 second delay after such an event is received before we perform the update (in this time window no more events are fired). Due to this delay it is necessary to synchronize the process of writing the plot to file with the plot updates. To do so, when the writeToFile method is invoked, we submit a process to the Swing thread that will write the plot to file with a delay of a second. One extra complication is that, due to the fact that update events generate other update events on the Swing thread, we cannot guarantee the relative order of such processes with the writeToFile one. In other words there might be cases in which the plot written to file is different to the one represented in the GUI WHEN writeToFile is invoked and the plot is showing.

For this reason we suggest NOT to show the plot to screen when writeToFile is to be invoked.

We will fix the above problem in a future version of the plotter.

Trees - JAIDA can read and write XML files (also known as aida files). In addition it can read PAW (if the optional CERNLIB extension is installed) and Root files (either directly or via a root daemon). Here are some examples:

ITree tree = tf.create("myFile.aida","xml");
ITree tree = tf.create("myFile.paw","paw");
ITree tree = tf.create("myFile.root","root");
ITree tree = tf.create("root://sldrh2.slac.stanford.edu","root",true,false,"scheme=anonymous");

When opening root files the following options are supported:

Styles - The AIDA style interfaces are fully implemented.  To understand the way styles work it is important to understand the hierarchical structure of the AIDA styles. For each plot a cascade of styles is taken into account: the style associated to the IPlotter, the one associated to the IPlotterRegion, the default one for a given type of data, and the user provided ones when the actual plotting is done (passed via the plot(..) method on the IPlotterRegion). When retrieving the value of a give style parameter we first start from the user provided styles (if any) and navigate down through all the above styles until we find a style for which the given style parameter has been set. This means that the style parameters set in a user provided style will always overwrite the corresponding style parameter set on the IPlotterRegion. Alternatively changing a style parameter on the IPlotterRegion will not affect a plot if a user provided style has been used to render the plot and the given style parameter has been set by the user.

In the Java implementation all the plots listen for changes to all the styles, except for the user provided ones, i.e. the ones that are passed to the IPlotterRegion via its plot(...) method. The plots will update automatically to display any style changes. There is a small caveat here due to a limitation in the AIDA interfaces. In order to modify the plot style of a given object that has been rendered with a user defined style after it has been plotted, it is necessary to first remove the object from the plot (remove(..) method on IPlotterRegion), adding it back again providing the modified style object. We plan to fix this problem for the next release of AIDA: 4.0.

In our Java implementation we have added the following parameters to our implementation of the AIDA styles to allow a finer control over the objects that appear on a given plot. In the table below we list both the standard AIDA parameters the additional parameter names added in our implementation. For each parameter we provide the name, the AIDA object on which they should be set, a description of what they control and the allowed values; for the standard AIDA parameters we also provide the method name that corresponds to such parameters. Please note that all the parameter names and their values are case sensitive. For more information on the AIDA styles please refer to the AIDA API.

The colors can be passed to the styles in the following formats:

• by name: "yellow" , where alpha is always 1.0
•  by int r,g,b,a: "128, 255, 64, 255" , where alpha (a) is optional
•  by float r,g,b,a: "0.5, 1.0, 0.25, 1.0" , where alpha (a) is optional
•  by single number: "64637" or "0x0FFF08" , where alpha is always 1.0

The marker's shape can be either a string or a number (a String number); the available shapes are: "dot" or "0", "box" or "1", "triangle" or "2", "diamond" or "3", "star" or "4", "verticalLine" or "5", "horizontalLine" or "6", "cross" or "7", "circle" or "8" and "square" or "9".

Fitting - The flexible design of the IFitter interface allows the user to switch very easily the optimizer engine used in the minimization process and the type of fit method used. We currently support two optimizers: Minuit and Uncmin. The available fit methods are:

• LeastSquares
• Chi2
• CleverChi2
• BinnedMaximumLikelihood
• UnbinnedMaximumLikelihood

The following link provides the fit methods definition.

Functions- Two types of functions can be created with the IFunctionFactory: built-in functions and scripted functions. Currently the only built-in functions we provide are the Polynomial, the Exponential, the one and two dimensional Gaussian that can be created through the createFunctionByName method of the IFunctionFactory using for the functions model p0, p1, ... , e, g and g2 respectively. No operations among them are currently supported.

The following table shows the name and the list of parameters for each of the built-in functions:

It is possible to create functions by name by adding any of the built in functions, e.g. "g0 + p1".

For more complicated functions the user should create scripted functions though the createFunctionFromScript method.

The following list details which parts of the AIDA standard are not fully implemented:

• Class IInfo is not implemented
• IFitter supports only constraints of the type "a = b"
• IFunctions: no operations among built in functions, beside addition, are supported.
• IPlotterLayout is not implemented
• IEvaluator and IFilter can only be applied to ITuple's columns at the root level (not to columns inside folders)
• ITuple: for the reason above the project methods on ITuple apply only to root level columns
• Provide full support to the AIDA Styles parameters

Optional Extras

JAIDA is written entirely in Java, and therefore works on any platform with support for Java. JAIDA also contains code for reading PAW files and for using the Minuit fitter. Both of these components use native code from CERNLIB, and to use them you will need to download and install the additional CERNLIB_Adapter for your platform in order to use these features.

Reporting Bugs

For discussion of features or problems related to JAIDA please use the JAIDA discussion forum. To report bugs or request enhancements you can also use the JAIDA bug database.

Saving plots

If you are using the hep.aida.ref.AnalysisFactory you can export your plots to a graphics file through the writeToFile(String fileName, String type) method on the IPlotter. In order to do this you need to download the following jar files from the FreeHEP repository and add them to your CLASSPATH:

• freehep-graphics2d.jar
• freehep-graphicsio.jar
• any additional freehep-graphicsio-"type".jar where "type" is one of the following export formats:
  • cgm, emf, gif, pdf, ppm, ps, svg, swf

Embedding the JAIDA plotter in your own Java application

The following example illustrates how to embed one (or more) JAIDA plotters into your own Java application. The example makes use of the hep.aida.ref.plotter.PlotterUtilities class which contains several methods for assisting in interfacing JAIDA to other Java applications.

import hep.aida.*;
import hep.aida.ref.plotter.PlotterUtilities;
import java.awt.BorderLayout;
import java.awt.event.ActionEvent;
import java.util.Random;

import javax.swing.*;

/**
 * An example of how to embed a JAIDA IPlotter into your own application.
 */
public class AIDAEmbed extends JPanel
{
   /** Creates a new instance of AIDAEmbed */
   public AIDAEmbed()
   {
      super(new BorderLayout());

      IAnalysisFactory af = IAnalysisFactory.create();
      ITree tree = af.createTreeFactory().create();
      IHistogramFactory hf = af.createHistogramFactory(tree);
      IHistogram1D h1d = hf.createHistogram1D("Test", 50, -3, 3);

      // Fill with junk
      Random rand = new Random();
      for (int i = 0; i < 10000; i++)
         h1d.fill(rand.nextGaussian());

      // Create an IPlotter 
      IPlotter plotter = af.createPlotterFactory().create();
      plotter.currentRegion().plot(h1d);

      // Now embed the plotter
      add(PlotterUtilities.componentForPlotter(plotter), BorderLayout.CENTER);
   }

   /**
    * @param args the command line arguments
    */
   public static void main(String[] args)
   {
      JFrame frame = new JFrame("Embedded AIDA");

      JMenuBar bar = new JMenuBar();
      JMenu menu = new JMenu("File");
      JMenuItem item = new JMenuItem(new ExitAction());
      menu.add(item);
      bar.add(menu);
      frame.setJMenuBar(bar);

      frame.setContentPane(new AIDAEmbed());
      frame.setDefaultCloseOperation(frame.EXIT_ON_CLOSE);
      frame.pack();
      frame.show();
   }
   
   private static class ExitAction extends AbstractAction
   {
      ExitAction() { super("Exit"); }
      public void actionPerformed(ActionEvent e) { System.exit(0); }
   }
}

Using JAIDA in a servlet

The following example illustrates how to use JAIDA in a servlet to send graphics back to a user's web browser.

import hep.aida.*;
import hep.aida.ref.plotter.PlotterUtilities;
import java.io.IOException;
import java.util.Random;
import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class AIDAServlet extends HttpServlet
{
   private IPlotter plotter;
   /** Initializes the servlet.
    */
   public void init(ServletConfig config) throws ServletException
   {
      super.init(config);
      
      IAnalysisFactory af = IAnalysisFactory.create();
      ITree tree = af.createTreeFactory().create();
      IHistogramFactory hf = af.createHistogramFactory(tree);

      IHistogram1D h1 = hf.createHistogram1D("Test", 50, -4, 4);
      Random r = new Random();
      for (int i = 0; i < 10000; i++)
         h1.fill(r.nextGaussian());

      plotter = af.createPlotterFactory().create("Test");
      plotter.region(0).plot(h1); 
   }
   
   public void doGet(HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException
   {      
      ServletOutputStream out = res.getOutputStream();  
      res.setContentType("image/png");
      PlotterUtilities.writeToFile(plotter,out,"png",null);
      out.close();
   }   
}

Using JAIDA with JAS3

JAIDA is intended for use in simple standalone Java applications. It provides the full AIDA functionality for Java, but only limited "GUI" functionality. JAS3 builds on the functionality of JAIDA and adds many GUI based interactive analysis tools. JAS3 is available from http://jas.freehep.org/jas3.

Using JAIDA from Python

Python is a popular object-oriented scripting language. Jython is an implementation of Python written in Java. Jython is able to access any Java object as if it were a Python object. Thus it is very easy to use JAIDA with Jython. The combination provides a very convenient way of exploring the capabilities of JAIDA.

To use it follow steps below:

• Download and install Jython. Add the installation directory to your PATH.
• Make sure your CLASSPATH is set as specified in the getting started section of these release notes.

Run the script below just by typing:

jython UsingJAIDAFromJython.py

where UsingJAIDAFromJython.py contains:

from hep.aida import *
from java.lang import *
from java.util import *

System.getProperties().setProperty("hep.aida.IAnalysisFactory","hep.aida.ref.AnalysisFactory")

true = Boolean("true");
false = Boolean("false");

factory = IAnalysisFactory.create();
tree    = factory.createTreeFactory().create("UsingJAIDAFromJython.aida","xml",false,true);
hf      = factory.createHistogramFactory(tree);
#fitter  = factory.createFitFactory().createFitter("Chi2","uncmin");

tree.mkdir("/Histograms");
tree.cd("/Histograms");

h1 = hf.createHistogram1D("Histogram 1D",50,-3,3);
h2 = hf.createHistogram2D("Histogram 2D",40,-3,3,40,-3,3);
        
tree.mkdir("/Clouds");
tree.cd("/Clouds");

c1 = hf.createCloud1D("Cloud 1D");
c2 = hf.createCloud2D("Cloud 2D");

page1 = factory.createPlotterFactory().create("Page1");

page1.show();
page1.createRegions(2,2);

page1.region(0).plot(h1);
page1.region(1).plot(h2);
page1.region(2).plot(c1);
page1.region(3).plot(c2);

r = Random()

def fill():
          for i in range(10000):
                h1.fill(r.nextGaussian())
                h2.fill(r.nextGaussian(),r.nextGaussian())
                c1.fill(r.nextGaussian())
                c2.fill(r.nextGaussian(),r.nextGaussian())

fill()

tree.commit();

Using JAIDA from Pnuts

Pnuts is a nice java scripting language and it can downloaded it from https://pnuts.dev.java.net/.

The above AIDA script in Pnuts looks like:

IAnalysisFactory = class hep.aida.IAnalysisFactory
factory = IAnalysisFactory::create()

tree    = factory.createTreeFactory().create("UsingJAIDAFromPnuts.aida","xml",false,true);
hf      = factory.createHistogramFactory(tree);

tree.mkdir("/Histograms");
tree.cd("/Histograms");

h1 = hf.createHistogram1D("Histogram 1D",50,-3,3);
h2 = hf.createHistogram2D("Histogram 2D",40,-3,3,40,-3,3);
        
tree.mkdir("/Clouds");
tree.cd("/Clouds");

c1 = hf.createCloud1D("Cloud 1D");
c2 = hf.createCloud2D("Cloud 2D");

page1 = factory.createPlotterFactory().create("Page1");

page1.show();
page1.createRegions(2,2);

page1.region(0).plot(h1);
page1.region(1).plot(h2);
page1.region(2).plot(c1);
page1.region(3).plot(c2);

Random = class java.util.Random
r = Random()

for( i = 0; i < 10000; i++ ) {
   h1.fill(r.nextGaussian())
   h2.fill(r.nextGaussian(),r.nextGaussian())
   c1.fill(r.nextGaussian())
   c2.fill(r.nextGaussian(),r.nextGaussian())
}

tree.commit();

To execute the above script follow the steps below:

• save the Pnuts script in a file called "script.pnut"
• execute with
  • pnuts script.pnut

where "pnuts" is the executable that comes with the Pnuts distribution appropriate for your platform.

Using JAIDA from C++

To access the Java implementation of the AIDA interfaces from C++ you need to download the AIDAJNI glue code that will allow you to operate on the JAIDA objects from C++.

Example C++ code follows:

£include <iostream>
£include <cstdlib>

£include "AIDA/AIDA.h"
£include "JIAnalysisFactory.h"

using namespace AIDA;

int main(int argc, char *argv[]) {

        AIDA::IAnalysisFactory* factory = AIDA_createAnalysisFactory();
        ITree*              tree    = factory->createTreeFactory()->create("UsingJAIDAFromCPP.aida","xml",false,true);
        IHistogramFactory*  hf      = factory->createHistogramFactory(*tree);

        tree->mkdir("/Histograms");
        tree->cd("/Histograms");

        IHistogram1D* h1 = hf->createHistogram1D("Histogram 1D",50,0,10);
        IHistogram2D* h2 = hf->createHistogram2D("Histogram 2D",40,0,10,40,0,10);
        
        tree->mkdir("/Clouds");
        tree->cd("/Clouds");
        
        ICloud1D* c1 = hf->createCloud1D("Cloud 1D");
        ICloud2D* c2 = hf->createCloud2D("Cloud 2D");

        IPlotter* page1 = factory->createPlotterFactory()->create("Page1");

        page1->show();
        page1->createRegions(2,2);

        page1->region(0)->plot(*h1);
        page1->region(1)->plot(*h2);
        page1->region(2)->plot(*c1);
        page1->region(3)->plot(*c2);

        srand( 0 );
        for ( int i = 0; i < 10000; i++ ) {
            h1->fill( 10*rand()/(double)RAND_MAX );
            h2->fill( 10*rand()/(double)RAND_MAX, 10*rand()/(double)RAND_MAX);
            c1->fill( 10*rand()/(double)RAND_MAX );
            c2->fill( 10*rand()/(double)RAND_MAX, 10*rand()/(double)RAND_MAX);
        }
        tree->commit();
        delete factory;
        return 1;
}

Using JAIDA from Geant4

Please follow the link on how to use JAIDA from Geant4.