Inclusion of Active Figures in Eprints

An `active figure' is a figure that can be modified in response to user input. For example, a figure might show a calculation or a fit to data using a certain arbitrarily chosen set of parameters. An active figure would allow a reader to input a different set of parameters and would then redraw itself accordingly.

It is not yet possible to have active figures in the standard ps or pdf text formats. However, it is completely straightward to create an active version of a figure as a java applet. And, it is easy to package this applet with an eprint, so that it can be stored at the eprint archive arXiv.org. In this form, the active figure can be retrieved with the paper and run while the paper is being read. A recent paper hep-ph/0101342, by James Wells and myself, illustrates how this can be done.

This page gives some basic materials for the creation of active figures. The java implementation in these files is rather primitive. If you can improve upon it, please send me the results. Address this and other correspondence to mpeskin@slac.stanford.edu

A java applet plotter: Pplotter.java
A simple two-parameter linear fitter: LinearFit.java
Construction of the applet in hep-ph/0101342
How to submit an active figure to arXiv.org

A java applet plotter: Pplotter.java

Here is a simple applet plotter: Pplotter.java. You will also need the class plotStream.java, which is the format for data input to the Pplotter. Pplotter is an abstract class which extends the class Applet. To instantiate a class derived from Pplotter, it is necessary to define the two methods:

public void setup() : This method is called by init(). It is used to specify the x and y limits of the plot and the tick size. It can also include other initialization functions.

public void plot(Graphics g) : This method is called by paint(Graphics g) after the axes and labels of the plot are drawn. This method is used to call the actual plotting functions.

A curve or continuous line is fed into the Pplotter through a plotStream class. A plotStream class has the public methods:

plotStream() : constructor
void add(double x, double y) : add a point to the plot.
void add(double x, double y, double yerr)
void add(double x, double xerr, double y, double yerr)
int size() : return the number of points in the plotStream.
double x(int i) : return the value of x in point i.
double y(int i)
double xerr(int i)
double yerr(int i)

The Pplotter class has the following public methods. Many of these emulate similar methods of the Topdrawer graphics program.

void setLimits(double xa, double xb, double ya, double yb) : set the limits of the plot
void setTicks(double xtick, double ytick) : set the tick size; a numerical label will appear on every five ticks
void drawLine(Graphics g, double x1, double y1, double x2, double y2) : draw a line from (x1,y1) to (x2,y2).
void drawRect(Graphics g, double x1, double y1, double x2, double y2) : draw a rectangle with corners at (x1,y1) and (x2,y2).
void drawString(Graphics g, String str, double x, double y) : write a character string on the plot at (x,y).
void plotPoints(Graphics g, plotStream PS) : plot a set of data points.
void plotLines(Graphics g, plotStream PS) : plot a broken line connecting the successive points of PS.
void plotHistogram(Graphics g, plotStream PS) : plot the data points in PS as a histogram.
void plotCurve(Graphics g, plotStream PS) : plot the data points in PS as a smooth curve, using spline interpolation.
void setClip(Graphics g) : restrict plotting to the interior of the plot.
void switchColor(Graphics g) : change the color used for plotting.

If you wish to plot in a specific color, this is best done by calling the standard java Graphics method, e.g.: g.setColor(Color.blue); . However, the method switchColor is useful when you overlay many plots with different parameter values.

A simple two-parameter linear fitter: LinearFit.java

Here is a simple linear fitter: LinearFit.java The fitter is based on a two-parameter relation: x_i = A_ik p_k, for k = 0,1, i = 0, ..., Ndata-1. (Note that java arrays start indexing at 0.) The fitter has a method fit() that fills the following variables of the fitter class:

center[k] : the central value of the fit
centererr[k] : the 1-dimensional error in each element of center[k]
chisq : the chi squared of the fit at its minimum

LinearFit is an abstract class which extends the class Pplotter. To instantiate a class derived from LinearFit, it is necessary to define the the method:

void fillX0() : This method fills the vector X0[i], i = 0, ..., Ndata-1, which gives the values of the various observables at p_k = 0.

LinearFit also has graphics functions that arise because it is defined as an extension of Pplotter. The public methods of the LinearFit class are:

LinearFit(int Ndata) : constructor
void setDependence(int i, double A0, double A1): sets A_i0 and A_i1.
void addData(int i, double x, double err) : sets the ith data point.
void fit() : perform the fit.
void plotContour(Graphics g) : plot the 68% confidence contour of the 2-d fit.
void plotContour(Graphics g, double centerx, double centery) : plot the 68% confidence contour centered at (centerx, centery).
boolean contourOutside() : returns true if the contour falls outside the boundaries of the plot.
void plotConstraint(Graphics g, i) : plot the 1-sigma constraint on the p_k given by the data point i.

Construction of the applet in hep-ph/0101342

The applet in hep-ph/0101342 is built using the class hierarchy: Applet -> Pplotter -> LinearFit -> STFit -> STapplet. The applet is accessed through the html file stapplet.html. The latter three files can be obtained here:

STfit.java adds the methods specific to the particular physics analysis done in the paper. STapplet.java adds the GUI. For an explanation of how to write GUI's in java, see any book on java. You might not learn anything else from this book, but you will see many examples of graphics and user interface components built from the java abstract windowing toolkit (awt). The GUI is written in Java 1.1. I recommend that you not write your applet in Java 2, since many browsers and even whole operating systems (e.g. Macintosh) do not yet support Java 2.

How to submit an active figure to arXiv.org

Finally, here are instructions for submitting an active figure to the eprint archive. I will use "yymmddd" to represent the paper number and "xapplet.class" to refer to the applet.

Compiling a java program generates a large number of object (`class') files. Bind these into a single `jar' file. On a UNIX system, this is done by the command: jar cf xapplet.jar *.class .
The applet is viewed most straightforwardly if it is run from an html file. So, create an html file xapplet.html which refers to the applet by an`applet' tag which includes the line: `code="xapplet.class" archive="xapplet.jar"'
Since arXiv.org will rename files, edit the html file to change `archive="xapplet.jar"' to `archive="yymmddd.xapplet.jar"'. (To do this, you need to know yymmddd. Eventually, the eprint archive will make this substitution automatically.)
Create a new file called 00README.XXX which contains one line of text: `xapplet.jar include'.
Create the tar file to be uploaded to arXiv.org. Normally, this includes a tex file and some eps figures. Include also the files: xapplet.jar, xapplet.html, 00README.XXX.
Submit the tar file as usual.
The archive will process the submission and then set up a postscript page for the paper, with the renamed files yymmddd.xapplet.html, yymmddd.xapplet.jar appearing as extra files on this page. Now you are done. If you would like these files to appear in logical order, note that they will appear together with yymmddd.ps in alphabetical order, with capitals before lower cases letters. Thus, if the name of the applet would follow `ps', the three files will appear in logical order.

M. E. Peskin

SLAC