The root primer page

The ROOT Primer Page

A Beginners Guide to the ROOT Data Analysis System

Last Update 14/03/97 | Update Information | List of Visitors of this Page (Currently NOT working)

ROOT has the following characteristics:

Many ROOT concepts (e.g. data structures) have their origin in PAW, the worldwide spread physics data analysis package. PAW is part of the CERNLIB from CERN High Energy Physics Laboratory. The striking differences to PAW (when using root in a simple interactive session):
- All graphical objects (e.g. 3D data plot) can be rotated with a mouse.
- All text objects (e.g. axis titles, statistics boxes) can be moved as well as changed (size, font, color) with a mouse or pull down menus.
- 3D Histograms (!)
As a comparison, the FERMILAB Software Tools, e.g. Histo-Scope / NPlot provide very good 3D and mouse functionality as well, but only a very limited user interface (e.g. no fit procedures).
ROOT is based upon C++ (PAW was based upon FORTRAN). More C++ Information: C++ Virtual Library, C++ Annotations
To my knowlegde, ROOT was at first presented to a larger auditory on the AIHEP96 conference. A summary talk was given by Rene Brun.
Current actual version is Vers. 0.90/12 , 13/01/97
Download from here
The original AIX 3.2.5 Distribution Package was linked by us and can also be obtained from here
PostScript and HTML Documentation from here

The ROOT mailing list: roottalk

(Instructions taken from an email of Fons.Rademakers@cern.ch, 15/01/96)

For a question or a bug report send an email to roottalk@root.cern.ch
To become a member of roottalk send an email to Majordomo@root.cern.ch with the following command in the body of your email message:
```
    subscribe roottalk mail@address
```
If you ever need to get in contact with the owner of the list, send email to owner-roottalk@root.cern.ch .
roottalk archive (all roottalk emails since beginning, ordered by [date][subject][author])

Quick start for PAW users:

PAW2ROOT syntax conversion table

The Primer

Part A:General Remarks

All the examples can be executed within root by typing
```
root [0] .x filename.C;
```
You can look what objects (ntuples, histograms, ...) are defined in your root session by typing
```
root [0] .ls
```
You can start root in the root++ mode by typing
```
root [0] TBrowser *b = new TBrowser
```

Part B:List of ROOT Objects

Canvas

Graphical object.

A canvas can simply be understood as a graphical window (corresponding to a HIGZ window in PAW). If you have not created any canvas, the default canvas c1 is created automatically when plotting something.
Inside your canvas you have to define pads corresponding to zones in your PAW session.
Inside a pad you can put objects, i.e. write text, draw lines, plot functions, histograms, ntuples and so on.
When putting your mouse pointer onto the objects, you can move them (symbol: 4 arrows), scale them (symbol: hand) or rotate them (symbol: 2 bended arrows).
If you have 2 pads within a canvas, you have to use
```
padname.cd();
```
to change your active pad.
Within one pad, you can define as many (sub-)pads as you like and jump between them using the
```
subpadname.cd()
```
command as well.
Example: canvas.C

Fit

Fitting of a histogram or a graph is possible
```
hx->Fit("gaus");    // fit histogram

graph->Fit("pol5"); // fit graph
```
Predefined fit functions: gaus, expo, poln (n=1,2,3,...)
Fitting with user defined fit functions
taken from a roottalk email from R. Brun, 7/03/97
For example, if you want to create a function to be fitted with two parameters involving sin(x):
```
TF1 *f1 = new TF1("f1","[0]*sin([1]*x)",0,3.14);
f1->SetParameter(0,1.1);  //initialize first parameter to 1.1
f1->SetParameter(1,0.2);

graph->Fit("f1");
```
Fit Range (taken from here)
In order to use the Range option, one must first create a function with the expression to be fitted. For example, if your histogram has a defined range between -4 and 4 and you want to fit a gaussian only in the interval 1 to 3, you can do:
```
TF1 *f1 = new TF1("f1","gaus",1,3);
histo->Fit("f1","R");
```

Function

Mathematical object.

If you want to plot a 1-dimensional function, just type

   fun1 = new TF1("fun1","sin(x)",0,10);
   fun1->Draw();

If you want to plot a 2-dimensional function, just type
```
   fun2 = new TF2("fun2","sin(x)*sin(y)",-10.0,10.0,-10.0,10.0);
   fun2->Draw("surf4");
```
You can rotate the 3D plot by use of the mouse.

Graph

x-y plot with or without error bars

root [0] .x graph.C;
as a simple example (axis scaling automatically). You can change position of the data points by use of the mouse (!).
root [0] .x graphbeauty.C;
makes the former example more beautiful (using canvas and graph options).
You can also set all the options by clicking with your mouse and choosing the SetLineAttributes, SetFillAttributes or SetMarkerAttributes panels (right mouse button).
Color Index Color

1 black

2 red

3 green

4 blue

5 yellow

6 pink

7 light blue

8 white

Histogram

A histogram is a data structure containing 1D, 2D or 3D channels. The number of events is stored as a function of the channel index.

If you have already a filled Ntuple and want to project it into a histogram h1, just type
```
ntuple.Draw("x>>h1","","h1");
h1.Draw();
```
without explicitely creating h1.
If you want to fill a 1D, 2D or 3D (!) histogram with some data stored in a variable x within your C-file, here is an example histo.C for random generated data.
Change of axis range
If you have the 2-Dim histogram hxy of the former example (range -4:4), you can draw it into a given frame (which itself is simply a new, empty histogram).
```
TH2F frame("frame","2-Dim", 40, -3, 3, 40, -3, 3);
frame.Draw();
hxy.Draw("same");
```

Copy a histogram h1into a new one

TH1F h2 = new TH1F();
h1->Copy(h2); // from -> to

/* or simply */

TH1F h2 = h1;

NTuples

A NTuple is a matrice-like data structure with n rows (corresponding e.g. to the number of events) and m columns (corresponding e.g. to the number of parameters per event).

For example you may have a data file (ASCII) like xyz.dat and you want to (a) read it and (b) put it into a NTuple Structure. Do it like this:

root [0] .x ntuplefix.C;

Simplest approach.
root [0] .x ntuplevar.C;

More comfortable approach.
Number of parameters and filename are given at runtime.
The data are addressed with a pointer *p. This makes the filling of the ntuple very easy using
ntuple.Fill(p) instead of using
ntuple.Fill(p[0],p[1],p[2],p[3],...)

Ntuple Plotting

Plotting 1D ntuple.Draw("x");

Plotting 2D ntuple.Draw("y:x");

Plotting 3D ntuple.Draw("z:y:x");

Plotting combinations of variables ntuple.Draw("2*x-3*y");

Plotting data with a condition ntuple.Draw("x","(x>0)");

Option: Plot into the same frame ntuple.Draw("x"," ","same");

For disk resident ntuples (if storage exhausted in case of large ntuples)
you first have to open a root file
```
TFile myfile("myfile.root","NEW");
```
Each ntuple created afterwards is automatically disk resident.

PostScript

Graphical output into a printable file.

If you have already a canvas c1 displaying a graph or a histogram, just type
```
TPostScript ps("graph.ps",-112);
c1->Draw();
ps.Close();
```
The different PS modes:

-111 PS portrait

-112 PS landscape

-113 Encapsulated PS not working in root v0.9
Change Size of the PS picture (Bug in root v0.9)
```
ps.Range(4,4); // x- and y-range / cm
```
is not working. The picture always has the same size [ 20 cm x 8 cm ].
Patch: Edit graph.ps, search for ".25 .25 scale" and change the x- and y-scaling factors according to your needs.
Special characters in Text:
"'a#" for the greek character \alpha, "\311" for the german letter ä etc.
For more information see here and overview tables pstable1.ps and pstable2.ps
(located on the root WWW server).

Part C:Adding own classes to root

Example 1: Linking a small program
containing simple root calls

You need 2 files: Makefile.ex1, histo-l.C
histo-l.C is based upon histo.C (see Histogram).
- Edit Makefile.ex1 (choose compiler type and ROOTSYS path).
- mv Makefile.ex1 Makefile
- ```
make histo-l
```
- You end up with the executable histo-l which at runtime opens a rootfile and fills it with a 1-dim and a 2-dim histogram. A 3-dim histogram (working in histo.C) is not working, but I don't know why.

Example 2: Linking your own myroot
containing new classes

At first you have to set some environment variables

   export ROOTSYS=...
   export PATH=$PATH:$ROOTSYS/bin
   export LIBPATH=$LIBPATH:$ROOTSYS/lib

You need 4 files: Makefile.ex2, MyClass.h, MyClass.C, main.C

Edit Makefile.ex2 (choose compiler type and ROOTSYS path)
mv Makefile.ex2 Makefile
```
make
```

You end up with your own root executable myroot including MyClass().
Now try to start it:

>> myroot
  *******************************************
  *                                         *
  *        W E L C O M E  to  R O O T       *
  *                                         *
  *   Version   0.90/12   15 January 1997   *
  *                                         *
  *  You are welcome to visit our Web site  *
  *          http://root.cern.ch            *
  *                                         *
  *******************************************
...
root [0] MyClass myclass
root [1] myclass.Print();
I = 0, F = 0
root [2] myclass.SetInt(1);
root [3] myclass.SetFloat(2.3);
root [4] myclass.Print();      
I = 1, F = 2.3
...

Dictionary:
You need to generate a Dictionary for your new classes. This is done by calling rootcint (implemented in the Makefile):
```
rootcint dict.C -c MyClass.h
```
rootcint reads MyClass.h and generates dict.C (and dict.h automatically) to tell root about your new classes. It is practical to put your class definitions into the h-files (and nothing else) to preserve these files for use with rootcint.

Example 3: Generating a shared library
which can be loaded in a (standard) root session

You need 3 files: MyClass.C, MyClass.h, genshlib
MyClass.C and MyClass.h are identical to Example 2.
Try this:
- Edit genshlib (choose compiler type and ROOTSYS path)
- Please read the remarks about a Dictionary in Example 2. The same is valid for Example 3. The dictionary object file dict.o must be part of the shared library.
- Furthermore, you have to find out how to generate a shared lib on your system platform. Using AIX, the command is
```
/usr/lpp/xlC/bin/makeC++SharedLib 
```
  You find the right command in your root distribution in the file $ROOTSYS/test/Makefile:
```
$(EVENT):       $(EVENTO)
                ... (look here for the command)
```
- Execute
```
genshlib
```
- You end up with a shared library MyClass.so which can be included dynamically in your root session. Try this:
```
>>root
  *******************************************
  *                                         *
  *        W E L C O M E  to  R O O T       *
  *                                         *
  *   Version   0.90/12   15 January 1997   *
  *                                         *
  *  You are welcome to visit our Web site  *
  *          http://root.cern.ch            *
  *                                         *
  *******************************************
...
root [0] gSystem->Load("MyClass.so");
root [1] MyClass myclass
root [2] myclass.Print();
I = 0, F = 0
...
```

Remark: Although we think that root is a brilliant concept, this page claims to be independent from the root development team. Thus, hopefully objectivity is achieved.

Update Information:
97/01/17 Page is released at Technical University Dresden
97/02/12 Page is added to "Applications using root" on http://root.cern.ch
97/07/03 Page is moved to Tokyo Metropolitan University

April - June 97 NO UPDATE (I moved to Japan, sorry)
Regularly Update will follow soon !

Questions/Comments | Sören Lange, 97/07/03

Color Index	Color
1	black
2	red
3	green
4	blue
5	yellow
6	pink
7	light blue
8	white

Plotting 1D	ntuple.Draw("x");
Plotting 2D	ntuple.Draw("y:x");
Plotting 3D	ntuple.Draw("z:y:x");
Plotting combinations of variables	ntuple.Draw("2x-3y");
Plotting data with a condition	ntuple.Draw("x","(x>0)");
Option: Plot into the same frame	ntuple.Draw("x"," ","same");

-111	PS portrait
-112	PS landscape
-113	Encapsulated PS	not working in root v0.9