Histograms

Histograms play a fundamental role in any kind of physical analysis. Histograms not only serve to visualize measurements, but also represent a powerful form of data reduction. ROOT supports histograms up to three dimensions.

Binned data

A histogram is used for continuous data, where the bins represent ranges of data. ROOT supports constant and variable bin widths.
A graph or chart is a plot of categorical variables, this is un-binned data, see → Graphs.


Histogram tutorials

Histogram classes

ROOT supports the following histogram types:

  • Histograms up to three dimensions (1-D, 2-D, 3-D).

  • Profile histograms, which are used to display the mean value of Y and its standard deviation for each bin in X.

All histogram classes are derived from the TH1 base class.

The following histogram classes are available in ROOT, among others:

1-D histograms

  • TH1C
    One byte per channel. Maximum bin content = 127.
  • TH1S
    One short per channel. Maximum bin content = 32767.
  • TH1I
    One int per channel. Maximum bin content = 2147483647.
  • TH1F
    One float per channel. Maximum precision 7 digits.
  • TH1D
    One double per channel. Maximum precision 14 digits.

2-D histograms

  • TH2C
    One byte per channel. Maximum bin content = 127.
  • TH2S
    One short per channel. Maximum bin content = 32767.
  • TH2I
    One int per channel. Maximum bin content = 2147483647.
  • TH2F
    One float per channel. Maximum precision 7 digits.
  • TH2D
    One double per channel. Maximum precision 14 digits.

3-D histograms

  • TH3C
    One byte per channel. Maximum bin content = 127.
  • TH3S
    One short per channel. Maximum bin content = 32767.
  • TH3I
    One int per channel. Maximum bin content = 2147483647.
  • TH3F
    One float per channel. Maximum precision 7 digits.
  • TH3D
    One double per channel. Maximum precision 14 digits.

Profile histograms

  • TProfile
    Profile histogram to display the mean value of Y and its error for each bin in X.
  • TProfile2D
    Profile2D histograms are used to display the mean value of Z and its RMS for each cell in X,Y.
  • TProfile3D
    Profile3D histograms are used to display the mean value of T and its RMS for each cell in X,Y,Z.

Bin numbering

All histogram types support fixed or variable bin sizes. 2-D histograms may have fixed size bins along X and variable size bins along Y or vice-versa.

Conventions

For all histogram types: nbins, xlow, xup:

  • bin# 0 contains the underflow.

  • bin# 1 contains the first bin with low-edge (xlow INCLUDED).

  • The second to last bin (bin# nbins) contains the upper-edge (xup EXCLUDED).

  • The last bin (bin# nbins+1) contains the overflow.

  • In case of 2-D or 3-D histograms, a global bin number is defined.

Example

Assuming a 3-D histogram h with binx, biny, binz, the function returns a global/linear bin number.

Int_t bin = h->GetBin(binx, biny, binz);

This global bin is useful to access the bin information independently of the dimension.

Re-binning

You can re-bin a histogram via the TH1::Rebin() method. It returns a new histogram with the re-binned contents. If bin errors were stored, they are recomputed during the re-binning.

Working with histograms

Creating and copying a histogram

  • Use a histogram constructor to create a histogram object.

Examples

In the following examples, histograms are created for the classes TH1I , TH2F , TH3D :

   TH1* h1 = new TH1I("h1", "h1 title", 100, 0.0, 4.0);
   TH2* h2 = new TH2F("h2", "h2 title", 40, 0.0, 2.0, 30, -1.5, 3.5);
   TH3* h3 = new TH3D("h3", "h3 title");

– or ­–

  • Clone/copy an existing histogram with the Clone() method.

Example

   TH1* hc = (TH1*)h1->Clone();

Filling a histogram

Examples

   h1->Fill(x);
   h1->Fill(x,w); // with weight
   h2->Fill(x,y);
   h2->Fill(x,y,w);
   h3->Fill(x,y,z);
   h3->Fill(x,y,z,w);

The Fill() method computes the bin number corresponding to the given x, y or z argument and increments this bin by the given weight.
The Fill() method returns the bin number for 1-D histograms or global bin number for 2-D and 3-D histograms.

Filling a histogram with random numbers

The FillRandom() method uses the contents of an existing TF1 function or another TH1 histogram (for all dimensions).

Example

A histogram is randomly filled 10 000 times with a default Gaussian distribution of mean 0 and sigma 1.

   TH1F h1("h1","Histogram from a Gaussian",100,-3,3);
   h1.FillRandom("gaus",10000);

Use the TH1::GetRandom() method to get a random number distributed according the contents of a histogram.

Adding, multiplying and dividing histograms

Following operations are supported on histograms or between histograms:

  • Addition of a histogram to the current histogram.

  • Additions of two histograms with coefficients and storage into the current histogram.

  • Multiplications and divisions are supported in the same way as additions.

You can use the operators (+, *, /) or the TH1 methods Add(), Multiply() and Divide().

Examples

Multiplying a histogram object with a constant:

   h1.Scale(const)

Creating a new histogram without changing the original one:

   TH1F h3 = 8*h1;

Multiplying two histograms and put the result in the third one:

   TH1F h3 = h1*h2;

Drawing a histogram

  • Use the TH1::Draw() method to draw a histogram.

    It creates a THistPainter object that specializes the drawing of the histogram. The THistPainter class is separated from the histogram, so that the histogram does not contain the graphics overhead.

  • Use the TH1::DrawCopy() method to create a copy of the histogram when drawing it.

  • Use the TH1::DrawNormalized() method to draw a normalized copy of a histogram.

Example

   TH1F h1("h1","Histogram from a Gaussian",100,-3,3);
   h1.FillRandom("gaus",10000);
   h1.Draw();

Figure: Histogram drawn with Draw().

Getting the bin width

  • Use the GetBinWidth() method to get the bin width of a histogram.
   TH1F h1("h1","Histogram from a Gaussian",100,-3,3);
   h1.FillRandom("gaus",10000);
   h1.Draw();
   h1.GetBinWidth(0)

   (double) 0.060000000

Drawing options

Note

The drawing options are not case sensitive.

Drawing options for all histogram classes

For detailed information on the drawing options for all histogram classes, refer to THistPainter.

AXIS: Draws only the axis.

HIST: When a histogram has errors, it is visualized by default with error bars. To visualize it without errors, use HIST together with the required option (for example “HIST SAME C”).

SAME: Superimposes on previous picture in the same pad.

CYL: Uses cylindrical coordinates.

POL: Uses polar coordinates.

SPH: Uses spherical coordinates.

PSR: Uses pseudo-rapidity/phi coordinates.

LEGO: Draws a lego plot with hidden line removal.

LEGO1: Draws a lego plot with hidden surface removal.

LEGO2: Draws a lego plot using colors to show the cell contents.

SURF: Draws a surface plot with hidden line removal.

SURF1: Draws a surface plot with hidden surface removal.

SURF2: Draws a surface plot using colors to show the cell contents.

SURF3: Same as SURF with a contour view on the top.

SURF4: Draws a surface plot using Gouraud shading.

SURF5: Same as SURF3 but only the colored contour is drawn. Used with option CYL, SPH or PSR, it allows to draw colored contours on a sphere, a cylinder or in a pseudo rapidly space. In Cartesian or polar coordinates, option SURF3 is used.

Example

   TH2F h2("h2","Histogram filled with random numbers",40,-4,4,40,-20,20);
   float px, py;
   for (int i = 0; i < 25000; i++) {
      gRandom->Rannor(px,py);
      h2.Fill(px,5*py);
   }
   h2.Draw("LEGO1");

Figure: Histogram drawn with Draw(“LEGO1”).

   h2.Draw("LEGO1 POL");

Figure: Histogram drawn with Draw(“LEGO1 POL”).

Drawing options for 1-D histogram classes

For detailed information on the drawing options for 1-D histogram classes, refer to THistPainter.

AH: Draws the histogram, but not the axis labels and tick marks.

B: Draws a bar chart.

C: Draws a smooth curve through the histogram bins.

E: Draws error bars.

E0: Draws error bars including bins with 0 contents.

E1: Draws error bars with perpendicular lines at the edges

E2: Draws error bars with rectangles.

E3: Draws a filled area through the end points of the vertical error bars.

E4: Draws a smoothed filled area through the end points of the error bars.

L: Draws a line through the bin contents.

P: Draws a (poly)marker at each bin using the histogram’s current marker style.

P0: Draws current marker at each bin including empty bins.

PIE: Draws a pie chart.

H: Draws a histogram with a * at each bin.

LF2: Draws a histogram with option L but with a filled area. L also draws a filled area if the histogram fill color is set but the fill area corresponds to the histogram contour.

9: Forces a histogram to be drawn in high resolution mode. By default, the histogram is drawn in low resolution in case the number of bins is greater than the number of pixels in the current pad.

][: Draws a histogram without the vertical lines for the first and the last bin. Use it, when superposing many histograms on the same picture.

Drawing options for 2-D histogram classes

For detailed information on the drawing options for 2-D histogram classes, refer to THistPainter .

By default, 2-D histograms are drawn as scatter plots.

ARR: Arrow mode. Shows gradient between adjacent cells.

BOX: Draws a box for each cell with surface proportional to contents.

BOX1: A sunken button is drawn for negative values, a raised one for positive values

COL: Draws a box for each cell with a color scale varying with contents.

COLZ: Same as COL with a drawn color palette.

CONT: Draws a contour plot (same as CONT0).

CONTZ: Same as CONT with a drawn color palette.

CONT0: Draws a contour plot using surface colors to distinguish contours.

CONT1: Draws a contour plot using line styles to distinguish contours.

CONT2: Draws a contour plot using the same line style for all contours.

CONT3: Draws a contour plot using fill area colors.

CONT4: Draws a contour plot using surface colors (SURF2 option at theta = 0).

CONT5: Uses Delaunay triangles to compute the contours.

LIST: Generates a list of TGraph objects for each contour.

FB: To be used with LEGO or SURFACE, suppresses the Front-Box.

BB: To be used with LEGO or SURFACE, suppresses the back-box.

A: To be used with LEGO or SURFACE, suppresses the axis.

SCAT: Draws a scatter-plot (default).

SPEC: Uses the TSpectrum2Painter tool for drawing.

TEXT: Draws bin contents as text (format set via gStyle->SetPaintTextFormat).

TEXTnn: Draws bin contents as text at angle nn (0 < nn < 90).

[cutg]: Draws only the sub-range selected by the TCutG name “cutg”.

Z: The Z option can be specified with the options: BOX, COL, CONT, SURF, and LEGO to display.

Drawing options for 3-D histogram classes

For detailed information on the drawing options for 3-D histogram classes, refer to THistPainter .

By default, 3-D histograms are drawn as scatter plots.

BOX: Draws a box for each cell with volume proportional to the contents.

LEGO: Same as BOX.

ISO: Draws an iso surface.

FB: Suppresses the front-box.

BB: Suppresses the back-box.

A: Suppresses the axis.

Drawing a histogram with error bars

You can draw a histogram with error bars.

Example

   TH1F h1("h1","Histogram from a Gaussian",100,-3,3);
   h1.FillRandom("gaus",10000);
   h1.Draw();

A canvas with the histogram is displayed.

  • Click View, and then click Editor.

  • Click on the histogram.

In the Style tab, you can select the error bars to displayed for the histogram.

Figure: Selection of error bars for a histogram.

  • Select Simple.

The size of the error bars is equal to the square root of the number of events in the histogram.

Figure: Error bars for a histogram.

Instead of using the Editor, you also can simply draw the error bars by:

   h1.Draw("e");

Example: Histogramming a data analysis

In Example: Using a ROOT macro for data analysis was shown how to create a ROOT macro for analyzing a tree in a ROOT file.

Here it is shown, how to create a histogram for a variable hPosX for this data analysis.

Example

A 1-D histogram TH1F is created for the X position of particles (hPosX).

#include "TFile.h"
#include "TTree.h"
#include "TBranch.h"
#include "TH1F.h"

const Int_t kMaxfParticles = 1293;

void AnalyzeTree()
{
// Variables used to store the data.

// Sum of data size (in bytes) of all events.
   Int_t totalSize = 0;

// Size of the current event.
   Int_t     eventSize = 0;

// X position of the particles.
   TH1F     *hPosX;

// List of branches.
   TBranch  *nParticlesBranch;
   TBranch  *particlesPosXBranch;
   TBranch  *particlesMomentumBranch;

// Declaration of leaf types
   Int_t nParticles;
   Double_t  particlesPosX[kMaxfParticles];
   Double_t  particlesMomentum[kMaxfParticles];

// Open the ROOT file.
   TFile *f = TFile::Open("http://root.cern/files/introtutorials/eventdata.root");
   if (f == 0) {

// If we cannot open the file, print an error message and return immediately.
      printf("Error: cannot open http://root.cern/files/introtutorials/eventdata.root!\n");
      return;
   }

// Get a pointer to the tree.
   TTree *tree = (TTree *)f->Get("EventTree");

// To use SetBranchAddress() with simple types (e.g. double, int) instead of objects (e.g. std::vector<Particle>).
   tree->SetMakeClass(1);

// Connect the branches with their member variables.
   tree->SetBranchAddress("fParticles", &nParticles, &nParticlesBranch);
   tree->SetBranchAddress("fParticles.fPosX", particlesPosX, &particlesPosXBranch);
   tree->SetBranchAddress("fParticles.fMomentum", particlesMomentum, &particlesMomentumBranch);

// Create the TH1F histogram.
   hPosX = new TH1F("hPosX", "Position in X", 20, -5, 5);

// Enable bin errors.
   hPosX->Sumw2();

   Long64_t nentries = tree->GetEntries();
   for (Long64_t i=0;i<nentries;i++) {

// We only need the number of particles ...
      nParticlesBranch->GetEntry(i);

// ... and their position in X...
      particlesPosXBranch->GetEntry(i);

// ... and their momentum.
      particlesMomentumBranch->GetEntry(i);

// Do the actual analysis.
      for (int iParticle = 0; iParticle < nParticles; ++iParticle) {
         if (particlesMomentum[iParticle] > 40.0)
            hPosX->Fill(particlesPosX[iParticle]);
      }
   }

// Fit the histogram.
   hPosX->Fit("pol2");

// Draw the histogram.
   hPosX->Draw();
}

Profile histograms

Profile histograms are used to display the mean value of Y and its error for each bin in X.

When you fill a profile histogram with the TProfile.Fill() method:

  • H[j] contains for each bin j the sum of the y values for this bin.

  • L[j] contains the number of entries in the bin j.

  • e[j] or s[j] will be the resulting error depending on the selected option.

The following formulae show the cumulated contents (capital letters) and the values displayed by the printing or plotting routines (small letters) of the elements for bin J.

E[j] = sum Y**2
L[j] = number of entries in bin J
H[j] = sum Y
h[j] = H[j] / L[j]
s[j] = sqrt[E[j] / L[j] - h[j]**2]
e[j] = s[j] / sqrt[L[j]]

The displayed bin content for bin J of a TProfile is always h(J). The corresponding bin error is by default e(J). In case the option s is used (in the constructor or by calling TProfile::BuildOptions) the displayed error is s(J).

In the special case where s[j] is zero, when there is only one entry per bin, e[j] is computed from the average of the s[j] for all bins. This approximation is used to keep the bin during a fit operation.

Example

{
  auto c1 = new TCanvas("c1","Profile histogram example",200,10,700,500);
  auto hprof  = new TProfile("hprof","Profile of pz versus px",100,-4,4,0,20);
  Float_t px, py, pz;
  for ( Int_t i=0; i<25000; i++) {
    gRandom->Rannor(px,py);
    pz = px*px + py*py;
    hprof->Fill(px,pz,1);
  }
  hprof->Draw();
}

Figure: A profile histogram example.