|
||||||
JAIDA 3.2.0 Release NotesThe most recent version of this file is available
here. JAIDA is a Java implementation of AIDA - Abstract Interfaces for Data Analysis. JAIDA 3.2.0 is based on AIDA 3.2. From a user perspective JAIDA 3.2.0 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
For a full list of changes in JAIDA 3.2.0 see the
JAIDA
change log. DocumentationThese 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: LicenseJAIDA 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 StartedThis 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:
A simple script called Two implementations of the AIDA IAnalysisFactory are provided with JAIDA:
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 ReleaseHistograms - We have provided a full implementation of the AIDA 3.2 histogram interfaces, including histogram arithmetic and projections and slices. 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. Styles - An initial implementation of AIDA plot styles has been added in this release. The following parameters are supported in this release:
The colors can be passed to the styles in the following formats:
Currently it is not possible to programmatically change:
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:
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 p, e, g and g2 respectively. No operations among them are currently supported. 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:
Optional ExtrasJAIDA 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 BugsFor discussion of features or problems related to JAIDA please use the AIDA mailing lists. To report bugs or request enhancements you can also use the JAIDA bug database. Saving plotsIf 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:
Embedding the JAIDA plotter in your own Java applicationThe 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 servletThe 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 JAS3JAIDA 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 PythonPython 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:
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 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 Geant4JAIDA is currently distributed as an overlay product for Geant4. Eventually this will be changed and the normal JAIDA distribution should be usable. Until then, follow the JAIDA/Geant4 instructions.
|
||||||