9.5. g4tools

9.5. g4tools
	Chapter 9. Analysis

g4tools is a "namespace protected" part of inlib and exlib which is of some interest for Geant4, mainly the histograms, the ntuples and the code to write them at the ROOT, AIDA XML and CSV file formats. The idea of g4tools is to cover, with a very light and easy to install package, what is needed to do analysis in a "Geant4 batch program".

As g4tools is distributed through Geant4 and in order to avoid potential namespace clashes with other codes that use the inlib/exlib to do Geant4 visualization (as for the g4view application or some of the exlib examples), the inlib and exlib namespaces had been automatically changed to tools in the g4tools distribution. Since in principle Geant4 users will not have to deal directly with the g4tools classes, but will manipulate histograms and ntuples through the G4AnalysisManager, we are not going to extensively document the g4tools classes here. Interested people are encouraged to go at the inlib/exlib web pages for that (see inlib/exlib site ).

9.5.1. g4tools package

9.5.1.1. g4tools code is pure header

As explained in inlib/exlib, the code found in g4tools is "pure header". This comes from the need to have an easy way to build applications, as the ioda one, from smartphone, passing by tablets and up to various desktops (UNIX and Windows). For example, if building an application targeted to the Apple AppStore and GooglePlay, the simplest way is to pass through Xcode and the Android make system (or Eclipse), and having not to build libraries simplifies a lot the handling of all these IDEs for the same application. A fallback of that is that the installation of g4tools (if not using the one coming with Geant4) is straightforward, you simply unzip the file containing the source code! To build an application using g4tools, as for inlib/exlib, you simply have to declare to your build system the "-I" toward the unfolded directory and do "Build and Run".

9.5.1.2. g4tools test

g4tools comes with test programs of its own that may be useful in case of problems (for example porting on a not yet covered platform). You can build and run them with :

     UNIX> <get g4tools.zip>
     UNIX> <unzip g4tools.zip>
     UNIX> cd g4tools/test/cpp
     UNIX> ./build
     UNIX> ./tools_test_histo
     UNIX> ./tools_test_wroot
     UNIX> etc...

and on Windows :

      DOS> <setup VisualC++ so that CL.exe is in your PATH>
      DOS> <get g4tools.zip>
      DOS> <unzip g4tools.zip> (you can use the unzip.exe of CYGWIN)
      DOS> cd g4tools\test\cpp
      DOS> .\build.bat
      DOS> .\tools_test_histo.exe
      DOS> .\tools_test_wroot.exe
      DOS> etc...

9.5.1.3. g4tools in Geant4

The g4tools header files are distributed in the Geant4 source in the source/analysis/include/tools directory and in the Geant4 installation, they are installed in include/tools directory. The g4tools test programs, included only in Geant4 development versions, can be downloaded with the g4tools-[version].zip file from the inexlib download page).

While the Geant4 analysis manager provides the methods for booking and filling the g4tools objects, it does not interface all public functions. Users can access the g4tools objects (see Section 9.2.3.4) and use the g4tools API described in the next section to get the needed informations.

9.5.2. User API

We describe here some of the public methods potentially seen by a user doing analysis.

9.5.2.1. Booking and filling

    h1d(const std::string& title,unsigned int Xnumber,double Xmin,double Xmax);
    h1d(const std::string& title,const std::vector<double>& edges);

    bool fill(double X,double Weight = 1);

example :

    #include <tools/histo/h1d>
    #include <tools/randd>
    ...
    tools::histo::h1d h("Gauss",100,-5,5);
    tools::rgaussd rg(1,2);
    for(unsigned int count=0;count<entries;count++) h.fill(rg.shoot(),1.4);

9.5.2.2. Mean and rms

    tools::histo::h1d h("Gauss",100,-5,5);
    ...
    std::cout << " mean " << h.mean() << ", rms " << h.rms() << std::endl;

9.5.2.3. Bin infos

When doing a :

    bool fill(double X,double Weight = 1);

the histogram class maintains, for each bin, the number of entries, the sum of weights that we can note "Sw", the sum of W by W "Sw2", the sum of X by Weight "Sxw", the sum of X by X by W "Sx2w". Then bin method names reflect these notations, for example to get the 50 bin sum of X*X*W :

    double Sx2w = h.bin_Sx2w(50);

and the same for the other sums :

    double Sw = h.bin_Sw(50);
    double Sw2 = h.bin_Sw2(50);
    double Sxw = h.bin_Sxw(50);
    unsigned int n = h.bin_entries(50);

You can have also all infos on all bins with:

    tools::histo::h1d h(...);
    ...
    const std::vector<unsigned int>& _entries = h.bins_entries();
    const std::vector<double>& _bins_sum_w = h.bins_sum_w();
    const std::vector<double>& _bins_sum_w2 = h.bins_sum_w2();
    const std::vector< std::vector<double> >& _bins_sum_xw = h.bins_sum_xw();
    const std::vector< std::vector<double> >& _bins_sum_x2w = h.bins_sum_x2w();

for example to dump bin 50 of an histo booked with 100 bins:

    std::cout << "entries[50] = " << _entries[50] << std::endl;
    std::cout << "  sum_w[50] = " << _bins_sum_w[50] << std::endl;
    std::cout << " sum_w2[50] = " << _bins_sum_w2[50] << std::endl;
    std::cout << " sum_xw[50] = " << _bins_sum_xw[50][0] << std::endl;   //0 = xaxis
    std::cout << "sum_x2w[50] = " << _bins_sum_x2w[50][0] << std::endl;  //0 = xaxis

(Take care that the [0] entries in the upper vectors are for the "underflow bin" and the last one is for the "overflow bin").

9.5.2.4. All data

You can get all internal data of an histo through the histo_data class:

    const tools::histo::h1d::hd_t& hdata = h.dac();  //dac=data access.

and then, for example, find back the bins infos with:

    const std::vector<unsigned int>& _entries = hdata.m_bin_entries;
    const std::vector<double>& _bins_sum_w = hdata.m_bin_Sw;
    const std::vector<double>& _bins_sum_w2 = hdata.m_bin_Sw2;
    const std::vector< std::vector<double> >& _bins_sum_xw = hdata.m_bin_Sxw;
    const std::vector< std::vector<double> >& _bins_sum_x2w = hdata.m_bin_Sx2w;
    // dump bin 50 :
    std::cout << "entries[50] = " << _entries[50] << std::endl;
    std::cout << "  sum_w[50] = " << _bins_sum_w[50] << std::endl;
    std::cout << " sum_w2[50] = " << _bins_sum_w2[50] << std::endl;
    std::cout << " sum_xw[50] = " << _bins_sum_xw[50][0] << std::endl;   //0 = xaxis
    std::cout << "sum_x2w[50] = " << _bins_sum_x2w[50][0] << std::endl;  //0 = xaxis

See the tools/histo/histo_data class for all internal fields.

9.5.2.5. Projections

From a 2D histo, you can get the x projection with:

    tools::histo::h1d* projection = tools::histo::projection_x(h2d,"ProjX");
    ...
    delete projection;

See test/cpp/histo.cpp for example code. Other slicing and projection methods are:

  // h2d -> h1d. (User gets ownership of the returned object).
  h1d* slice_x(const h2d&,int y_beg_ibin,int y_end_ibin,const std::string& title);
  h1d* projection_x(const h2d&,const std::string& title);
  h1d* slice_y(const h2d&,int x_beg_ibin,int x_end_ibin,const std::string& title);
  h1d* projection_y(const h2d&,const std::string& title);
  // h2d -> p1d. (User gets ownership of the returned object).
  p1d* profile_x(const h2d&,int y_beg_ibin,int y_end_ibin,const std::string& title);
  p1d* profile_x(const h2d&,const std::string&);
  p1d* profile_y(const h2d&,int x_beg_ibin,int x_end_ibin,const std::string& title);
  p1d* profile_y(const h2d&,const std::string& title);
  // h3d -> h2d. (User gets ownership of the returned object).
  h2d* slice_xy(const h3d&,int z_beg_ibin,int z_end_ibin,const std::string& title);
  h2d* projection_xy(const h3d&,const std::string& title);
  h2d* slice_yz(const h3d&,int x_beg_ibin,int x_end_ibin,const std::string& title);
  h2d* projection_yz(const h3d&,const std::string& title);
  h2d* slice_xz(const h3d&,int y_beg_ibin,int y_end_ibin,const std::string& title);
  h2d* projection_xz(const h3d&,const std::string& title);


9.4. Accumulables		Chapter 10. Examples