Rivet is hosted by Hepforge, IPPP Durham

Histogramming in Rivet

Histogramming in Rivet is currently handled via the YODA data analysis interfaces: see https://yoda.hepforge.org/ for more information on YODA.

Booking histograms

Most of the time you will want to book histograms from within an Analysis. Rivet provides machinery to handle the mess of YODA factories behind the scenes via the Analysis::bookHisto1D(...) methods - see the API documentation for details. There are several ways to book histograms:

  • book evenly spaced bins in a range, by specifying the endpoints and the number of bins;
  • pass a specific std::vector of bin edges;
  • automatically book with the right bin edges based on the reference data file.

Any "official" Rivet analyses will use the latter method, and we recommend that you do so, too. If you are starting a new analysis, and the reference data is found in HepData (the SPIRES record will provide a link to "Durham Reaction Data"), then please contact us and we will provide you with an automatically-dumped reference data file.

The bookHisto1D methods all return a YODA::Histo1D* pointer: this should be assigned to a member variable of the same type in your Analysis derived class. The path to each histogram will automatically be /MY_ANALYSIS_NAME/HISTO_NAME.

Tell me more about this auto-booking thing…

Maybe this isn't so obvious after all! The idea is that most Rivet analyses should be comparable with experimental data, such as that in the HepData database. Otherwise, it's not so much use for tuning or validation and can only be used for regression testing. While this is useful, we expect that most analyses will be written to compare with experiment.

Since the MC and ref data must have the same binnings to be meaningfully compared, and since encoding long lists of bin edges into your code is annoying, error-prone and ugly, our booking system will use the reference data files as a template from which to book the MC histogram. The reference files will be searched for in the component paths listed in the RIVET_REF_PATH environment variable, in the data directory of the Rivet release, and in the current directory, in that order. The Rivet data directory, after installation, is usually found in $prefix/share/Rivet. The internal path to the reference histograms is the same as for the MC histograms, but all inside a top-level virtual directory called "REF". For example, MC histo /MY_ANALYSIS/my-histo can be auto-booked from reference histo /REF/MY_ANALYSIS/my-histo

For those histograms dumped from HepData, the histogram naming system is a little strange: Every 1D histogram that you might want to make is stored in HepData as a combination of an x-axis and a y-axis for a given dataset --- HepData datasets can have multiple axes of either kind, so that e.g. several measurements binned the same way can be encoded as multiple y-axes on a single x-axis. So, armed with the dataset, x-axis and y-axis IDs, if you call

// In MyAnalysis class definition:
Histo1D* _myHisto;

// In implementation:
void MyAnalysis::initialize() {
  ...
  _myHisto = bookHisto1D(1, 1, 2, "MyDbn - HepData dataset 1, x-axis 1 and y-axis 2");
  ...
}

then you'll get back a YODA Histo1D* with the right binning. You can also book an IProfile1D*, IDataPointSet* in the same way.

If you're developing an analysis for a paper which has a HepData record, and you want to get hold of the YODA file, please ask the Rivet developers to make a copy of the file for you. If your paper of choice isn't in HepData, then please contact either the Rivet or HepData admins and we'll try to get your data into the system. Please encourage your experiment to submit published data to HepData --- good coverage of experimental measurements is essential for generator tuning to be trustworthy (and submission of published data to the community archive is anyway good practice.)

Filling histograms

Histograms are usually filled in your analysis' analyze() method, using the normal YODA fill() method, e.g.

const double weight = event.weight();
_histMyDistribution->fill(value, weight);

Remember to use the event weight!

Normalizing histograms

We've provided a normalizing method Histo1D::normalize(double normto=1.0, bool includeoverflows=true), so you don't have to write lots of lines of repetitive and fragile code.

Saving histograms to file

The rivet and rivetgun automatically save all the histograms known to the YODA analysis system to file at the end of the run (this even works when the process is killed). If you are linking Rivet into your own code, you will need to call the AnalysisHandler::commitData() method.

Using saved histograms

Once you have a histogram file, what to do with it?

YODA format

The YODA data format is outlined on the YODA wiki: https://yoda.hepforge.org/trac/wiki/DataFormat.

Rivet supplies several scripts which can be used for comparing and plotting histograms from YODA files. Rivet comes with three commands --- rivet-mkhtml, compare-histos and make-plots --- for comparing and plotting data files. These commands produce nice comparison plots of publication quality from the YODA files.

The high level program rivet-mkhtml will automatically create a plot webpage from the given YODA files. It searches for reference data automatically and uses the other two commands internally. Example:

rivet-mkhtml withUE.yoda:'Title=With UE' withoutUE.yoda:'LineColor=blue'

Run rivet-mkhtml --help to find out about all features and options.

Plotting options will be taken from *.plot files installed in Rivet's share directory. These contain plotting instructions according to the make-plots syntax as documented in http://rivet.hepforge.org/make-plots.html . Such files can also be written for any plugin analysis and will be found if they are in the RIVET_ANALYSIS_PATH.

You can also run the other two commands separately:

rivet-cmphistos will accept a number of YODA files as input (ending in .yoda), identify which plots are available in them, and combine the MC and reference plots appropriately into a set of plot data files ending with .dat. More options are described by running rivet-cmphistos --help.

Incidentally, the reference files for each Rivet analysis are to be found in the installed Rivet shared data directory, installdir/share/Rivet. You can find the location of this by using the rivet-config command: rivet-config --datadir

You can plot the created data files using the make-plots command:

make-plots --pdf *.dat

The --pdf flag makes the output plots in PDF format: by default the output is in postscript (.ps), and flags for conversion to EPS and PNG are also available.

Note that the plotting tools internally use LaTeX for drawing, and for very complex plots it might sometimes fail with an error message like "TeX memory exceeded" (or "DVI file can't be opened"). In such a case it is recommended to increase the allowed TeX memory size as described e.g. in the pgfplots manual in Section 6.2.

Last modified 2 years ago Last modified on Jul 30, 2015, 5:26:59 PM